From 1abc7ce8f059aadb60466fe9400913c55bd90b92 Mon Sep 17 00:00:00 2001
From: rroverin <rroveri@nvidia.com>
Date: Wed, 12 Aug 2026 18:32:57 +0200
Subject: [PATCH 01/48] feat(models): add Nemotron 3.5 Lightning 30B-A3B to
 NVIDIA NIM picker

---
 hermes_cli/models.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/hermes_cli/models.py b/hermes_cli/models.py
index 3a809c5f1a..e2dc50c3cb 100644
--- a/hermes_cli/models.py
+++ b/hermes_cli/models.py
@@ -341,6 +341,7 @@ _PROVIDER_MODELS: dict[str, list[str]] = {
         # NVIDIA flagship reasoning models
         "nvidia/nemotron-3-ultra-550b-a55b",
         "nvidia/nemotron-3-super-120b-a12b",
+        "nvidia/nemotron-3.5-lightning-30b-a3b",
         "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning",
         # Third-party agentic models hosted on build.nvidia.com
         # (map to OpenRouter defaults — users get familiar picks on NIM)

From 48c1eefa2677419a5b80967f708eb1098e415709 Mon Sep 17 00:00:00 2001
From: Gille <4317663+helix4u@users.noreply.github.com>
Date: Mon, 17 Aug 2026 21:43:52 -0600
Subject: [PATCH 02/48] fix(desktop): repair missing Windows runtime

---
 apps/desktop/electron/main.ts                 | 24 ++++++-----
 .../electron/windows-hermes-path.test.ts      | 43 ++++++++++++++-----
 apps/desktop/electron/windows-hermes-path.ts  | 40 +++++++++--------
 3 files changed, 68 insertions(+), 39 deletions(-)

diff --git a/apps/desktop/electron/main.ts b/apps/desktop/electron/main.ts
index 06a1eb9181..51607c1397 100644
--- a/apps/desktop/electron/main.ts
+++ b/apps/desktop/electron/main.ts
@@ -3707,16 +3707,20 @@ async function handOffWindowsBootstrapRecovery(reason) {
   const venvHermes = path.join(venvBin, IS_WINDOWS ? 'hermes.exe' : 'hermes')
   const venvPython = path.join(venvBin, IS_WINDOWS ? 'python.exe' : 'python')
 
-  // Choose the gentle in-place --update when ANY real-install signal is present,
-  // not just the `hermes.exe` console-script shim. That shim is generated at the
-  // END of venv setup and is absent in exactly the interrupted/quarantined states
-  // this recovery exists to heal — gating on it alone forced the destructive
-  // --repair (full venv recreate) and drove reinstall loops. The venv interpreter
-  // and the bootstrap-complete marker are present earlier and are better signals.
-  const haveRealInstall =
-    fileExists(venvPython) || fileExists(venvHermes) || fileExists(path.join(updateRoot, '.hermes-bootstrap-complete'))
-
-  const updaterArgs = chooseUpdaterArgs(haveRealInstall, branch)
+  // The updater invokes the venv's Hermes launcher, which in turn requires the
+  // venv interpreter. A bootstrap-complete marker proves only that setup once
+  // finished; it can outlive a manually removed or quarantined venv. Sending a
+  // marker-only install through --update dead-ends at "Could not find the hermes
+  // CLI" instead of rebuilding the runtime, so only a runnable pair gets the
+  // gentle update path. Partial or missing runtimes go through full repair.
+  const updaterArgs = chooseUpdaterArgs(
+    {
+      hasBootstrapMarker: fileExists(path.join(updateRoot, '.hermes-bootstrap-complete')),
+      hasVenvHermes: fileExists(venvHermes),
+      hasVenvPython: fileExists(venvPython)
+    },
+    branch
+  )
 
   await releaseBackendLockForUpdate(updateRoot)
 
diff --git a/apps/desktop/electron/windows-hermes-path.test.ts b/apps/desktop/electron/windows-hermes-path.test.ts
index 778042b278..76e4d0ac50 100644
--- a/apps/desktop/electron/windows-hermes-path.test.ts
+++ b/apps/desktop/electron/windows-hermes-path.test.ts
@@ -5,9 +5,9 @@
 //   1. buildPathExtCandidates() — PATHEXT extensions must be tried BEFORE the
 //      empty extension, or an extensionless Git-Bash `hermes` shim shadows
 //      the real hermes.cmd/hermes.exe.
-//   2. chooseUpdaterArgs() — must gate on haveRealInstall (any real-install
-//      signal), not just the hermes.exe console-script shim, or healthy
-//      installs get forced into a destructive --repair.
+//   2. chooseUpdaterArgs() — must distinguish a runnable updater from stale
+//      install provenance. The bootstrap marker can outlive the venv, and a
+//      partial venv cannot run the updater; those states require --repair.
 //   3. resolveVenvHermesCommand() — must probe the venv python via
 //      canImportHermesCli() before trusting it, or a broken venv gets
 //      re-selected forever instead of falling through to bootstrap.
@@ -45,17 +45,40 @@ test('buildPathExtCandidates: non-Windows only tries the bare name', () => {
   assert.deepEqual(buildPathExtCandidates(undefined, false), [''])
 })
 
-test('chooseUpdaterArgs: gentle --update when a real-install signal is present', () => {
-  assert.deepEqual(chooseUpdaterArgs(true, 'main'), ['--update', '--branch', 'main'])
+test('chooseUpdaterArgs: gentle --update when both updater runtime files exist', () => {
+  assert.deepEqual(
+    chooseUpdaterArgs({ hasBootstrapMarker: true, hasVenvHermes: true, hasVenvPython: true }, 'main'),
+    ['--update', '--branch', 'main']
+  )
 })
 
-test('chooseUpdaterArgs: destructive --repair only when NO real-install signal is present', () => {
-  assert.deepEqual(chooseUpdaterArgs(false, 'main'), ['--repair', '--branch', 'main'])
+test('chooseUpdaterArgs: marker-only install uses --repair when the venv is gone', () => {
+  assert.deepEqual(
+    chooseUpdaterArgs({ hasBootstrapMarker: true, hasVenvHermes: false, hasVenvPython: false }, 'main'),
+    ['--repair', '--branch', 'main']
+  )
 })
 
-test('chooseUpdaterArgs: passes the branch through unchanged in both cases', () => {
-  assert.deepEqual(chooseUpdaterArgs(true, 'release/1.2'), ['--update', '--branch', 'release/1.2'])
-  assert.deepEqual(chooseUpdaterArgs(false, 'release/1.2'), ['--repair', '--branch', 'release/1.2'])
+test('chooseUpdaterArgs: partial updater runtimes use --repair', () => {
+  assert.deepEqual(
+    chooseUpdaterArgs({ hasBootstrapMarker: true, hasVenvHermes: false, hasVenvPython: true }, 'main'),
+    ['--repair', '--branch', 'main']
+  )
+  assert.deepEqual(
+    chooseUpdaterArgs({ hasBootstrapMarker: true, hasVenvHermes: true, hasVenvPython: false }, 'main'),
+    ['--repair', '--branch', 'main']
+  )
+})
+
+test('chooseUpdaterArgs: passes the branch through unchanged in both modes', () => {
+  assert.deepEqual(
+    chooseUpdaterArgs({ hasBootstrapMarker: false, hasVenvHermes: true, hasVenvPython: true }, 'release/1.2'),
+    ['--update', '--branch', 'release/1.2']
+  )
+  assert.deepEqual(
+    chooseUpdaterArgs({ hasBootstrapMarker: false, hasVenvHermes: false, hasVenvPython: false }, 'release/1.2'),
+    ['--repair', '--branch', 'release/1.2']
+  )
 })
 
 function makeDeps(overrides: Partial<Parameters<typeof resolveVenvHermesCommand>[2]> = {}) {
diff --git a/apps/desktop/electron/windows-hermes-path.ts b/apps/desktop/electron/windows-hermes-path.ts
index 6f3542853e..f94d4b2c39 100644
--- a/apps/desktop/electron/windows-hermes-path.ts
+++ b/apps/desktop/electron/windows-hermes-path.ts
@@ -11,12 +11,11 @@
  *      hermes.cmd/hermes.exe; the shim then failed the --version probe and
  *      the desktop fell through to a spurious bootstrap/repair. The fix:
  *      PATHEXT extensions first, empty extension LAST.
- *   2. chooseUpdaterArgs() — handOffWindowsBootstrapRecovery() chose
- *      --update vs the destructive --repair by checking ONLY
- *      venv\Scripts\hermes.exe (the console-script shim, written at the END
- *      of venv setup and absent in interrupted states), so it escalated to a
- *      full venv recreate even on healthy installs. The fix: gate on ANY
- *      real-install signal, not just the shim.
+ *   2. chooseUpdaterArgs() — handOffWindowsBootstrapRecovery() must separate
+ *      install provenance from updater viability. A bootstrap-complete marker
+ *      can outlive a deleted venv, while the updater needs BOTH the venv Python
+ *      and Hermes launcher. Marker-only or partial runtimes must use --repair;
+ *      only a runnable pair can use --update.
  *   3. resolveVenvHermesCommand() — unwrapWindowsVenvHermesCommand() returned
  *      the venv python with NO runtime probe (bypassing the caller's
  *      --version check too), so a venv broken mid-update (e.g. missing
@@ -61,23 +60,26 @@ export function buildPathExtCandidates(pathext: string | undefined, isWindows: b
 }
 
 /**
- * Choose the Windows bootstrap-recovery updater invocation: the gentle
- * in-place --update when ANY real-install signal is present, the
- * destructive --repair (full venv recreate) otherwise.
+ * Choose the Windows bootstrap-recovery invocation. The gentle in-place
+ * updater can only start when both pieces of its runtime contract exist: the
+ * venv Python interpreter and the Hermes launcher that drives `hermes update`.
+ * A bootstrap-complete marker proves install provenance, not current runtime
+ * usability, and may remain after the venv is removed or quarantined.
  *
- * haveRealInstall must be computed by the caller from ALL real-install
- * signals (venv python interpreter, venv hermes shim, bootstrap-complete
- * marker) — gating on just the hermes.exe console-script shim alone is the
- * regression this function's callers must avoid: that shim is written at
- * the END of venv setup and is absent in exactly the interrupted/quarantined
- * states this recovery exists to heal.
- *
- * @param {boolean} haveRealInstall
+ * @param {BootstrapRecoverySignals} signals
  * @param {string} branch
  * @returns {string[]} updater argv, e.g. ['--update', '--branch', 'main'].
  */
-export function chooseUpdaterArgs(haveRealInstall: boolean, branch: string): string[] {
-  return haveRealInstall ? ['--update', '--branch', branch] : ['--repair', '--branch', branch]
+export interface BootstrapRecoverySignals {
+  hasBootstrapMarker: boolean
+  hasVenvHermes: boolean
+  hasVenvPython: boolean
+}
+
+export function chooseUpdaterArgs(signals: BootstrapRecoverySignals, branch: string): string[] {
+  const canRunUpdater = signals.hasVenvHermes && signals.hasVenvPython
+
+  return canRunUpdater ? ['--update', '--branch', branch] : ['--repair', '--branch', branch]
 }
 
 /**

From ca20ee90bba57115421e54e121073d1169b72b77 Mon Sep 17 00:00:00 2001
From: xxxigm <tuancanhnguyen706@gmail.com>
Date: Wed, 19 Aug 2026 20:10:18 +0700
Subject: [PATCH 03/48] fix(desktop): wrap toast titles so long errors stay
 readable

AlertTitle clamps to one line, so Desktop error toasts hide the rest of the message behind an ellipsis. Override that clamp, let the title wrap, and cap height so a huge error scrolls instead of covering the chat.
---
 apps/desktop/src/components/notifications.tsx | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/apps/desktop/src/components/notifications.tsx b/apps/desktop/src/components/notifications.tsx
index 6406032364..788873c531 100644
--- a/apps/desktop/src/components/notifications.tsx
+++ b/apps/desktop/src/components/notifications.tsx
@@ -119,7 +119,7 @@ function TopCenterStack({
       aria-label={copy.region}
       className={cn(
         REGION_BASE,
-        'left-1/2 top-[calc(var(--titlebar-height,34px)+0.75rem)] w-[min(32rem,calc(100%-2rem))] -translate-x-1/2 flex-col'
+        'left-1/2 top-[calc(var(--titlebar-height,34px)+0.75rem)] w-[min(40rem,calc(100%-2rem))] -translate-x-1/2 flex-col'
       )}
       role="region"
     >
@@ -187,6 +187,13 @@ function renderMessage(message: string, accent?: string): ReactNode {
   )
 }
 
+// AlertTitle defaults to a single-line clamp. Toast errors are often a full
+// sentence, so the toast wraps — then caps height and scrolls instead of
+// growing down the chat or clipping with an ellipsis.
+export function toastTitleClassName() {
+  return 'col-start-auto line-clamp-none max-h-[4.5em] overflow-y-auto overscroll-contain whitespace-normal wrap-break-word'
+}
+
 function NotificationItem({ notification }: { notification: AppNotification }) {
   const styles = tone[notification.kind]
   const Icon = styles.icon
@@ -213,9 +220,13 @@ function NotificationItem({ notification }: { notification: AppNotification }) {
         <Icon className={styles.iconClass} style={iconStyle} />
       )}
       <div className="col-start-2 min-w-0">
-        {notification.title && <AlertTitle className="col-start-auto">{notification.title}</AlertTitle>}
+        {notification.title && (
+          <AlertTitle className={toastTitleClassName()} title={notification.title}>
+            {notification.title}
+          </AlertTitle>
+        )}
         <AlertDescription className="col-start-auto">
-          <p className="m-0">{renderMessage(notification.message, accent)}</p>
+          <p className="m-0 wrap-break-word">{renderMessage(notification.message, accent)}</p>
           {notification.meta && <p className="m-0 text-xs text-muted-foreground tabular-nums">{notification.meta}</p>}
           {hasDetail && <NotificationDetail detail={notification.detail || ''} />}
           {notification.action && (

From ab6e7b93da55f216d4816c4002672585c607f148 Mon Sep 17 00:00:00 2001
From: xxxigm <tuancanhnguyen706@gmail.com>
Date: Wed, 19 Aug 2026 20:10:18 +0700
Subject: [PATCH 04/48] test(desktop): keep long toast titles readable

Cover the wrap override and height cap so a one-line clamp cannot hide the rest of an error toast again.
---
 .../src/components/notifications.test.tsx     | 50 +++++++++++++++++++
 1 file changed, 50 insertions(+)
 create mode 100644 apps/desktop/src/components/notifications.test.tsx

diff --git a/apps/desktop/src/components/notifications.test.tsx b/apps/desktop/src/components/notifications.test.tsx
new file mode 100644
index 0000000000..5c345ce5ea
--- /dev/null
+++ b/apps/desktop/src/components/notifications.test.tsx
@@ -0,0 +1,50 @@
+import { cleanup, render, screen } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import { I18nProvider } from '@/i18n'
+import { clearNotifications, notify } from '@/store/notifications'
+
+import { NotificationStack, toastTitleClassName } from './notifications'
+
+const LONG_TITLE = 'This turn is no longer in server history (it may have been compressed away).'
+const DETAIL = 'target user message is no longer in session history'
+
+describe('toast titles', () => {
+  beforeEach(() => {
+    clearNotifications()
+  })
+
+  afterEach(() => {
+    cleanup()
+    clearNotifications()
+  })
+
+  it('drops the one-line clamp so a long error title can wrap', () => {
+    const className = toastTitleClassName()
+
+    expect(className).toMatch(/\bline-clamp-none\b/)
+    expect(className).not.toMatch(/\bline-clamp-1\b/)
+    expect(className).toMatch(/\bwhitespace-normal\b/)
+    expect(className).toContain('max-h-[4.5em]')
+    expect(className).toMatch(/\boverflow-y-auto\b/)
+  })
+
+  it('renders the full title and body instead of truncating them', () => {
+    notify({ kind: 'error', title: LONG_TITLE, message: DETAIL })
+
+    render(
+      <I18nProvider configClient={null} initialLocale="en">
+        <NotificationStack />
+      </I18nProvider>
+    )
+
+    const title = screen.getByText(LONG_TITLE)
+
+    expect(title.textContent).toBe(LONG_TITLE)
+    expect(title.getAttribute('title')).toBe(LONG_TITLE)
+    expect(title.className).toMatch(/\bline-clamp-none\b/)
+    expect(title.className).not.toMatch(/\bline-clamp-1\b/)
+    expect(title.className).toMatch(/\boverflow-y-auto\b/)
+    expect(screen.getByText(DETAIL)).toBeTruthy()
+  })
+})

From 0599b66de77e59daaad0d928010b23016feb6172 Mon Sep 17 00:00:00 2001
From: dcdexhome <dcdexhome@gmail.com>
Date: Wed, 19 Aug 2026 10:45:27 -0400
Subject: [PATCH 05/48] fix(desktop): stop re-entrant pin-sync reconcile from
 overflowing nanostores

The Desktop renderer crashes with `RangeError: Invalid array length` thrown
from `Array.push` inside nanostores' `notify()`. The shared `listenerQueue`
grows without bound because `reconcile()` is subscribed to BOTH `$sessions`
and `$pinnedSessionIds`, and `pullRemotePins()` mutates `$pinnedSessionIds`
(via `pinSession`/`unpinSession`), which fires `reconcile()` again
synchronously.

The existing `mirrored`/`pending`/`unconfirmed` fences only cover a *bounded*
single-toggle echo. They do not cover the *unbounded* oscillation that occurs
when two profiles share a session id with conflicting `pinned` flags (copied or
imported profile databases). A profile-blind pull then pins and unpins the same
durable id in one pass, re-firing `reconcile` forever until the queue overflows
and the renderer dies.

Two changes:

1. `rowsByPinId()` collapses the cross-profile session list to one
   authoritative row per durable pin id, preferring the active gateway's
   profile (the same tie-break `resolveLoadedRow` uses). `pullRemotePins()`
   iterates the deduped rows, so a conflicting duplicate can no longer pin then
   unpin the same id in a single pass.

2. A re-entrancy guard on `reconcile()` so a synchronous re-entry (from the
   `$pinnedSessionIds` listener firing during `pullRemotePins`) returns
   immediately instead of recursing.

Also fixes a latent TDZ `ReferenceError` in `session-unread.ts`: `isPlainRecord`
was declared after its first use through `persistentAtom`, so decoding a
persisted value could throw `Cannot access 'isPlainRecord' before
initialization`.

Regression tests cover the duplicate-id oscillation and the active-profile
tie-break.
---
 .../src/store/session-pin-sync.test.ts        | 30 +++++++++
 apps/desktop/src/store/session-pin-sync.ts    | 61 ++++++++++++++++++-
 apps/desktop/src/store/session-unread.ts      |  6 +-
 3 files changed, 93 insertions(+), 4 deletions(-)

diff --git a/apps/desktop/src/store/session-pin-sync.test.ts b/apps/desktop/src/store/session-pin-sync.test.ts
index 634b2b09be..d77d9d68d5 100644
--- a/apps/desktop/src/store/session-pin-sync.test.ts
+++ b/apps/desktop/src/store/session-pin-sync.test.ts
@@ -14,6 +14,7 @@ vi.mock('@/hermes', () => ({
 }))
 
 import { $pinnedSessionIds } from '@/store/layout'
+import { $activeGatewayProfile } from '@/store/profile'
 import { $sessions } from '@/store/session'
 
 import { resetSessionPinMirror, watchSessionPins } from './session-pin-sync'
@@ -290,4 +291,33 @@ describe('watchSessionPins remote pull', () => {
     expect($pinnedSessionIds.get()).toContain('failed')
     expect(patch).toHaveBeenCalledWith('failed', true, undefined)
   })
+
+  it('does not oscillate when two profiles share a session id with conflicting pins', async () => {
+    // The cross-profile list can hold the same durable id twice with opposite
+    // `pinned` flags (copied/imported profile DBs). A profile-blind pull would
+    // pin then unpin the id in one pass and re-fire reconcile forever,
+    // overflowing nanostores' listenerQueue (RangeError: Invalid array length).
+    $sessions.set([
+      row('shared', { profile: 'default', pinned: true }),
+      row('shared', { profile: 'hcoder', pinned: false })
+    ])
+    await flush()
+
+    // Deterministic: exactly one row wins, so the local set settles and no
+    // runaway re-entrant reconcile occurs.
+    expect($pinnedSessionIds.get()).toEqual(['shared'])
+  })
+
+  it('prefers the active gateway profile when duplicate ids disagree', async () => {
+    $activeGatewayProfile.set('hcoder')
+    $sessions.set([
+      row('shared', { profile: 'default', pinned: true }),
+      row('shared', { profile: 'hcoder', pinned: false })
+    ])
+    await flush()
+
+    // The active profile's row is authoritative, so the pin is dropped.
+    expect($pinnedSessionIds.get()).toEqual([])
+    $activeGatewayProfile.set('default')
+  })
 })
diff --git a/apps/desktop/src/store/session-pin-sync.ts b/apps/desktop/src/store/session-pin-sync.ts
index e22bf9433d..e299b72cb2 100644
--- a/apps/desktop/src/store/session-pin-sync.ts
+++ b/apps/desktop/src/store/session-pin-sync.ts
@@ -24,7 +24,9 @@
 import { setSessionPinnedRemote } from '@/hermes'
 import { onConnectionScopeChange } from '@/lib/connection-scoped'
 import { $pinnedSessionIds, pinSession, unpinSession } from '@/store/layout'
+import { $activeGatewayProfile, normalizeProfileKey } from '@/store/profile'
 import { $sessions, sessionMatchesStoredId, sessionPinId } from '@/store/session'
+import type { SessionInfo } from '@/types/hermes'
 
 // pin ids we've successfully PATCHed pinned=true this session.
 const mirrored = new Set<string>()
@@ -46,6 +48,39 @@ function profileFor(pinId: string): null | string | undefined {
   return $sessions.get().find(row => sessionMatchesStoredId(row, pinId))?.profile
 }
 
+/**
+ * One authoritative row per durable pin id. Session ids are only unique inside
+ * a profile, so the cross-profile list can legitimately hold two rows with the
+ * same `sessionPinId` but different `pinned` flags (copied/imported profile
+ * databases). Iterating both would pin then unpin the same id in one pass and
+ * re-fire `reconcile` forever — the runaway that overflows nanostores'
+ * listenerQueue. Collapse to a single row per id, preferring the active
+ * gateway's profile (the same tie-break `resolveLoadedRow` uses), so the pull
+ * is deterministic and never oscillates.
+ */
+function rowsByPinId(rows: readonly SessionInfo[]): Map<string, SessionInfo> {
+  const byId = new Map<string, SessionInfo>()
+  const gateway = normalizeProfileKey($activeGatewayProfile.get())
+
+  for (const row of rows) {
+    const pinId = sessionPinId(row)
+    const existing = byId.get(pinId)
+
+    if (!existing) {
+      byId.set(pinId, row)
+
+      continue
+    }
+
+    // Prefer the active gateway's profile; otherwise keep the first seen.
+    if (normalizeProfileKey(row.profile) === gateway && normalizeProfileKey(existing.profile) !== gateway) {
+      byId.set(pinId, row)
+    }
+  }
+
+  return byId
+}
+
 /** PATCH the flag, guarding reads against pages that predate the write. */
 function writePin(id: string, pinned: boolean, profile?: null | string): Promise<void> {
   unconfirmed.set(id, { at: Date.now(), value: pinned })
@@ -78,7 +113,7 @@ function writePin(id: string, pinned: boolean, profile?: null | string): Promise
 function pullRemotePins(): void {
   const local = new Set($pinnedSessionIds.get())
 
-  for (const row of $sessions.get()) {
+  for (const row of rowsByPinId($sessions.get()).values()) {
     // A backend without the flag has no opinion; never act on `undefined`.
     if (typeof row.pinned !== 'boolean') {
       continue
@@ -128,7 +163,31 @@ function pullRemotePins(): void {
   }
 }
 
+// Re-entrancy guard: reconcile() is subscribed to BOTH $sessions and
+// $pinnedSessionIds, and pullRemotePins() mutates $pinnedSessionIds (via
+// pinSession/unpinSession), which fires reconcile() again synchronously.
+// Without this guard, a session whose pin state oscillates — two rows with the
+// same durable id but conflicting `pinned` flags, possible when profile
+// databases share session ids — drives an unbounded re-entrant loop that
+// overflows nanostores' shared listenerQueue and crashes the renderer with
+// `RangeError: Invalid array length`.
+let reconciling = false
+
 function reconcile(): void {
+  if (reconciling) {
+    return
+  }
+
+  reconciling = true
+
+  try {
+    reconcileInner()
+  } finally {
+    reconciling = false
+  }
+}
+
+function reconcileInner(): void {
   // Config/session REST is only reachable through the Electron bridge.
   if (!window.hermesDesktop) {
     return
diff --git a/apps/desktop/src/store/session-unread.ts b/apps/desktop/src/store/session-unread.ts
index b6afadace0..64f3cdf115 100644
--- a/apps/desktop/src/store/session-unread.ts
+++ b/apps/desktop/src/store/session-unread.ts
@@ -64,6 +64,9 @@ type SeenCounts = Record<string, Record<string, number>>
 /** profile key → durable ids flagged by the live busy→idle edge. */
 type Markers = Record<string, string[]>
 
+const isPlainRecord = (value: unknown): value is Record<string, unknown> =>
+  Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+
 export const $sessionSeenCounts = persistentAtom<SeenCounts>(
   'hermes.desktop.sessionSeenCounts',
   {},
@@ -76,9 +79,6 @@ export const $unreadFinishedMarkers = persistentAtom<Markers>(
   Codecs.json(sanitizeMarkers)
 )
 
-const isPlainRecord = (value: unknown): value is Record<string, unknown> =>
-  Boolean(value) && typeof value === 'object' && !Array.isArray(value)
-
 // Also the migration: a pre-profile-scoping flat record (durable id → number)
 // has non-object values, so it drops wholesale rather than mis-attributing
 // every id to a profile named after it. Dropped watermarks reseed on next

From d959ba5601f342ba673ce1c245a2535f7662a06f Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 19 Aug 2026 02:00:47 -0500
Subject: [PATCH 06/48] fix(desktop): scope session lookup to the active
 profile

Unscoped getSession hits the primary backend. A 404 then skipped the
active profile in the remaining probes, so chats on a non-default
profile never loaded.

Co-authored-by: Michael McAllister <michael@empowerlo.com>
---
 .../resolve-stored-session.test.ts            | 36 ++++++-------
 .../hooks/use-session-actions/utils.ts        | 54 ++++++++-----------
 2 files changed, 39 insertions(+), 51 deletions(-)

diff --git a/apps/desktop/src/app/session/hooks/use-session-actions/resolve-stored-session.test.ts b/apps/desktop/src/app/session/hooks/use-session-actions/resolve-stored-session.test.ts
index 68f9bac298..468936f5b6 100644
--- a/apps/desktop/src/app/session/hooks/use-session-actions/resolve-stored-session.test.ts
+++ b/apps/desktop/src/app/session/hooks/use-session-actions/resolve-stored-session.test.ts
@@ -62,31 +62,33 @@ describe('resolveStoredSession profile ownership', () => {
   it('treats a profile-less cache hit as unresolved when multiple profiles exist', async () => {
     $sessions.set([session({ id: 's1' })])
     mockGetSession.mockRejectedValueOnce(new Error('404: Session not found'))
-    mockGetSession.mockRejectedValueOnce(new Error('404: Session not found'))
     mockGetSession.mockResolvedValueOnce(session({ id: 's1', profile: 'default' }))
 
     const resolved = await resolveStoredSession('s1')
 
     expect(resolved?.profile).toBe('default')
-    // rung 2 (bare) then rung 3 (stamped probes: active profile first)
-    expect(mockGetSession).toHaveBeenNthCalledWith(1, 's1')
-    expect(mockGetSession).toHaveBeenNthCalledWith(2, 's1', 'meta')
-    expect(mockGetSession).toHaveBeenNthCalledWith(3, 's1', 'default')
+    // rung 2 (active profile) then rung 3 (stamped cross-profile probe)
+    expect(mockGetSession).toHaveBeenNthCalledWith(1, 's1', 'meta')
+    expect(mockGetSession).toHaveBeenNthCalledWith(2, 's1', 'default')
   })
 
-  it('probes the ACTIVE profile when the unscoped lookup 404s (hidden Bot Mode chat)', async () => {
-    // A hidden Bot Mode canonical chat is never in the sidebar cache, and the
-    // unscoped GET routes to the PRIMARY backend (404). The owner is the
-    // active profile itself — it must be probed, not skipped.
-    mockGetSession.mockRejectedValueOnce(new Error('404: Session not found'))
-    mockGetSession.mockResolvedValueOnce(session({ id: 's1', message_count: 2 }))
+  it('scopes the first by-id lookup so a miss does not skip the active profile', async () => {
+    $activeGatewayProfile.set('brain')
+    $profiles.set(profiles('default', 'brain'))
+    mockGetSession.mockImplementation(async (id, profile) => {
+      if (profile === 'brain') {
+        return session({ id, profile: 'brain' })
+      }
+
+      throw new Error('404: Session not found')
+    })
 
     const resolved = await resolveStoredSession('s1')
 
-    expect(resolved?.profile).toBe('meta')
-    expect(mockGetSession).toHaveBeenNthCalledWith(1, 's1')
-    expect(mockGetSession).toHaveBeenNthCalledWith(2, 's1', 'meta')
-    expect($sessions.get().find(s => s.id === 's1')?.profile).toBe('meta')
+    expect(resolved?.profile).toBe('brain')
+    expect(mockGetSession).toHaveBeenCalledWith('s1', 'brain')
+    expect(mockGetSession).not.toHaveBeenCalledWith('s1')
+    expect(mockGetSession).not.toHaveBeenCalledWith('s1', 'default')
   })
 
   it('accepts a profile-less cache hit for single-profile users', async () => {
@@ -105,6 +107,7 @@ describe('resolveStoredSession profile ownership', () => {
     const resolved = await resolveStoredSession('s1')
 
     expect(resolved?.profile).toBe('meta')
+    expect(mockGetSession).toHaveBeenCalledWith('s1', 'meta')
     // the upserted cache row is owned too, so the next hit short-circuits
     expect($sessions.get().find(s => s.id === 's1')?.profile).toBe('meta')
   })
@@ -113,7 +116,6 @@ describe('resolveStoredSession profile ownership', () => {
     // Per-profile remote override: Electron strips the desktop alias before
     // forwarding, so the standalone backend stamps its backend-local root.
     mockGetSession.mockRejectedValueOnce(new Error('404: Session not found'))
-    mockGetSession.mockRejectedValueOnce(new Error('404: Session not found'))
     mockGetSession.mockResolvedValueOnce(session({ id: 's1', profile: 'default' }))
     $activeGatewayProfile.set('default')
     $profiles.set(profiles('default', 'meta'))
@@ -125,7 +127,6 @@ describe('resolveStoredSession profile ownership', () => {
   })
 
   it('stamps the probed profile on a scoped hit from an older backend that omits it', async () => {
-    mockGetSession.mockRejectedValueOnce(new Error('404: Session not found'))
     mockGetSession.mockRejectedValueOnce(new Error('404: Session not found'))
     mockGetSession.mockResolvedValueOnce(session({ id: 's1' }))
 
@@ -137,7 +138,6 @@ describe('resolveStoredSession profile ownership', () => {
   })
 
   it('resolveSessionProfile routes a default-profile session from a non-default gateway', async () => {
-    mockGetSession.mockRejectedValueOnce(new Error('404: Session not found'))
     mockGetSession.mockRejectedValueOnce(new Error('404: Session not found'))
     mockGetSession.mockResolvedValueOnce(session({ id: 's1', profile: 'default' }))
 
diff --git a/apps/desktop/src/app/session/hooks/use-session-actions/utils.ts b/apps/desktop/src/app/session/hooks/use-session-actions/utils.ts
index e622a52463..6474b93431 100644
--- a/apps/desktop/src/app/session/hooks/use-session-actions/utils.ts
+++ b/apps/desktop/src/app/session/hooks/use-session-actions/utils.ts
@@ -1307,17 +1307,19 @@ export async function resolveStoredSession(storedSessionId: string): Promise<Ses
     return cached
   }
 
-  // Direct by-id on the live backend — one row lookup, no list scan. Covers
-  // single-profile users and any id on the active profile (e.g. an old session
-  // past the sidebar's recent window). 404 just means it's not on this profile.
-  try {
-    const session = await getSession(storedSessionId)
+  // Direct by-id on the active profile — one row lookup, no list scan. Electron
+  // routes an unscoped GET to the primary backend, which may not own the
+  // active profile. A 404 there used to skip that profile in the probes below,
+  // so the session was never found.
+  const activeKey = normalizeProfileKey($activeGatewayProfile.get())
 
-    // Older backends omit `profile` on unscoped GETs; the serving backend is
-    // the active gateway's, so back-fill that rather than caching an unowned
-    // row. A present stamp is preserved: in app-global remote mode a bare hit
-    // can legitimately carry another profile's row (see the branch tests).
-    session.profile ||= normalizeProfileKey($activeGatewayProfile.get())
+  try {
+    const session = await getSession(storedSessionId, activeKey)
+
+    // Older backends can omit `profile`; this request targeted the active
+    // profile, so back-fill that rather than caching an unowned row. A present
+    // stamp is preserved for backend compatibility.
+    session.profile ||= activeKey
 
     upsertResolvedSession(session, storedSessionId)
 
@@ -1326,30 +1328,16 @@ export async function resolveStoredSession(storedSessionId: string): Promise<Ses
     // Not on the active profile — fall through to the cross-profile probe.
   }
 
-  // Multi-profile only: probe each profile by id (still one cheap lookup
-  // each) rather than pulling every profile's recent sessions. The first hit
-  // carries its owning `profile`, which routes the resume to the right backend.
-  //
-  // The ACTIVE profile is probed too, and first. The unscoped rung above does
-  // NOT cover it: Electron routes a profile-less /api/sessions GET to the
-  // PRIMARY backend, not the active gateway's, so a session owned by the
-  // active non-primary profile 404s there. Skipping the active key then left
-  // it as the ONE profile never probed — a hidden Bot Mode chat (never in the
-  // sidebar cache) owned by the focused bot resolved to undefined on every
-  // switch, the transcript prefetch went unscoped to the primary, and the
-  // thread painted empty until an explicitly-profiled row (right-click →
-  // Sessions) seeded the cache.
-  const activeKey = normalizeProfileKey($activeGatewayProfile.get())
+  // Multi-profile only: probe each remaining profile by id (still one cheap
+  // lookup each) rather than pulling every profile's recent sessions. The
+  // first hit carries its owning `profile`, which routes the resume to the
+  // right backend. The active profile was already tried above.
+  const otherProfiles = $profiles
+    .get()
+    .map(profile => normalizeProfileKey(profile.name))
+    .filter(key => key !== activeKey)
 
-  const probeProfiles = [
-    activeKey,
-    ...$profiles
-      .get()
-      .map(profile => normalizeProfileKey(profile.name))
-      .filter(key => key !== activeKey)
-  ]
-
-  for (const profile of probeProfiles) {
+  for (const profile of otherProfiles) {
     try {
       const session = await getSession(storedSessionId, profile)
 

From aa20dbe73e57545b2d4cb7d3383f21d5047cb217 Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 19 Aug 2026 03:34:49 -0500
Subject: [PATCH 07/48] refactor(desktop): split src/hermes.ts into src/api/
 domain modules
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

2,248 lines of gateway REST client become twelve modules by domain, with
hermes.ts left as a barrel so all 144 importers stay put. The import
graph is a star — every domain module imports only ./client, and client
imports nothing back — so there are no cycles.

The barrel names client's public exports rather than re-exporting it
wholesale. Splitting a module forces its private helpers into exports so
siblings can reach them, and export * would then republish them:
profileScoped, connectionScoped and capabilityScoped were private to
hermes.ts and have to stay that way, or a call site can assemble its own
request scope and drift from the api layer.
---
 apps/desktop/src/api/client.ts    |  154 ++
 apps/desktop/src/api/config.ts    |  239 ++++
 apps/desktop/src/api/cron.ts      |  153 ++
 apps/desktop/src/api/mcp.ts       |  147 ++
 apps/desktop/src/api/messaging.ts |  131 ++
 apps/desktop/src/api/models.ts    |  129 ++
 apps/desktop/src/api/plugins.ts   |  128 ++
 apps/desktop/src/api/profiles.ts  |   89 ++
 apps/desktop/src/api/sessions.ts  |  465 ++++++
 apps/desktop/src/api/skills.ts    |  162 +++
 apps/desktop/src/api/system.ts    |  247 ++++
 apps/desktop/src/api/toolsets.ts  |  141 ++
 apps/desktop/src/hermes.ts        | 2176 +----------------------------
 13 files changed, 2214 insertions(+), 2147 deletions(-)
 create mode 100644 apps/desktop/src/api/client.ts
 create mode 100644 apps/desktop/src/api/config.ts
 create mode 100644 apps/desktop/src/api/cron.ts
 create mode 100644 apps/desktop/src/api/mcp.ts
 create mode 100644 apps/desktop/src/api/messaging.ts
 create mode 100644 apps/desktop/src/api/models.ts
 create mode 100644 apps/desktop/src/api/plugins.ts
 create mode 100644 apps/desktop/src/api/profiles.ts
 create mode 100644 apps/desktop/src/api/sessions.ts
 create mode 100644 apps/desktop/src/api/skills.ts
 create mode 100644 apps/desktop/src/api/system.ts
 create mode 100644 apps/desktop/src/api/toolsets.ts

diff --git a/apps/desktop/src/api/client.ts b/apps/desktop/src/api/client.ts
new file mode 100644
index 0000000000..e996ab0109
--- /dev/null
+++ b/apps/desktop/src/api/client.ts
@@ -0,0 +1,154 @@
+import { JsonRpcGatewayClient } from '@hermes/shared'
+
+import type { HermesApiRequest } from '@/global'
+
+// Desktop startup fires a burst of read-only data calls (config, profiles,
+// model info/options, cron) the moment the backend passes readiness. On a
+// profile-heavy or remote install these can each take tens of seconds — e.g.
+// /api/profiles runs list_profiles(), which does a recursive skill-tree walk
+// per profile — so the 15s default (DEFAULT_FETCH_TIMEOUT_MS in hardening.ts)
+// times out a backend that is alive-but-busy, surfacing as a spurious
+// "Timed out connecting to Hermes backend" that hangs the UI (#48504).
+//
+// Give the boot burst a generous per-call timeout instead of raising the
+// global default: interactive/runtime calls and the liveness poll (/api/status)
+// keep the short default so a genuinely-dead backend is still detected fast.
+export const STARTUP_REQUEST_TIMEOUT_MS = 60_000
+const DEFAULT_GATEWAY_REQUEST_TIMEOUT_MS = 30_000
+// prompt.submit is effectively fire-and-forget: turn completion is signaled by
+// stream / message.complete events, NOT by the RPC return. A long turn (MoA
+// presets running references + aggregator in series, deep reasoning, large tool
+// chains) can legitimately take minutes to ACK, so bounding the ack by the
+// generic 30s default surfaces a false "request timed out" toast while the turn
+// is still running and will succeed (issue #55024). Match the backend's
+// agent-turn ceiling (agent.gateway_timeout = 1800s) so the ack timeout only
+// ever fires when the turn itself would have been abandoned server-side.
+export const PROMPT_SUBMIT_REQUEST_TIMEOUT_MS = 1_800_000
+
+export class HermesGateway extends JsonRpcGatewayClient {
+  constructor() {
+    super({
+      closedErrorMessage: 'Hermes gateway connection closed',
+      connectErrorMessage: 'Could not connect to Hermes gateway',
+      createRequestId: nextId => nextId,
+      notConnectedErrorMessage: 'Hermes gateway is not connected',
+      requestTimeoutMs: DEFAULT_GATEWAY_REQUEST_TIMEOUT_MS
+    })
+  }
+}
+
+// Profile that profile-scoped REST settings (config/env/skills/tools/model/…)
+// should target. Mirrors $activeGatewayProfile, pushed in from the store via
+// setApiRequestProfile so this module needs no store import (avoids a cycle).
+// Electron main consumes request.profile as request scope. Local calls whose
+// REST handlers accept profile reuse the primary dashboard via ?profile=;
+// unscoped handlers retain a profile backend. Remote overrides still route to
+// their owning backend. Null → primary, so single-profile users are unaffected.
+let _apiProfile: null | string = null
+
+export function setApiRequestProfile(profile: null | string): void {
+  _apiProfile = profile || null
+}
+
+export function profileScoped(profile?: null | string): { profile?: string } {
+  const selected = profile === undefined ? _apiProfile : profile
+
+  return selected ? { profile: selected } : {}
+}
+
+/** Profile that profile-scoped REST/WS calls should target (null → primary).
+ *  Read-only twin of setApiRequestProfile for modules (e.g. voice playback)
+ *  that build their own connection URLs and must stay on the same backend. */
+export function getApiRequestProfile(): null | string {
+  return _apiProfile
+}
+
+// Registry connection serving the active gateway (null → the local pool).
+// Pushed from store/gateway's setActive — the single seam BOTH
+// ensureGatewayProfile and ensureGatewayAgent funnel through — so WS calls
+// that dial their own backend (pluginSocket) resolve it through the SAME
+// source of truth those paths maintain for $connection. That makes the plugin
+// socket follow registry-agent activations too, not just profile switches.
+// Same no-store-import contract as _apiProfile (avoids a cycle).
+let _apiConnectionId: null | string = null
+
+export function setApiRequestConnection(connectionId: null | string): void {
+  _apiConnectionId = connectionId || null
+}
+
+// Registry connection scope for a REST request. A registered remote gateway
+// owns its own state.db — cron jobs and their run sessions live THERE — so
+// requests for gateway-owned data must carry the connection id for the main
+// process to route them to that host (hermes:api's registry branch). Null
+// resolves to no tag, keeping single-source users byte-identical; explicit
+// 'local' must remain tagged when the legacy primary points elsewhere.
+export function connectionScoped(): { connectionId?: string } {
+  return _apiConnectionId ? { connectionId: _apiConnectionId } : {}
+}
+
+/** Send a REST request to the renderer's active registry source. Request-level
+ *  routing may override the active source for an explicitly-owned resource.
+ *
+ *  Helpers under `api/` go through here rather than calling the preload bridge
+ *  directly, so the connection tag cannot be forgotten on a new one — with one
+ *  exception. A capabilityScoped() helper must NOT: that scope says "the local
+ *  pool" by omitting `connectionId` entirely, and an absent key cannot override
+ *  the ambient tag spread underneath it, so a 'local' pin would silently route
+ *  to whatever remote gateway happened to be active. Those helpers call the
+ *  bridge directly and own their routing end to end. */
+export function hermesApi<T>(request: HermesApiRequest): Promise<T> {
+  return window.hermesDesktop.api<T>({ ...connectionScoped(), ...request })
+}
+
+// ── Capability scope: (connection, profile) routing for the Capabilities
+// surface (skills / toolsets / MCP / hub / env / toolset config) ────────────
+//
+// A profile is not a machine-global name — it belongs to ONE gateway. The
+// Capabilities surface can be pointed at any (connection, profile) pair
+// (SkillsView's scope selector, Bot Mode's fixedProfile/fixedConnection), so
+// its REST helpers accept either the legacy string form or an explicit scope
+// object:
+//
+//   - `undefined` / string → the legacy profile path, PLUS the active registry
+//     connection tag (connectionScoped, same contract the cron helpers adopted
+//     in #87882). Without the tag, a window activated onto a registered remote
+//     gateway read the LOCAL pool's skills/tools/MCP — the wrong machine.
+//   - `{ connectionId, profile }` → explicit pin. `''`/`'local'` connection
+//     ids mean the local pool and deliberately DROP the ambient connection
+//     tag, so a local-profile pick made while a remote gateway is active still
+//     routes to the local machine.
+export type ProfileScope = null | string | { connectionId?: null | string; profile?: null | string }
+
+export function capabilityScoped(scope?: ProfileScope): { connectionId?: string; profile?: string } {
+  if (scope && typeof scope === 'object') {
+    const profile = (scope.profile ?? '').trim()
+    const connectionId = (scope.connectionId ?? '').trim()
+
+    return {
+      ...(profile ? { profile } : {}),
+      ...(connectionId && connectionId !== 'local' ? { connectionId } : {})
+    }
+  }
+
+  return { ...profileScoped(scope), ...connectionScoped() }
+}
+
+/** Stable cache-key for a capability scope: `profile` for the local/legacy
+ *  path, `connectionId::profile` for an explicit remote pin. Mirrors
+ *  normalizeProfileKey for plain strings so existing keys stay byte-identical. */
+export function profileScopeKey(scope?: ProfileScope): string {
+  if (scope && typeof scope === 'object') {
+    const profile = (scope.profile ?? '').trim() || 'default'
+    const connectionId = (scope.connectionId ?? '').trim()
+
+    return connectionId && connectionId !== 'local' ? `${connectionId}::${profile}` : profile
+  }
+
+  return (scope ?? '').trim() || 'default'
+}
+
+/** Registry connection id that connection-scoped WS calls should target
+ *  (null → the local pool). Read-only twin of setApiRequestConnection. */
+export function getApiRequestConnection(): null | string {
+  return _apiConnectionId
+}
diff --git a/apps/desktop/src/api/config.ts b/apps/desktop/src/api/config.ts
new file mode 100644
index 0000000000..38fd4945d6
--- /dev/null
+++ b/apps/desktop/src/api/config.ts
@@ -0,0 +1,239 @@
+import type {
+  ConfigSchemaResponse,
+  CustomEndpointsResponse,
+  CustomEndpointUpdate,
+  CustomEndpointValidationResponse,
+  EnvVarInfo,
+  HermesConfig,
+  HermesConfigRecord,
+  LogsResponse,
+  OAuthPollResponse,
+  OAuthProvidersResponse,
+  OAuthStartResponse,
+  OAuthSubmitResponse,
+  StatusResponse
+} from '@/types/hermes'
+
+import { capabilityScoped, hermesApi, type ProfileScope, profileScoped, STARTUP_REQUEST_TIMEOUT_MS } from './client'
+
+export function getStatus(): Promise<StatusResponse> {
+  return hermesApi<StatusResponse>({
+    ...profileScoped(),
+    path: '/api/status'
+  })
+}
+
+export function getLogs(params: {
+  component?: string
+  file?: string
+  level?: string
+  lines?: number
+  search?: string
+}): Promise<LogsResponse> {
+  const query = new URLSearchParams()
+
+  if (params.file) {
+    query.set('file', params.file)
+  }
+
+  if (typeof params.lines === 'number') {
+    query.set('lines', String(params.lines))
+  }
+
+  if (params.level && params.level !== 'ALL') {
+    query.set('level', params.level)
+  }
+
+  if (params.component && params.component !== 'all') {
+    query.set('component', params.component)
+  }
+
+  if (params.search) {
+    query.set('search', params.search)
+  }
+
+  const suffix = query.toString()
+
+  return hermesApi<LogsResponse>({
+    ...profileScoped(),
+    path: suffix ? `/api/logs?${suffix}` : '/api/logs'
+  })
+}
+
+export function getHermesConfig(profile?: string): Promise<HermesConfig> {
+  return hermesApi<HermesConfig>({
+    ...profileScoped(profile),
+    path: '/api/config',
+    timeoutMs: STARTUP_REQUEST_TIMEOUT_MS
+  })
+}
+
+export function getHermesConfigRecord(profile?: ProfileScope): Promise<HermesConfigRecord> {
+  return window.hermesDesktop.api<HermesConfigRecord>({
+    ...capabilityScoped(profile),
+    path: '/api/config'
+  })
+}
+
+export function getHermesConfigDefaults(): Promise<HermesConfigRecord> {
+  return hermesApi<HermesConfigRecord>({
+    ...profileScoped(),
+    path: '/api/config/defaults',
+    timeoutMs: STARTUP_REQUEST_TIMEOUT_MS
+  })
+}
+
+export function getHermesConfigSchema(profile?: null | string): Promise<ConfigSchemaResponse> {
+  return hermesApi<ConfigSchemaResponse>({
+    ...profileScoped(profile),
+    path: '/api/config/schema'
+  })
+}
+
+export function saveHermesConfig(config: HermesConfigRecord, profile?: null | string): Promise<{ ok: boolean }> {
+  return hermesApi<{ ok: boolean }>({
+    ...profileScoped(profile),
+    path: '/api/config',
+    method: 'PUT',
+    body: { config }
+  })
+}
+
+export function getEnvVars(profile?: null | string): Promise<Record<string, EnvVarInfo>> {
+  return hermesApi<Record<string, EnvVarInfo>>({
+    ...profileScoped(profile),
+    path: '/api/env'
+  })
+}
+
+export function setEnvVar(key: string, value: string, profile?: ProfileScope): Promise<{ ok: boolean }> {
+  return window.hermesDesktop.api<{ ok: boolean }>({
+    ...capabilityScoped(profile),
+    path: '/api/env',
+    method: 'PUT',
+    body: { key, value }
+  })
+}
+
+export function deleteEnvVar(key: string, profile?: ProfileScope): Promise<{ ok: boolean }> {
+  return window.hermesDesktop.api<{ ok: boolean }>({
+    ...capabilityScoped(profile),
+    path: '/api/env',
+    method: 'DELETE',
+    body: { key }
+  })
+}
+
+export function revealEnvVar(key: string, profile?: ProfileScope): Promise<{ key: string; value: string }> {
+  return window.hermesDesktop.api<{ key: string; value: string }>({
+    ...capabilityScoped(profile),
+    path: '/api/env/reveal',
+    method: 'POST',
+    body: { key }
+  })
+}
+
+export function validateProviderCredential(
+  key: string,
+  value: string,
+  apiKey?: string
+): Promise<{ ok: boolean; reachable: boolean; message: string; models?: string[] }> {
+  return hermesApi<{ ok: boolean; reachable: boolean; message: string; models?: string[] }>({
+    ...profileScoped(),
+    path: '/api/providers/validate',
+    method: 'POST',
+    body: { key, value, api_key: apiKey ?? '' }
+  })
+}
+
+export function getCustomEndpoints(): Promise<CustomEndpointsResponse> {
+  return hermesApi<CustomEndpointsResponse>({
+    ...profileScoped(),
+    path: '/api/providers/custom-endpoints'
+  })
+}
+
+export function saveCustomEndpoint(endpoint: CustomEndpointUpdate): Promise<CustomEndpointsResponse> {
+  return hermesApi<CustomEndpointsResponse>({
+    ...profileScoped(),
+    path: '/api/providers/custom-endpoints',
+    method: 'POST',
+    body: endpoint
+  })
+}
+
+export function validateCustomEndpoint(endpoint: CustomEndpointUpdate): Promise<CustomEndpointValidationResponse> {
+  return hermesApi<CustomEndpointValidationResponse>({
+    path: '/api/providers/custom-endpoints/validate',
+    method: 'POST',
+    body: endpoint
+  })
+}
+
+export function activateCustomEndpoint(id: string): Promise<{ ok: boolean; provider: string; model: string }> {
+  return hermesApi<{ ok: boolean; provider: string; model: string }>({
+    ...profileScoped(),
+    path: `/api/providers/custom-endpoints/${encodeURIComponent(id)}/activate`,
+    method: 'POST'
+  })
+}
+
+export function deleteCustomEndpoint(id: string): Promise<CustomEndpointsResponse> {
+  return hermesApi<CustomEndpointsResponse>({
+    ...profileScoped(),
+    path: `/api/providers/custom-endpoints/${encodeURIComponent(id)}`,
+    method: 'DELETE'
+  })
+}
+
+export function listOAuthProviders(): Promise<OAuthProvidersResponse> {
+  return hermesApi<OAuthProvidersResponse>({
+    ...profileScoped(),
+    path: '/api/providers/oauth'
+  })
+}
+
+export function disconnectOAuthProvider(providerId: string): Promise<{ ok: boolean; provider: string }> {
+  return hermesApi<{ ok: boolean; provider: string }>({
+    ...profileScoped(),
+    path: `/api/providers/oauth/${encodeURIComponent(providerId)}`,
+    method: 'DELETE'
+  })
+}
+
+export function startOAuthLogin(providerId: string, profile?: ProfileScope): Promise<OAuthStartResponse> {
+  return window.hermesDesktop.api<OAuthStartResponse>({
+    ...capabilityScoped(profile),
+    path: `/api/providers/oauth/${encodeURIComponent(providerId)}/start`,
+    method: 'POST',
+    body: {}
+  })
+}
+
+export function submitOAuthCode(providerId: string, sessionId: string, code: string): Promise<OAuthSubmitResponse> {
+  return hermesApi<OAuthSubmitResponse>({
+    ...profileScoped(),
+    path: `/api/providers/oauth/${encodeURIComponent(providerId)}/submit`,
+    method: 'POST',
+    body: { session_id: sessionId, code }
+  })
+}
+
+export function pollOAuthSession(
+  providerId: string,
+  sessionId: string,
+  profile?: ProfileScope
+): Promise<OAuthPollResponse> {
+  return window.hermesDesktop.api<OAuthPollResponse>({
+    ...capabilityScoped(profile),
+    path: `/api/providers/oauth/${encodeURIComponent(providerId)}/poll/${encodeURIComponent(sessionId)}`
+  })
+}
+
+export function cancelOAuthSession(sessionId: string): Promise<{ ok: boolean }> {
+  return hermesApi<{ ok: boolean }>({
+    ...profileScoped(),
+    path: `/api/providers/oauth/sessions/${encodeURIComponent(sessionId)}`,
+    method: 'DELETE'
+  })
+}
diff --git a/apps/desktop/src/api/cron.ts b/apps/desktop/src/api/cron.ts
new file mode 100644
index 0000000000..b790b033d7
--- /dev/null
+++ b/apps/desktop/src/api/cron.ts
@@ -0,0 +1,153 @@
+import type {
+  AutomationBlueprint,
+  CronDeliveryTarget,
+  CronJob,
+  CronJobCreatePayload,
+  CronJobUpdates,
+  SessionInfo
+} from '@/types/hermes'
+
+import { connectionScoped, hermesApi, profileScoped, STARTUP_REQUEST_TIMEOUT_MS } from './client'
+
+// The cron trigger endpoint intentionally waits for the whole job so its
+// response reflects the persisted execution result. Agent jobs can run far
+// longer than the Electron fetch default; keep this override local to the one
+// synchronous long-operation endpoint rather than weakening all API timeouts.
+const CRON_TRIGGER_REQUEST_TIMEOUT_MS = 24 * 60 * 60 * 1000
+
+// Cron jobs are stored per-profile (<HERMES_HOME>/cron/jobs.json), and the
+// backend's list endpoint defaults to 'all'. Pass a concrete profile key to
+// list just that profile's jobs, or 'all' for the unified cross-profile view.
+// Omitting the arg keeps the legacy 'all' default for non-profile callers.
+// profileScoped() still rides along for backend-process routing.
+export function getCronJobs(profile?: string): Promise<CronJob[]> {
+  const suffix = profile ? `?profile=${encodeURIComponent(profile)}` : ''
+
+  return hermesApi<CronJob[]>({
+    ...profileScoped(),
+    ...connectionScoped(),
+    path: `/api/cron/jobs${suffix}`,
+    timeoutMs: STARTUP_REQUEST_TIMEOUT_MS
+  })
+}
+
+export function getCronJob(jobId: string): Promise<CronJob> {
+  return hermesApi<CronJob>({
+    ...profileScoped(),
+    ...connectionScoped(),
+    path: `/api/cron/jobs/${encodeURIComponent(jobId)}`
+  })
+}
+
+export async function getCronJobRuns(jobId: string, limit = 20): Promise<SessionInfo[]> {
+  const { runs } = await hermesApi<{ runs: SessionInfo[] }>({
+    ...profileScoped(),
+    ...connectionScoped(),
+    path: `/api/cron/jobs/${encodeURIComponent(jobId)}/runs?limit=${limit}`
+  })
+
+  return runs ?? []
+}
+
+// The single source of truth for cron delivery targets (local + configured
+// gateways). Both the manual cron editor and the blueprint dialog use this so
+// they never offer a platform that isn't connected. Mirrors the dashboard.
+export async function getCronDeliveryTargets(): Promise<CronDeliveryTarget[]> {
+  const { targets } = await hermesApi<{ targets: CronDeliveryTarget[] }>({
+    ...profileScoped(),
+    ...connectionScoped(),
+    path: '/api/cron/delivery-targets'
+  })
+
+  return targets ?? []
+}
+
+export function createCronJob(body: CronJobCreatePayload): Promise<CronJob> {
+  return hermesApi<CronJob>({
+    ...profileScoped(),
+    ...connectionScoped(),
+    path: '/api/cron/jobs',
+    method: 'POST',
+    body
+  })
+}
+
+export function updateCronJob(jobId: string, updates: CronJobUpdates): Promise<CronJob> {
+  return hermesApi<CronJob>({
+    ...profileScoped(),
+    ...connectionScoped(),
+    path: `/api/cron/jobs/${encodeURIComponent(jobId)}`,
+    method: 'PUT',
+    body: { updates }
+  })
+}
+
+export function pauseCronJob(jobId: string): Promise<CronJob> {
+  return hermesApi<CronJob>({
+    ...profileScoped(),
+    ...connectionScoped(),
+    path: `/api/cron/jobs/${encodeURIComponent(jobId)}/pause`,
+    method: 'POST'
+  })
+}
+
+export function resumeCronJob(jobId: string): Promise<CronJob> {
+  return hermesApi<CronJob>({
+    ...profileScoped(),
+    ...connectionScoped(),
+    path: `/api/cron/jobs/${encodeURIComponent(jobId)}/resume`,
+    method: 'POST'
+  })
+}
+
+export function triggerCronJob(jobId: string): Promise<CronJob> {
+  return hermesApi<CronJob>({
+    ...profileScoped(),
+    ...connectionScoped(),
+    path: `/api/cron/jobs/${encodeURIComponent(jobId)}/trigger`,
+    method: 'POST',
+    timeoutMs: CRON_TRIGGER_REQUEST_TIMEOUT_MS
+  })
+}
+
+export function deleteCronJob(jobId: string): Promise<{ ok: boolean }> {
+  return hermesApi<{ ok: boolean }>({
+    ...profileScoped(),
+    ...connectionScoped(),
+    path: `/api/cron/jobs/${encodeURIComponent(jobId)}`,
+    method: 'DELETE'
+  })
+}
+
+// Automation Blueprints — parameterized cron templates the backend serves from
+// cron/blueprint_catalog.py. getAutomationBlueprints returns the gallery
+// (deliver options already rewritten to this machine's configured gateways);
+// instantiateAutomationBlueprint fills the slots and creates a real cron job via
+// the same create_job path as createCronJob.
+//
+// Profile-scoping is intentionally asymmetric: the GET catalog is global (the
+// list endpoint takes no profile — only deliver options are rewritten from the
+// configured gateways), so it carries only the profileScoped() header for
+// routing. instantiate creates a real per-profile job, so it names the target
+// profile explicitly via ?profile=. This mirrors the dashboard's api.ts.
+export function getAutomationBlueprints(): Promise<{ blueprints: AutomationBlueprint[] }> {
+  return hermesApi<{ blueprints: AutomationBlueprint[] }>({
+    ...profileScoped(),
+    ...connectionScoped(),
+    path: '/api/cron/blueprints',
+    timeoutMs: STARTUP_REQUEST_TIMEOUT_MS
+  })
+}
+
+export function instantiateAutomationBlueprint(
+  body: { blueprint: string; values: Record<string, string> },
+  profile: string
+): Promise<CronJob> {
+  return hermesApi<CronJob>({
+    ...profileScoped(),
+    ...connectionScoped(),
+    path: `/api/cron/blueprints/instantiate?profile=${encodeURIComponent(profile)}`,
+    method: 'POST',
+    body
+  })
+}
diff --git a/apps/desktop/src/api/mcp.ts b/apps/desktop/src/api/mcp.ts
new file mode 100644
index 0000000000..f67870e5bf
--- /dev/null
+++ b/apps/desktop/src/api/mcp.ts
@@ -0,0 +1,147 @@
+import type { McpCatalogResponse, McpServerSummary } from '@/types/hermes'
+
+import { capabilityScoped, hermesApi, type ProfileScope, profileScoped } from './client'
+
+export interface McpTestResult {
+  ok: boolean
+  error?: string
+  /** `schema_chars` (converted registry-schema size, chars) is additive —
+   *  older backends omit it and the cost overlay shows no token estimate. */
+  tools: { name: string; description: string; schema_chars?: number }[]
+  /** Capability counts (absent on older backends / failed probes). */
+  prompts?: number
+  resources?: number
+}
+
+export interface McpOAuthFlow {
+  flow_id: string
+  server_name: string
+  status: 'starting' | 'authorization_required' | 'approved' | 'error'
+  authorization_url: string | null
+  error: string | null
+  tools?: { name: string; description: string }[]
+}
+
+/** Connect to the server, list its tools, disconnect. Slow (spawns/handshakes
+ *  for real) — well past the 15s default fetch timeout. */
+export function testMcpServer(name: string, profile?: ProfileScope): Promise<McpTestResult> {
+  return window.hermesDesktop.api<McpTestResult>({
+    ...capabilityScoped(profile),
+    path: `/api/mcp/servers/${encodeURIComponent(name)}/test`,
+    method: 'POST',
+    timeoutMs: 60_000
+  })
+}
+
+/** Replace the whole `mcp_servers` map (the mcp.json editor's save). Unlike
+ *  `saveHermesConfig`, this REPLACES rather than deep-merges, so deletes,
+ *  re-enables (dropping `enabled: false`), and removed nested fields persist. */
+export function saveMcpServers(
+  servers: Record<string, Record<string, unknown>>,
+  profile?: ProfileScope
+): Promise<{ ok: boolean }> {
+  return window.hermesDesktop.api<{ ok: boolean }>({
+    ...capabilityScoped(profile),
+    path: '/api/mcp/servers',
+    method: 'PUT',
+    body: { servers }
+  })
+}
+
+/** Start an MCP OAuth flow and return the authorization URL. */
+export function authMcpServer(name: string, profile?: ProfileScope): Promise<McpOAuthFlow> {
+  return window.hermesDesktop.api<McpOAuthFlow>({
+    ...capabilityScoped(profile),
+    path: `/api/mcp/servers/${encodeURIComponent(name)}/auth`,
+    method: 'POST',
+    timeoutMs: 60_000
+  })
+}
+
+export function getMcpOAuthFlow(flowId: string, profile?: ProfileScope): Promise<McpOAuthFlow> {
+  return window.hermesDesktop.api<McpOAuthFlow>({
+    ...capabilityScoped(profile),
+    path: `/api/mcp/oauth/flows/${encodeURIComponent(flowId)}`
+  })
+}
+
+/** Cancel an in-flight MCP OAuth flow server-side, freeing the per-server
+ *  "already in progress" slot so a retry doesn't 409. */
+export function cancelMcpOAuthFlow(flowId: string, profile?: null | string): Promise<{ ok: boolean; status: string }> {
+  return hermesApi<{ ok: boolean; status: string }>({
+    ...profileScoped(profile),
+    path: `/api/mcp/oauth/flows/${encodeURIComponent(flowId)}`,
+    method: 'DELETE'
+  })
+}
+
+// ---------------------------------------------------------------------------
+// MCP servers — structured list / test / enable toggle / catalog (parity with
+// `hermes mcp` and the dashboard MCP page). Raw JSON editing stays in
+// config.yaml via saveHermesConfig.
+// ---------------------------------------------------------------------------
+
+export function listMcpServers(): Promise<{ servers: McpServerSummary[] }> {
+  return hermesApi<{ servers: McpServerSummary[] }>({
+    ...profileScoped(),
+    path: '/api/mcp/servers'
+  })
+}
+
+/** Add one server to `mcp_servers` (validated + name-collision-checked
+ *  server-side — the same endpoint the dashboard's add form uses). */
+export function addMcpServer(body: {
+  name: string
+  url?: string
+  command?: string
+  args?: string[]
+  env?: Record<string, string>
+  auth?: string
+}): Promise<McpServerSummary> {
+  return hermesApi<McpServerSummary>({
+    ...profileScoped(),
+    path: '/api/mcp/servers',
+    method: 'POST',
+    body
+  })
+}
+
+/** Remove one server from `mcp_servers` (the inline setup card's rollback
+ *  when a directory install is cancelled after the config write). */
+export function removeMcpServer(name: string): Promise<{ ok: boolean }> {
+  return hermesApi<{ ok: boolean }>({
+    ...profileScoped(),
+    path: `/api/mcp/servers/${encodeURIComponent(name)}`,
+    method: 'DELETE'
+  })
+}
+
+export function setMcpServerEnabled(name: string, enabled: boolean): Promise<{ ok: boolean }> {
+  return hermesApi<{ ok: boolean }>({
+    ...profileScoped(),
+    path: `/api/mcp/servers/${encodeURIComponent(name)}/enabled`,
+    method: 'PUT',
+    body: { enabled }
+  })
+}
+
+export function getMcpCatalog(profile?: ProfileScope): Promise<McpCatalogResponse> {
+  return window.hermesDesktop.api<McpCatalogResponse>({
+    ...capabilityScoped(profile),
+    path: '/api/mcp/catalog'
+  })
+}
+
+export function installMcpCatalogEntry(
+  name: string,
+  env: Record<string, string> = {},
+  profile?: ProfileScope
+): Promise<{ ok: boolean; name?: string; pid?: number; action?: string; background?: boolean }> {
+  return window.hermesDesktop.api<{ ok: boolean; name?: string; pid?: number; action?: string; background?: boolean }>({
+    ...capabilityScoped(profile),
+    path: '/api/mcp/catalog/install',
+    method: 'POST',
+    body: { name, env, enable: true },
+    timeoutMs: 60_000
+  })
+}
diff --git a/apps/desktop/src/api/messaging.ts b/apps/desktop/src/api/messaging.ts
new file mode 100644
index 0000000000..b49bdc93b8
--- /dev/null
+++ b/apps/desktop/src/api/messaging.ts
@@ -0,0 +1,131 @@
+import type {
+  MessagingPlatformsResponse,
+  MessagingPlatformTestResponse,
+  MessagingPlatformUpdate,
+  PairingResponse,
+  PairingUser,
+  WebhookCreatePayload,
+  WebhookCreateResponse,
+  WebhookEnableResponse,
+  WebhooksResponse
+} from '@/types/hermes'
+
+import { hermesApi, profileScoped } from './client'
+
+export function getMessagingPlatforms(profile?: null | string): Promise<MessagingPlatformsResponse> {
+  return hermesApi<MessagingPlatformsResponse>({
+    ...profileScoped(profile),
+    path: '/api/messaging/platforms'
+  })
+}
+
+export function updateMessagingPlatform(
+  platformId: string,
+  body: MessagingPlatformUpdate,
+  profile?: null | string
+): Promise<{ ok: boolean; platform: string }> {
+  return hermesApi<{ ok: boolean; platform: string }>({
+    ...profileScoped(profile),
+    path: `/api/messaging/platforms/${encodeURIComponent(platformId)}`,
+    method: 'PUT',
+    body
+  })
+}
+
+export function testMessagingPlatform(
+  platformId: string,
+  profile?: null | string
+): Promise<MessagingPlatformTestResponse> {
+  return hermesApi<MessagingPlatformTestResponse>({
+    ...profileScoped(profile),
+    path: `/api/messaging/platforms/${encodeURIComponent(platformId)}/test`,
+    method: 'POST'
+  })
+}
+
+// -- Pairing (who may DM the bot) --------------------------------------------
+// Unknown DMers get a one-time code and land in `pending` until an admin
+// approves them. Approval grants on the row's `request_id`, never on the code:
+// the code is the requester's proof that the channel is theirs and is never
+// returned by the API, while an authenticated admin is only ever identifying
+// a row they can already see.
+
+export function getPairing(profile?: null | string): Promise<PairingResponse> {
+  return hermesApi<PairingResponse>({
+    ...profileScoped(profile),
+    path: '/api/pairing'
+  })
+}
+
+export function approvePairing(
+  platform: string,
+  requestId: string,
+  profile?: null | string
+): Promise<{ ok: boolean; user: PairingUser }> {
+  return hermesApi<{ ok: boolean; user: PairingUser }>({
+    ...profileScoped(profile),
+    path: '/api/pairing/approve',
+    method: 'POST',
+    // These endpoints read the profile off the body, not the query string —
+    // `profileScoped()` alone would approve into the wrong profile's store.
+    body: { platform, request_id: requestId, ...profileScoped(profile) }
+  })
+}
+
+export function revokePairing(platform: string, userId: string, profile?: null | string): Promise<{ ok: boolean }> {
+  return hermesApi<{ ok: boolean }>({
+    ...profileScoped(profile),
+    path: '/api/pairing/revoke',
+    method: 'POST',
+    body: { platform, user_id: userId, ...profileScoped(profile) }
+  })
+}
+
+// -- Webhooks (subscription CRUD) --------------------------------------------
+// The webhook receiver is its own gateway platform; subscriptions live in a
+// shared JSON store the CLI/dashboard also drive. Enable mutates config and
+// best-effort restarts the gateway; subscription changes hot-reload.
+
+export function getWebhooks(): Promise<WebhooksResponse> {
+  return hermesApi<WebhooksResponse>({
+    ...profileScoped(),
+    path: '/api/webhooks'
+  })
+}
+
+export function enableWebhooks(): Promise<WebhookEnableResponse> {
+  return hermesApi<WebhookEnableResponse>({
+    ...profileScoped(),
+    path: '/api/webhooks/enable',
+    method: 'POST'
+  })
+}
+
+export function createWebhook(body: WebhookCreatePayload): Promise<WebhookCreateResponse> {
+  return hermesApi<WebhookCreateResponse>({
+    ...profileScoped(),
+    path: '/api/webhooks',
+    method: 'POST',
+    body
+  })
+}
+
+export function deleteWebhook(name: string): Promise<{ ok: boolean }> {
+  return hermesApi<{ ok: boolean }>({
+    ...profileScoped(),
+    path: `/api/webhooks/${encodeURIComponent(name)}`,
+    method: 'DELETE'
+  })
+}
+
+export function setWebhookEnabled(
+  name: string,
+  enabled: boolean
+): Promise<{ enabled: boolean; name: string; ok: boolean }> {
+  return hermesApi<{ enabled: boolean; name: string; ok: boolean }>({
+    ...profileScoped(),
+    path: `/api/webhooks/${encodeURIComponent(name)}/enabled`,
+    method: 'PUT',
+    body: { enabled }
+  })
+}
diff --git a/apps/desktop/src/api/models.ts b/apps/desktop/src/api/models.ts
new file mode 100644
index 0000000000..0aa1ca951f
--- /dev/null
+++ b/apps/desktop/src/api/models.ts
@@ -0,0 +1,129 @@
+import type {
+  AnalyticsResponse,
+  AuxiliaryModelsResponse,
+  MoaConfigResponse,
+  ModelAssignmentRequest,
+  ModelAssignmentResponse,
+  ModelInfoResponse,
+  ModelOptionsResponse
+} from '@/types/hermes'
+
+import { capabilityScoped, hermesApi, type ProfileScope, profileScoped, STARTUP_REQUEST_TIMEOUT_MS } from './client'
+
+export function getGlobalModelInfo(profile?: null | string): Promise<ModelInfoResponse> {
+  return hermesApi<ModelInfoResponse>({
+    ...profileScoped(profile),
+    path: '/api/model/info',
+    timeoutMs: STARTUP_REQUEST_TIMEOUT_MS
+  })
+}
+
+export function getUsageAnalytics(days = 30, profile?: ProfileScope): Promise<AnalyticsResponse> {
+  return window.hermesDesktop.api<AnalyticsResponse>({
+    ...capabilityScoped(profile),
+    path: `/api/analytics/usage?days=${Math.max(1, Math.floor(days))}`
+  })
+}
+
+export function getGlobalModelOptions(
+  opts?: {
+    refresh?: boolean
+    includeUnconfigured?: boolean
+    explicitOnly?: boolean
+  },
+  profile?: null | string
+): Promise<ModelOptionsResponse> {
+  const params = new URLSearchParams()
+
+  if (opts?.refresh) {
+    params.set('refresh', '1')
+  }
+
+  if (opts?.includeUnconfigured) {
+    params.set('include_unconfigured', '1')
+  }
+
+  if (opts?.explicitOnly !== false) {
+    params.set('explicit_only', '1')
+  }
+
+  return hermesApi<ModelOptionsResponse>({
+    ...profileScoped(profile),
+    path: params.size > 0 ? `/api/model/options?${params.toString()}` : '/api/model/options',
+    timeoutMs: STARTUP_REQUEST_TIMEOUT_MS
+  })
+}
+
+export interface RecommendedDefaultModel {
+  provider: string
+  model: string
+  /** True/false for Nous (free vs paid tier); null for other providers. */
+  free_tier: boolean | null
+}
+
+// Recommended default model for a freshly-authenticated provider. Mirrors the
+// curation `hermes model` does — for Nous it honors the free/paid tier so a
+// free user gets a free model instead of a paid default.
+export function getRecommendedDefaultModel(
+  provider: string,
+  profile?: null | string
+): Promise<RecommendedDefaultModel> {
+  return hermesApi<RecommendedDefaultModel>({
+    ...profileScoped(profile),
+    path: `/api/model/recommended-default?provider=${encodeURIComponent(provider)}`
+  })
+}
+
+export function setGlobalModel(
+  provider: string,
+  model: string
+): Promise<{ ok: boolean; provider: string; model: string }> {
+  return hermesApi<{ ok: boolean; provider: string; model: string }>({
+    ...profileScoped(),
+    path: '/api/model/set',
+    method: 'POST',
+    body: {
+      scope: 'main',
+      provider,
+      model
+    }
+  })
+}
+
+export function getAuxiliaryModels(profile?: null | string): Promise<AuxiliaryModelsResponse> {
+  return hermesApi<AuxiliaryModelsResponse>({
+    ...profileScoped(profile),
+    path: '/api/model/auxiliary'
+  })
+}
+
+export function getMoaModels(profile?: null | string): Promise<MoaConfigResponse> {
+  return hermesApi<MoaConfigResponse>({
+    ...profileScoped(profile),
+    path: '/api/model/moa'
+  })
+}
+
+export function saveMoaModels(
+  body: MoaConfigResponse,
+  profile?: null | string
+): Promise<MoaConfigResponse & { ok: boolean }> {
+  return hermesApi<MoaConfigResponse & { ok: boolean }>({
+    ...profileScoped(profile),
+    path: '/api/model/moa',
+    method: 'PUT',
+    body
+  })
+}
+
+export function setModelAssignment(
+  body: ModelAssignmentRequest,
+  profile?: null | string
+): Promise<ModelAssignmentResponse> {
+  return hermesApi<ModelAssignmentResponse>({
+    ...profileScoped(profile),
+    path: '/api/model/set',
+    method: 'POST',
+    body
+  })
+}
diff --git a/apps/desktop/src/api/plugins.ts b/apps/desktop/src/api/plugins.ts
new file mode 100644
index 0000000000..ff8e4a6b0c
--- /dev/null
+++ b/apps/desktop/src/api/plugins.ts
@@ -0,0 +1,128 @@
+import type { HermesConnection } from '@/global'
+import { reconnectBackoffDelayMs } from '@/lib/reconnect-backoff'
+
+import { getApiRequestConnection, getApiRequestProfile, hermesApi, profileScoped } from './client'
+
+/** Resolve the ACTIVE backend's connection descriptor, (connectionId,
+ *  profile)-scoped — mirroring how store/profile resolves $connection: a
+ *  registry agent's descriptor comes from getConnectionFor (its SOURCE
+ *  connection), everything else from the profile-keyed local pool. The
+ *  getConnectionFor bridge is optional (older Desktop mains); without it the
+ *  profile-scoped pool lookup is the best available answer. */
+async function activeConnection(): Promise<HermesConnection> {
+  const getConnectionFor = window.hermesDesktop.getConnectionFor
+  const connectionId = getApiRequestConnection()
+
+  if (connectionId && getConnectionFor) {
+    return getConnectionFor({ connectionId, profile: getApiRequestProfile() })
+  }
+
+  return window.hermesDesktop.getConnection(getApiRequestProfile())
+}
+
+/** Options for a plugin REST call — mirrors the app's own `hermesDesktop.api`
+ *  shape, minus the path (which is namespace-derived). */
+export interface PluginRestOptions {
+  method?: string
+  body?: unknown
+  /** Single-file multipart upload (see HermesApiRequest.upload). */
+  upload?: { filename: string; contentType?: string; bytes: ArrayBuffer }
+  timeoutMs?: number
+}
+
+// Normalize `path` to a leading-slash suffix relative to `/api/plugins/<id>`.
+// The namespace is the boundary — reject `..` so a relative segment can't
+// normalize out into another plugin's API or a core route. Check the path
+// portion only (before any query/hash).
+function pluginPathSuffix(caller: string, path: string): string {
+  const suffix = path.startsWith('/') ? path : `/${path}`
+
+  if (suffix.split(/[?#]/, 1)[0].split('/').includes('..')) {
+    throw new Error(`${caller}: illegal path traversal in "${path}"`)
+  }
+
+  return suffix
+}
+
+/** The plugin REST door. Every call is scoped BY CONSTRUCTION to the plugin's
+ *  own backend namespace — `path` is relative to `/api/plugins/<pluginId>`
+ *  ('/board' → `/api/plugins/kanban/board`), so a plugin can't address another
+ *  plugin's API or a core route through it. Profile-aware like every desktop
+ *  REST call. Broader reach (core endpoints, another namespace) is the future
+ *  declared-capability seam; today the namespace IS the boundary. */
+export async function pluginRest<T>(pluginId: string, path: string, opts: PluginRestOptions = {}): Promise<T> {
+  if (!window.hermesDesktop?.api) {
+    throw new Error('Hermes desktop bridge unavailable')
+  }
+
+  const suffix = pluginPathSuffix('pluginRest', path)
+
+  return hermesApi<T>({
+    path: `/api/plugins/${pluginId}${suffix}`,
+    method: opts.method,
+    body: opts.body,
+    upload: opts.upload,
+    timeoutMs: opts.timeoutMs,
+    ...profileScoped()
+  })
+}
+
+/** The plugin WebSocket door — the live twin of `pluginRest`, scoped the same
+ *  way: `path` is relative to `/api/plugins/<pluginId>` ('/events' → the
+ *  plugin's own event stream). Token-mode backends auth via the same query
+ *  credential the app's own sockets use; OAuth remotes resolve null (callers
+ *  keep their polling fallback — every consumer must have one anyway, since a
+ *  socket can drop). Auto-reconnects with backoff until disposed. */
+export function pluginSocket(pluginId: string, path: string, onMessage: (data: unknown) => void): () => void {
+  const suffix = pluginPathSuffix('pluginSocket', path)
+
+  let socket: null | WebSocket = null
+  let disposed = false
+  let attempt = 0
+
+  const connect = async () => {
+    const connection = await activeConnection().catch(() => null)
+
+    // No bridge / OAuth cookie auth (WS tickets are single-use, core-managed):
+    // stay on the polling fallback rather than half-working.
+    if (disposed || !connection || connection.authMode === 'oauth') {
+      return
+    }
+
+    const base = connection.baseUrl.replace(/^http/, 'ws')
+    const join = suffix.includes('?') ? '&' : '?'
+    socket = new WebSocket(
+      `${base}/api/plugins/${pluginId}${suffix}${join}token=${encodeURIComponent(connection.token)}`
+    )
+
+    socket.onmessage = event => {
+      attempt = 0
+
+      try {
+        onMessage(JSON.parse(String(event.data)))
+      } catch {
+        // Non-JSON frame — plugin streams are JSON by contract; skip it.
+      }
+    }
+
+    socket.onclose = () => {
+      socket = null
+
+      if (!disposed) {
+        // Full-jitter exponential backoff: same rationale as the gateway
+        // socket reconnect loops — an immediate-retry loop across many
+        // desktop clients floods the gateway with connection attempts
+        // during a restart.
+        window.setTimeout(() => void connect(), reconnectBackoffDelayMs(attempt, { baseDelayMs: 500, capMs: 30_000 }))
+        attempt += 1
+      }
+    }
+  }
+
+  void connect()
+
+  return () => {
+    disposed = true
+    socket?.close()
+  }
+}
diff --git a/apps/desktop/src/api/profiles.ts b/apps/desktop/src/api/profiles.ts
new file mode 100644
index 0000000000..52fc090906
--- /dev/null
+++ b/apps/desktop/src/api/profiles.ts
@@ -0,0 +1,89 @@
+import type {
+  ProfileCreatePayload,
+  ProfileDesktopOverlay,
+  ProfileSetupCommand,
+  ProfileSoul,
+  ProfilesResponse
+} from '@/types/hermes'
+
+import { hermesApi, STARTUP_REQUEST_TIMEOUT_MS } from './client'
+
+export function getProfiles(): Promise<ProfilesResponse> {
+  return hermesApi<ProfilesResponse>({
+    path: '/api/profiles',
+    timeoutMs: STARTUP_REQUEST_TIMEOUT_MS
+  })
+}
+
+export function createProfile(body: ProfileCreatePayload): Promise<{ name: string; ok: boolean; path: string }> {
+  return hermesApi<{ name: string; ok: boolean; path: string }>({
+    path: '/api/profiles',
+    method: 'POST',
+    body
+  })
+}
+
+export function renameProfile(name: string, newName: string): Promise<{ name: string; ok: boolean; path: string }> {
+  return hermesApi<{ name: string; ok: boolean; path: string }>({
+    path: `/api/profiles/${encodeURIComponent(name)}`,
+    method: 'PATCH',
+    body: { new_name: newName }
+  })
+}
+
+export function deleteProfile(name: string): Promise<{ ok: boolean; path: string }> {
+  return hermesApi<{ ok: boolean; path: string }>({
+    path: `/api/profiles/${encodeURIComponent(name)}`,
+    method: 'DELETE'
+  })
+}
+
+export function getProfileSoul(name: string): Promise<ProfileSoul> {
+  return hermesApi<ProfileSoul>({
+    path: `/api/profiles/${encodeURIComponent(name)}/soul`
+  })
+}
+
+export function updateProfileSoul(name: string, content: string): Promise<{ ok: boolean }> {
+  return hermesApi<{ ok: boolean }>({
+    path: `/api/profiles/${encodeURIComponent(name)}/soul`,
+    method: 'PUT',
+    body: { content }
+  })
+}
+
+export function getProfileSetupCommand(name: string): Promise<ProfileSetupCommand> {
+  return hermesApi<ProfileSetupCommand>({
+    path: `/api/profiles/${encodeURIComponent(name)}/setup-command`
+  })
+}
+
+/** Export a profile to a shareable .tar.gz on the backend's filesystem.
+ *  `extraFiles` stages extra root-level files (desktop.json — the appearance/
+ *  interface overlay) into the archive alongside the profile's own artifacts. */
+export function exportProfileArchive(
+  name: string,
+  opts: { extraFiles?: Record<string, string>; output?: string } = {}
+): Promise<{ archive: string; ok: boolean }> {
+  return hermesApi<{ archive: string; ok: boolean }>({
+    path: `/api/profiles/${encodeURIComponent(name)}/export`,
+    method: 'POST',
+    body: { extra_files: opts.extraFiles ?? {}, output: opts.output ?? '' },
+    timeoutMs: STARTUP_REQUEST_TIMEOUT_MS
+  })
+}
+
+/** Import a profile .tar.gz as a new profile. Returns the bundled desktop
+ *  appearance overlay too (when the archive carried one) so the caller can
+ *  apply theme/layout without another round-trip. */
+export function importProfileArchive(
+  archive: string,
+  name?: string
+): Promise<{ desktop: null | ProfileDesktopOverlay; name: string; ok: boolean; path: string }> {
+  return hermesApi<{ desktop: null | ProfileDesktopOverlay; name: string; ok: boolean; path: string }>({
+    path: '/api/profiles/import',
+    method: 'POST',
+    body: { archive, name: name || null },
+    timeoutMs: STARTUP_REQUEST_TIMEOUT_MS
+  })
+}
diff --git a/apps/desktop/src/api/sessions.ts b/apps/desktop/src/api/sessions.ts
new file mode 100644
index 0000000000..e8f17ac226
--- /dev/null
+++ b/apps/desktop/src/api/sessions.ts
@@ -0,0 +1,465 @@
+import { isMissingRestEndpoint } from '@/lib/gateway-rpc'
+import { recordTranscriptTail } from '@/store/transcript-tail'
+import type {
+  PaginatedSessions,
+  SessionInfo,
+  SessionMessage,
+  SessionMessagesResponse,
+  SessionSearchResponse
+} from '@/types/hermes'
+
+import { hermesApi } from './client'
+
+const SESSION_LIST_REQUEST_TIMEOUT_MS = 60_000
+
+/**
+ * Trim a page to its window WITHOUT discarding pinned rows.
+ *
+ * The list endpoints deliberately back-fill pinned conversations past their
+ * LIMIT — a pin means "always reachable", so an aged-out pinned chat is
+ * appended after the recency window. A plain `slice(0, limit)` throws exactly
+ * those rows away again, which is why pins silently stopped rendering past
+ * some count: the sidebar could only ever show the pins that happened to fall
+ * inside the most-recent page.
+ */
+function pageWindow(sessions: SessionInfo[], limit: number): SessionInfo[] {
+  if (sessions.length <= limit) {
+    return sessions
+  }
+
+  const recent = sessions.slice(0, limit)
+
+  return [...recent, ...sessions.slice(limit).filter(session => session.pinned)]
+}
+
+export async function listSessions(
+  limit = 40,
+  minMessages = 0,
+  archived: 'exclude' | 'include' | 'only' = 'exclude',
+  order: 'created' | 'recent' = 'recent'
+): Promise<PaginatedSessions> {
+  const result = await hermesApi<PaginatedSessions>({
+    path:
+      `/api/sessions?limit=${limit}&offset=0&min_messages=${Math.max(0, minMessages)}` +
+      `&archived=${archived}&order=${order}`,
+    timeoutMs: SESSION_LIST_REQUEST_TIMEOUT_MS
+  })
+
+  return {
+    ...result,
+    sessions: pageWindow(result.sessions, limit),
+    offset: 0
+  }
+}
+
+// Unified, read-only session list aggregated across ALL profiles. Served by the
+// primary backend straight off each profile's state.db — no per-profile backend
+// is spawned. Single-profile users get the same rows as listSessions(), tagged
+// profile="default".
+// Source scoping lets callers split the unified list into independent slices:
+// recents pass `excludeSources: ['cron']`, the cron-jobs section passes
+// `source: 'cron'`. Without this a burst of (always-newest) cron sessions
+// consumes the whole recents page and starves real conversations.
+export interface SessionSourceFilter {
+  source?: string
+  excludeSources?: string[]
+}
+
+export async function listAllProfileSessions(
+  limit = 40,
+  minMessages = 0,
+  archived: 'exclude' | 'include' | 'only' = 'exclude',
+  order: 'created' | 'recent' = 'recent',
+  profile: 'all' | (string & {}) = 'all',
+  filter: SessionSourceFilter = {}
+): Promise<PaginatedSessions> {
+  const sourceParam = filter.source ? `&source=${encodeURIComponent(filter.source)}` : ''
+
+  const excludeParam = filter.excludeSources?.length
+    ? `&exclude_sources=${encodeURIComponent(filter.excludeSources.join(','))}`
+    : ''
+
+  const result = await hermesApi<PaginatedSessions>({
+    path:
+      `/api/profiles/sessions?limit=${limit}&offset=0&min_messages=${Math.max(0, minMessages)}` +
+      `&archived=${archived}&order=${order}&profile=${encodeURIComponent(profile)}${sourceParam}${excludeParam}`,
+    timeoutMs: SESSION_LIST_REQUEST_TIMEOUT_MS
+  })
+
+  return {
+    ...result,
+    sessions: pageWindow(result.sessions, limit),
+    offset: 0
+  }
+}
+
+// Batched sidebar slices in one request: recents (scoped to the active profile),
+// cron, and messaging. The backend opens each profile's state.db once and runs
+// all three filtered queries, replacing three separate listAllProfileSessions
+// calls that each reopened + re-counted every profile DB per refresh. Electron
+// splices remote profiles per slice (see interceptSessionRequestForRemote).
+export interface SidebarSessionSlice {
+  sessions: SessionInfo[]
+  /** Per-profile "the window came back full, more rows exist on disk" flags —
+   *  what pagination needs, without a COUNT(*) per profile DB per refresh. */
+  profiles_truncated?: Record<string, boolean>
+  /** Per-profile tokens and spend over every session, not just this window.
+   *  Absent from the legacy per-slice endpoint, which has no aggregate. */
+  profiles_usage?: Record<string, { cost_usd: number; tokens: number }>
+}
+
+/** Which profiles filled their per-profile window in a returned page. The
+ *  legacy per-slice endpoint doesn't report this, so derive it from the rows:
+ *  a profile at (or over) the cap still has more on disk. Pinned rows are
+ *  discounted — they're back-filled past the LIMIT, so counting them fakes a
+ *  full page and leaves a "Load more" that can never resolve. */
+function profilesTruncatedFrom(sessions: SessionInfo[], cap: number): Record<string, boolean> {
+  const counts = new Map<string, number>()
+
+  for (const session of sessions) {
+    const key = session.profile || 'default'
+
+    counts.set(key, (counts.get(key) ?? 0) + (session.pinned ? 0 : 1))
+  }
+
+  return Object.fromEntries([...counts].map(([name, count]) => [name, count >= cap]))
+}
+
+export interface SidebarSessionsResponse {
+  recents: SidebarSessionSlice
+  cron: SidebarSessionSlice
+  messaging: SidebarSessionSlice
+  errors?: Array<{ profile: string; error: string }>
+}
+
+export interface SidebarSessionsRequest {
+  recentsProfile: 'all' | (string & {})
+  recentsLimit: number
+  recentsExclude: string[]
+  cronLimit: number
+  messagingLimit: number
+  messagingExclude: string[]
+}
+
+// The batched /sidebar endpoint shipped later than the per-slice route, so a
+// newer desktop can meet an older backend that 404s it ("No such API
+// endpoint"). Endpoint-missing is a capability signal, not a transient
+// failure: remember it (per renderer lifetime — a runtime home change reloads
+// the window and re-probes) and serve every subsequent refresh straight from
+// the three proven per-slice calls instead of re-probing a known-dead route
+// once per turn/broadcast.
+let sidebarBatchEndpointMissing = false
+
+// Capability flags are per-backend facts. A hard re-home reloads the window
+// (module state resets naturally), but a soft gateway switch re-dials in
+// place — the next backend may well have the batched route, so the switch
+// paths call this to re-probe rather than leak the old backend's capability.
+export function resetSidebarBatchCapability() {
+  sidebarBatchEndpointMissing = false
+}
+
+// Compatibility fallback: reassemble the three sidebar slices from the
+// per-slice endpoint, mirroring the batched route's semantics (min_messages=1,
+// archived excluded, recency order; every slice scoped to the caller's profile).
+// Rides the same Electron remote-splice
+// interception as the pre-batching desktop, so remote profiles stay correct.
+async function listSidebarSessionsLegacy(req: SidebarSessionsRequest): Promise<SidebarSessionsResponse> {
+  const [recents, cron, messaging] = await Promise.all([
+    listAllProfileSessions(req.recentsLimit, 1, 'exclude', 'recent', req.recentsProfile, {
+      excludeSources: req.recentsExclude
+    }),
+    listAllProfileSessions(req.cronLimit, 1, 'exclude', 'recent', req.recentsProfile, { source: 'cron' }),
+    listAllProfileSessions(req.messagingLimit, 1, 'exclude', 'recent', req.recentsProfile, {
+      excludeSources: req.messagingExclude
+    })
+  ])
+
+  const errors = [...(recents.errors ?? []), ...(cron.errors ?? []), ...(messaging.errors ?? [])]
+
+  return {
+    recents: {
+      profiles_truncated: profilesTruncatedFrom(recents.sessions, req.recentsLimit),
+      sessions: recents.sessions
+    },
+    cron: { sessions: cron.sessions },
+    messaging: { sessions: messaging.sessions },
+    ...(errors.length ? { errors } : {})
+  }
+}
+
+/** The PR each of these sessions opened, recovered from its own transcript —
+ *  for sessions whose recorded branch can't answer (they started on trunk and
+ *  did the work in a worktree). Also returns every id it looked at, so the
+ *  caller can remember a miss and never ask again. */
+export function scanSessionPullRequests(
+  ids: string[]
+): Promise<{ pull_requests: Record<string, { number: number; url: string }>; scanned: string[] }> {
+  return hermesApi<{
+    pull_requests: Record<string, { number: number; url: string }>
+    scanned: string[]
+  }>({
+    path: '/api/profiles/sessions/pull-requests',
+    method: 'POST',
+    body: { ids }
+  })
+}
+
+export async function listSidebarSessions(req: SidebarSessionsRequest): Promise<SidebarSessionsResponse> {
+  if (sidebarBatchEndpointMissing) {
+    return listSidebarSessionsLegacy(req)
+  }
+
+  const params = new URLSearchParams({
+    recents_profile: req.recentsProfile,
+    recents_limit: String(Math.max(1, req.recentsLimit)),
+    cron_limit: String(Math.max(1, req.cronLimit)),
+    messaging_limit: String(Math.max(1, req.messagingLimit))
+  })
+
+  if (req.recentsExclude.length) {
+    params.set('recents_exclude', req.recentsExclude.join(','))
+  }
+
+  if (req.messagingExclude.length) {
+    params.set('messaging_exclude', req.messagingExclude.join(','))
+  }
+
+  let result: SidebarSessionsResponse
+
+  try {
+    result = await hermesApi<SidebarSessionsResponse>({
+      path: `/api/profiles/sessions/sidebar?${params.toString()}`,
+      timeoutMs: SESSION_LIST_REQUEST_TIMEOUT_MS
+    })
+  } catch (err) {
+    // Safe to read a 404 as route-missing here: this GET has no path params,
+    // so it cannot 404 on a bad id.
+    if (!isMissingRestEndpoint(err)) {
+      throw err
+    }
+
+    // Older backend without the batched route (desktop/runtime version skew).
+    sidebarBatchEndpointMissing = true
+
+    return listSidebarSessionsLegacy(req)
+  }
+
+  return {
+    recents: { ...result.recents, sessions: result.recents?.sessions ?? [] },
+    cron: { ...result.cron, sessions: result.cron?.sessions ?? [] },
+    messaging: { ...result.messaging, sessions: result.messaging?.sessions ?? [] },
+    errors: result.errors
+  }
+}
+
+// Mutations take the owning `profile` so Electron can route them to the correct
+// remote backend or local profile scope. Omit for the current/default profile.
+export function setSessionArchived(id: string, archived: boolean, profile?: string | null): Promise<{ ok: boolean }> {
+  return hermesApi<{ ok: boolean }>({
+    ...(profile ? { profile } : {}),
+    path: `/api/sessions/${encodeURIComponent(id)}`,
+    method: 'PATCH',
+    body: { archived }
+  })
+}
+
+// Mirror a sidebar pin to the backend "keep" flag so the sessions.auto_archive
+// sweep (which runs backend-side, blind to Desktop localStorage) never hides a
+// pinned chat. Best-effort: the sidebar stays localStorage-driven for its own
+// display; this only feeds the backend policy.
+export function setSessionPinnedRemote(id: string, pinned: boolean, profile?: string | null): Promise<{ ok: boolean }> {
+  return hermesApi<{ ok: boolean }>({
+    ...(profile ? { profile } : {}),
+    path: `/api/sessions/${encodeURIComponent(id)}`,
+    method: 'PATCH',
+    body: { pinned }
+  })
+}
+
+// Mirror a sidebar unread toggle to the backend read-state watermark
+// (sessions.last_read_at via SessionDB.set_session_read). Same profile
+// routing as the other session mutations: a remote session's row lives only
+// on its remote host, so the owning profile must travel with the request.
+export function setSessionUnreadRemote(id: string, unread: boolean, profile?: string | null): Promise<{ ok: boolean }> {
+  return hermesApi<{ ok: boolean }>({
+    ...(profile ? { profile } : {}),
+    path: `/api/sessions/${encodeURIComponent(id)}`,
+    method: 'PATCH',
+    body: { unread }
+  })
+}
+
+export function searchSessions(query: string): Promise<SessionSearchResponse> {
+  return hermesApi<SessionSearchResponse>({
+    path: `/api/sessions/search?q=${encodeURIComponent(query)}`
+  })
+}
+
+// Resolves a single session row by id on one backend (the active profile, or
+// the given `profile`). The backend resolves exact ids and unique prefixes and
+// 404s when the id isn't on that profile — so a cheap by-id lookup replaces the
+// cross-profile list scan when locating an unknown id's owner.
+export function getSession(id: string, profile?: string | null): Promise<SessionInfo> {
+  const suffix = profile ? `?profile=${encodeURIComponent(profile)}` : ''
+
+  return hermesApi<SessionInfo>({
+    ...(profile ? { profile } : {}),
+    path: `/api/sessions/${encodeURIComponent(id)}${suffix}`
+  })
+}
+
+// Reads another profile's transcript. For a remote profile Electron reroutes
+// this GET to the remote backend (which serves its own state.db); for a local
+// profile the primary opens that profile's state.db via ?profile=. Omit for
+// the current/default profile.
+export function getSessionMessages(
+  id: string,
+  profile?: string | null,
+  page: { limit?: number; offset?: number; order?: 'latest' | 'oldest'; includeCompacted?: boolean } = {}
+): Promise<SessionMessagesResponse> {
+  const query = new URLSearchParams()
+
+  if (profile) {
+    query.set('profile', profile)
+  }
+
+  if (page.limit !== undefined) {
+    query.set('limit', String(page.limit))
+  }
+
+  if (page.offset !== undefined) {
+    query.set('offset', String(page.offset))
+  }
+
+  if (page.order) {
+    query.set('order', page.order)
+  }
+
+  if (page.includeCompacted !== undefined) {
+    query.set('include_compacted', String(page.includeCompacted))
+  }
+
+  const suffix = query.size ? `?${query.toString()}` : ''
+
+  return hermesApi<SessionMessagesResponse>({
+    ...(profile ? { profile } : {}),
+    path: `/api/sessions/${encodeURIComponent(id)}/messages${suffix}`
+  })
+}
+
+/**
+ * The initial hydration page: enough tail to fill the transcript window a few
+ * times over, small enough that opening a long session doesn't ship (and
+ * convert) hundreds of rows nobody has scrolled to. Older rows load on demand
+ * via `getOlderSessionMessages` when "Show earlier" exhausts the in-memory
+ * store (see app/chat/transcript-backfill).
+ */
+export const LATEST_SESSION_MESSAGES_LIMIT = 120
+
+export function getLatestSessionMessages(id: string, profile?: string | null): Promise<SessionMessagesResponse> {
+  // includeCompacted: durable display history must include rows preserved by
+  // in-place compaction (active=0, compacted=1); without them the transcript
+  // silently ends at the compaction boundary and earlier turns are unreachable.
+  return getSessionMessages(id, profile, {
+    limit: LATEST_SESSION_MESSAGES_LIMIT,
+    order: 'latest',
+    includeCompacted: true
+  }).then(page => {
+    // Record whether the tail was truncated (page came back full) and where
+    // the next older page starts, so "Show earlier" can backfill over REST
+    // (app/chat/transcript-backfill). Keyed under both the requested id and
+    // the resolved id — callers hold either.
+    recordTranscriptTail(id, page, profile)
+
+    if (page.session_id && page.session_id !== id) {
+      recordTranscriptTail(page.session_id, page, profile)
+    }
+
+    return page
+  })
+}
+
+/**
+ * One page of messages OLDER than the `offset` newest rows.
+ *
+ * Backend semantics (`_handle_session_messages` → `SessionDB.get_messages`
+ * with `latest=True`): the offset is measured back from the NEWEST message
+ * and the selected page is returned in chronological order. So after a tail
+ * hydration of N rows, `getOlderSessionMessages(id, profile, N)` returns the
+ * page immediately preceding it, ready to prepend.
+ *
+ * Legacy backends without pagination support return the full transcript and
+ * no `pagination` metadata — callers detect that via the missing field and
+ * treat the response as the complete history (see transcript-backfill).
+ */
+export function getOlderSessionMessages(
+  id: string,
+  profile: string | null | undefined,
+  offset: number,
+  limit: number = LATEST_SESSION_MESSAGES_LIMIT
+): Promise<SessionMessagesResponse> {
+  return getSessionMessages(id, profile, { includeCompacted: true, limit, offset, order: 'latest' })
+}
+
+export async function getAllSessionMessages(
+  id: string,
+  profile?: string | null,
+  options: { maxJsonChars?: number } = {}
+): Promise<SessionMessagesResponse> {
+  const messages: SessionMessage[] = []
+  const pageSize = 500
+  const maxJsonChars = options.maxJsonChars ?? 32_000_000
+  let jsonChars = 0
+  let offset = 0
+  let resolvedSessionId = id
+
+  while (true) {
+    const page = await getSessionMessages(id, profile, {
+      limit: pageSize,
+      offset,
+      order: 'oldest',
+      includeCompacted: true
+    })
+
+    resolvedSessionId = page.session_id
+    jsonChars += (JSON.stringify(page.messages) ?? '').length
+
+    if (jsonChars > maxJsonChars) {
+      throw new Error(
+        'Session transcript exceeds the Desktop safe-load limit; use the Web Dashboard export for this session.'
+      )
+    }
+
+    messages.push(...page.messages)
+
+    // Legacy backends ignore pagination and return the full transcript.
+    if (!page.pagination || page.messages.length === 0 || page.messages.length < page.pagination.limit) {
+      break
+    }
+
+    offset += page.messages.length
+  }
+
+  return { session_id: resolvedSessionId, messages }
+}
+
+export function deleteSession(id: string, profile?: string | null): Promise<{ ok: boolean }> {
+  return hermesApi<{ ok: boolean }>({
+    ...(profile ? { profile } : {}),
+    path: `/api/sessions/${encodeURIComponent(id)}`,
+    method: 'DELETE'
+  })
+}
+
+export function renameSession(
+  id: string,
+  title: string,
+  profile?: string | null
+): Promise<{ ok: boolean; title: string }> {
+  return hermesApi<{ ok: boolean; title: string }>({
+    ...(profile ? { profile } : {}),
+    path: `/api/sessions/${encodeURIComponent(id)}`,
+    method: 'PATCH',
+    body: { title, ...(profile ? { profile } : {}) }
+  })
+}
diff --git a/apps/desktop/src/api/skills.ts b/apps/desktop/src/api/skills.ts
new file mode 100644
index 0000000000..cf29d2daf2
--- /dev/null
+++ b/apps/desktop/src/api/skills.ts
@@ -0,0 +1,162 @@
+import type {
+  SkillHubPreview,
+  SkillHubScanResult,
+  SkillHubSearchResponse,
+  SkillHubSourcesResponse,
+  SkillInfo,
+  StarmapGraph
+} from '@/types/hermes'
+import type { ActionResponse } from '@/types/hermes'
+
+import { capabilityScoped, hermesApi, type ProfileScope, profileScoped } from './client'
+
+export function getSkills(profile?: ProfileScope): Promise<SkillInfo[]> {
+  return window.hermesDesktop.api<SkillInfo[]>({
+    ...capabilityScoped(profile),
+    path: '/api/skills'
+  })
+}
+
+/** Raw SKILL.md text (frontmatter included) for ANY skill — bundled, hub, or
+ *  learned — backing the Capabilities detail pane's full-skill view. */
+export function getSkillContent(
+  name: string,
+  profile?: ProfileScope
+): Promise<{ content: string; name: string; path: string }> {
+  return window.hermesDesktop.api<{ content: string; name: string; path: string }>({
+    ...capabilityScoped(profile),
+    path: `/api/skills/content?name=${encodeURIComponent(name)}`
+  })
+}
+
+export function setSkillEnabled(
+  name: string,
+  enabled: boolean,
+  profile?: ProfileScope
+): Promise<{ ok: boolean; name: string; enabled: boolean }> {
+  return window.hermesDesktop.api<{ ok: boolean; name: string; enabled: boolean }>({
+    ...capabilityScoped(profile),
+    path: '/api/skills/toggle',
+    method: 'PUT',
+    body: { name, enabled }
+  })
+}
+
+export function getStarmapGraph(): Promise<StarmapGraph> {
+  return hermesApi<StarmapGraph>({
+    ...profileScoped(),
+    // Backend REST contract — stays /api/learning even though the UI feature is
+    // now "star map". Renaming this would break against an un-upgraded backend.
+    path: '/api/learning/graph'
+  })
+}
+
+export interface LearningNodeDetail {
+  content: string
+  kind: 'memory' | 'skill'
+  label: string
+  ok: boolean
+}
+
+export function getLearningNode(id: string, profile?: ProfileScope): Promise<LearningNodeDetail> {
+  return window.hermesDesktop.api<LearningNodeDetail>({
+    ...capabilityScoped(profile),
+    path: `/api/learning/node?id=${encodeURIComponent(id)}`
+  })
+}
+
+export function deleteLearningNode(id: string, profile?: ProfileScope): Promise<{ message: string; ok: boolean }> {
+  return window.hermesDesktop.api<{ message: string; ok: boolean }>({
+    ...capabilityScoped(profile),
+    path: '/api/learning/node',
+    method: 'DELETE',
+    body: { id }
+  })
+}
+
+export function editLearningNode(
+  id: string,
+  content: string,
+  profile?: ProfileScope
+): Promise<{ message: string; ok: boolean }> {
+  return window.hermesDesktop.api<{ message: string; ok: boolean }>({
+    ...capabilityScoped(profile),
+    path: '/api/learning/node',
+    method: 'PUT',
+    body: { content, id }
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Skills hub — search / preview / scan / install (parity with `hermes skills`
+// and the dashboard's Browse-hub tab). Installs spawn background actions whose
+// logs are tailed via getActionStatus().
+// ---------------------------------------------------------------------------
+
+const HUB_REQUEST_TIMEOUT_MS = 45_000
+
+export function getSkillHubSources(profile?: null | string): Promise<SkillHubSourcesResponse> {
+  return hermesApi<SkillHubSourcesResponse>({
+    ...profileScoped(profile),
+    path: '/api/skills/hub/sources',
+    timeoutMs: HUB_REQUEST_TIMEOUT_MS
+  })
+}
+
+export function searchSkillsHub(
+  query: string,
+  source = 'all',
+  limit = 20,
+  profile?: null | string
+): Promise<SkillHubSearchResponse> {
+  const params = new URLSearchParams({ q: query, source, limit: String(limit) })
+
+  return hermesApi<SkillHubSearchResponse>({
+    ...profileScoped(profile),
+    path: `/api/skills/hub/search?${params.toString()}`,
+    timeoutMs: HUB_REQUEST_TIMEOUT_MS
+  })
+}
+
+export function previewSkillHub(identifier: string, profile?: null | string): Promise<SkillHubPreview> {
+  return hermesApi<SkillHubPreview>({
+    ...profileScoped(profile),
+    path: `/api/skills/hub/preview?identifier=${encodeURIComponent(identifier)}`,
+    timeoutMs: HUB_REQUEST_TIMEOUT_MS
+  })
+}
+
+export function scanSkillHub(identifier: string, profile?: null | string): Promise<SkillHubScanResult> {
+  return hermesApi<SkillHubScanResult>({
+    ...profileScoped(profile),
+    path: `/api/skills/hub/scan?identifier=${encodeURIComponent(identifier)}`,
+    timeoutMs: HUB_REQUEST_TIMEOUT_MS
+  })
+}
+
+export function installSkillFromHub(identifier: string, profile?: ProfileScope): Promise<ActionResponse> {
+  return window.hermesDesktop.api<ActionResponse>({
+    ...capabilityScoped(profile),
+    path: '/api/skills/hub/install',
+    method: 'POST',
+    body: { identifier }
+  })
+}
+
+export function uninstallSkillFromHub(name: string, profile?: ProfileScope): Promise<ActionResponse> {
+  return window.hermesDesktop.api<ActionResponse>({
+    ...capabilityScoped(profile),
+    path: '/api/skills/hub/uninstall',
+    method: 'POST',
+    body: { name }
+  })
+}
+
+export function updateSkillsFromHub(profile?: ProfileScope): Promise<ActionResponse> {
+  return window.hermesDesktop.api<ActionResponse>({
+    ...capabilityScoped(profile),
+    path: '/api/skills/hub/update',
+    method: 'POST',
+    body: {}
+  })
+}
diff --git a/apps/desktop/src/api/system.ts b/apps/desktop/src/api/system.ts
new file mode 100644
index 0000000000..678d09e549
--- /dev/null
+++ b/apps/desktop/src/api/system.ts
@@ -0,0 +1,247 @@
+import type {
+  ActionResponse,
+  ActionStatusResponse,
+  AudioSpeakResponse,
+  AudioTranscriptionResponse,
+  BackendUpdateCheckResponse,
+  CuratorStatusResponse,
+  DebugShareResponse,
+  ElevenLabsVoicesResponse,
+  MemoryProviderConfig,
+  MemoryProviderOAuthStatus,
+  MemoryStatusResponse
+} from '@/types/hermes'
+
+import { capabilityScoped, hermesApi, type ProfileScope, profileScoped } from './client'
+
+export const AUDIO_SPEAK_MIN_REQUEST_TIMEOUT_MS = 180_000
+export const AUDIO_SPEAK_MAX_REQUEST_TIMEOUT_MS = 600_000
+const AUDIO_SPEAK_TIMEOUT_MS_PER_CHAR = 35
+
+export function audioSpeakRequestTimeoutMs(text: string): number {
+  const estimated = Math.max(
+    AUDIO_SPEAK_MIN_REQUEST_TIMEOUT_MS,
+    Math.ceil(String(text || '').length * AUDIO_SPEAK_TIMEOUT_MS_PER_CHAR)
+  )
+
+  return Math.min(AUDIO_SPEAK_MAX_REQUEST_TIMEOUT_MS, estimated)
+}
+
+export const AUDIO_TRANSCRIBE_MIN_REQUEST_TIMEOUT_MS = 180_000
+export const AUDIO_TRANSCRIBE_MAX_REQUEST_TIMEOUT_MS = 600_000
+// The transcribe payload is the base64 audio data URL itself, so its string
+// length tracks clip size. ~0.1ms/char keeps short clips at the floor while
+// letting multi-minute recordings scale toward the cap (a base64 char is
+// ~0.75 bytes, so at 128kbps ≈ 21k chars/s of audio this budgets ~2s of
+// timeout per 1s of audio before the cap clamps it).
+const AUDIO_TRANSCRIBE_TIMEOUT_MS_PER_CHAR = 0.1
+
+export function audioTranscribeRequestTimeoutMs(dataUrl: string): number {
+  const estimated = Math.max(
+    AUDIO_TRANSCRIBE_MIN_REQUEST_TIMEOUT_MS,
+    Math.ceil(String(dataUrl || '').length * AUDIO_TRANSCRIBE_TIMEOUT_MS_PER_CHAR)
+  )
+
+  return Math.min(AUDIO_TRANSCRIBE_MAX_REQUEST_TIMEOUT_MS, estimated)
+}
+
+// surface=declared serves the curated desktop schema; the dashboard consumes the raw plugin schema.
+export function getMemoryProviderConfig(provider: string, profile?: null | string): Promise<MemoryProviderConfig> {
+  return hermesApi<MemoryProviderConfig>({
+    ...profileScoped(profile),
+    path: `/api/memory/providers/${encodeURIComponent(provider)}/config?surface=declared`
+  })
+}
+
+export function saveMemoryProviderConfig(
+  provider: string,
+  values: Record<string, string>,
+  profile?: null | string
+): Promise<{ ok: boolean }> {
+  return hermesApi<{ ok: boolean }>({
+    ...profileScoped(profile),
+    path: `/api/memory/providers/${encodeURIComponent(provider)}/config?surface=declared`,
+    method: 'PUT',
+    body: { values }
+  })
+}
+
+// Memory-provider OAuth connect (provider-keyed; 404s for providers without an
+// OAuth flow). Profile-scoped: the grant lands in the active profile's config.
+export function startMemoryProviderOAuth(
+  provider: string,
+  profile?: null | string
+): Promise<MemoryProviderOAuthStatus> {
+  return hermesApi<MemoryProviderOAuthStatus>({
+    ...profileScoped(profile),
+    path: `/api/memory/providers/${encodeURIComponent(provider)}/oauth/start`,
+    method: 'POST'
+  })
+}
+
+export function getMemoryProviderOAuthStatus(
+  provider: string,
+  profile?: null | string
+): Promise<MemoryProviderOAuthStatus> {
+  return hermesApi<MemoryProviderOAuthStatus>({
+    ...profileScoped(profile),
+    path: `/api/memory/providers/${encodeURIComponent(provider)}/oauth/status`
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Memory data + curator (parity with `hermes memory` / `hermes curator`).
+// ---------------------------------------------------------------------------
+
+export function getMemoryStatus(): Promise<MemoryStatusResponse> {
+  return hermesApi<MemoryStatusResponse>({
+    ...profileScoped(),
+    path: '/api/memory'
+  })
+}
+
+export function resetMemory(target: 'all' | 'memory' | 'user'): Promise<{ ok: boolean; deleted: string[] }> {
+  return hermesApi<{ ok: boolean; deleted: string[] }>({
+    ...profileScoped(),
+    path: '/api/memory/reset',
+    method: 'POST',
+    body: { target }
+  })
+}
+
+export function getCuratorStatus(): Promise<CuratorStatusResponse> {
+  return hermesApi<CuratorStatusResponse>({
+    ...profileScoped(),
+    path: '/api/curator'
+  })
+}
+
+export function setCuratorPaused(paused: boolean): Promise<{ ok: boolean; paused: boolean }> {
+  return hermesApi<{ ok: boolean; paused: boolean }>({
+    ...profileScoped(),
+    path: '/api/curator/paused',
+    method: 'PUT',
+    body: { paused }
+  })
+}
+
+export function runCurator(): Promise<ActionResponse> {
+  return hermesApi<ActionResponse>({
+    ...profileScoped(),
+    path: '/api/curator/run',
+    method: 'POST',
+    body: {}
+  })
+}
+
+export function restartGateway(): Promise<ActionResponse> {
+  return hermesApi<ActionResponse>({
+    ...profileScoped(),
+    path: '/api/gateway/restart',
+    method: 'POST'
+  })
+}
+
+export function updateHermes(): Promise<ActionResponse> {
+  return hermesApi<ActionResponse>({
+    ...profileScoped(),
+    path: '/api/hermes/update',
+    method: 'POST'
+  })
+}
+
+/** Query the connected backend's own update state. In remote mode this is the
+ *  authoritative source for the backend's behind-count + "what's changed",
+ *  distinct from the Electron client clone's git state. */
+export function checkHermesUpdate(force = false): Promise<BackendUpdateCheckResponse> {
+  return hermesApi<BackendUpdateCheckResponse>({
+    ...profileScoped(),
+    path: `/api/hermes/update/check${force ? '?force=true' : ''}`
+  })
+}
+
+export function getActionStatus(name: string, lines = 200, profile?: ProfileScope): Promise<ActionStatusResponse> {
+  return window.hermesDesktop.api<ActionStatusResponse>({
+    ...capabilityScoped(profile),
+    path: `/api/actions/${encodeURIComponent(name)}/status?lines=${Math.max(1, lines)}`
+  })
+}
+
+export function transcribeAudio(dataUrl: string, mimeType?: string): Promise<AudioTranscriptionResponse> {
+  return hermesApi<AudioTranscriptionResponse>({
+    path: '/api/audio/transcribe',
+    method: 'POST',
+    ...profileScoped(),
+    body: {
+      data_url: dataUrl,
+      mime_type: mimeType
+    },
+    // Transcription blocks until provider STT, file handling, and response
+    // encoding finish. Remote providers and long clips regularly exceed the
+    // default 15s Electron backend timeout.
+    timeoutMs: audioTranscribeRequestTimeoutMs(dataUrl)
+  })
+}
+
+export function speakText(text: string): Promise<AudioSpeakResponse> {
+  return hermesApi<AudioSpeakResponse>({
+    ...profileScoped(),
+    path: '/api/audio/speak',
+    method: 'POST',
+    body: { text },
+    // TTS blocks until provider synthesis, file read, and base64 encoding
+    // finish. Remote providers and large messages regularly exceed the
+    // default 15s Electron backend timeout.
+    timeoutMs: audioSpeakRequestTimeoutMs(text)
+  })
+}
+
+export function getElevenLabsVoices(profile?: null | string): Promise<ElevenLabsVoicesResponse> {
+  return hermesApi<ElevenLabsVoicesResponse>({
+    path: '/api/audio/elevenlabs/voices',
+    ...profileScoped(profile)
+  })
+}
+
+/** `gh` CLI presence + auth state, for the composer's GitHub skill pill
+ *  (GitHub is deliberately not an MCP — the github/* skills are the
+ *  integration). Backend caches for 5 minutes; `refresh` bypasses. */
+export function getGhAuthStatus(refresh = false): Promise<{ available: boolean; authenticated: boolean }> {
+  return hermesApi<{ available: boolean; authenticated: boolean }>({
+    ...profileScoped(),
+    path: `/api/git/gh-auth${refresh ? '?refresh=true' : ''}`
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Maintenance operations (parity with `hermes doctor` / `hermes security
+// audit` / `hermes backup` / `hermes debug share` and the dashboard System
+// page). All except debug share are spawn-based background actions tailed via
+// getActionStatus().
+// ---------------------------------------------------------------------------
+
+export function runDoctor(): Promise<ActionResponse> {
+  return hermesApi<ActionResponse>({ path: '/api/ops/doctor', method: 'POST', body: {} })
+}
+
+export function runSecurityAudit(): Promise<ActionResponse> {
+  return hermesApi<ActionResponse>({ path: '/api/ops/security-audit', method: 'POST', body: {} })
+}
+
+export function runBackup(): Promise<ActionResponse & { archive?: string }> {
+  return hermesApi<ActionResponse & { archive?: string }>({
+    path: '/api/ops/backup',
+    method: 'POST',
+    body: {}
+  })
+}
+
+export function runDebugShare(): Promise<DebugShareResponse> {
+  return hermesApi<DebugShareResponse>({
+    path: '/api/ops/debug-share',
+    method: 'POST',
+    body: {},
+    // Synchronous upload of report + logs to the paste service.
+    timeoutMs: 120_000
+  })
+}
diff --git a/apps/desktop/src/api/toolsets.ts b/apps/desktop/src/api/toolsets.ts
new file mode 100644
index 0000000000..862c0fc521
--- /dev/null
+++ b/apps/desktop/src/api/toolsets.ts
@@ -0,0 +1,141 @@
+import type {
+  ActionResponse,
+  ComputerUseStatus,
+  TerminalBackendsResponse,
+  ToolsetConfig,
+  ToolsetInfo,
+  ToolsetModelsResponse
+} from '@/types/hermes'
+
+import { capabilityScoped, hermesApi, type ProfileScope, profileScoped } from './client'
+
+// The optional trailing `profile` on every capability fetcher below is the
+// Capabilities view's profile-scope override: it lets the Skills/Tools/MCP
+// panels configure ANY profile without swapping the app-wide active profile.
+// Omitting it (every pre-existing caller) means `profileScoped(undefined)`
+// falls back to the app-wide `_apiProfile`, so behavior is byte-identical.
+export function getToolsets(profile?: ProfileScope): Promise<ToolsetInfo[]> {
+  return window.hermesDesktop.api<ToolsetInfo[]>({
+    ...capabilityScoped(profile),
+    path: '/api/tools/toolsets'
+  })
+}
+
+export function setToolsetEnabled(
+  name: string,
+  enabled: boolean,
+  profile?: ProfileScope
+): Promise<{ ok: boolean; name: string; enabled: boolean }> {
+  return window.hermesDesktop.api<{ ok: boolean; name: string; enabled: boolean }>({
+    ...capabilityScoped(profile),
+    path: `/api/tools/toolsets/${encodeURIComponent(name)}`,
+    method: 'PUT',
+    body: { enabled }
+  })
+}
+
+export function getToolsetConfig(name: string, profile?: ProfileScope): Promise<ToolsetConfig> {
+  return window.hermesDesktop.api<ToolsetConfig>({
+    ...capabilityScoped(profile),
+    path: `/api/tools/toolsets/${encodeURIComponent(name)}/config`
+  })
+}
+
+export function getToolsetModels(
+  name: string,
+  provider?: string,
+  profile?: ProfileScope
+): Promise<ToolsetModelsResponse> {
+  const suffix = provider ? `?provider=${encodeURIComponent(provider)}` : ''
+
+  return window.hermesDesktop.api<ToolsetModelsResponse>({
+    ...capabilityScoped(profile),
+    path: `/api/tools/toolsets/${encodeURIComponent(name)}/models${suffix}`
+  })
+}
+
+export function selectToolsetModel(
+  name: string,
+  model: string,
+  provider?: string,
+  profile?: ProfileScope
+): Promise<{ ok: boolean; name: string; model: string }> {
+  return window.hermesDesktop.api<{ ok: boolean; name: string; model: string }>({
+    ...capabilityScoped(profile),
+    path: `/api/tools/toolsets/${encodeURIComponent(name)}/model`,
+    method: 'PUT',
+    body: { model, provider }
+  })
+}
+
+export interface SelectToolsetProviderResponse {
+  ok: boolean
+  name: string
+  provider: string
+  /** Present when the selection was scoped to one web capability. */
+  capability?: string
+  /** Present (true) when a managed Nous row was selected but the Portal
+   *  entitlement is missing — the row won't activate until the user signs
+   *  in to Nous Portal. */
+  needs_nous_auth?: boolean
+  /** The managed feature key (e.g. "browser") when needs_nous_auth is set. */
+  feature?: string
+}
+
+export function selectToolsetProvider(
+  name: string,
+  provider: string,
+  capability?: 'search' | 'extract',
+  profile?: ProfileScope
+): Promise<SelectToolsetProviderResponse> {
+  return window.hermesDesktop.api<SelectToolsetProviderResponse>({
+    ...capabilityScoped(profile),
+    path: `/api/tools/toolsets/${encodeURIComponent(name)}/provider`,
+    method: 'PUT',
+    body: capability ? { provider, capability } : { provider }
+  })
+}
+
+export function runToolsetPostSetup(
+  name: string,
+  key: string,
+  profile?: ProfileScope
+): Promise<ActionResponse & { key: string }> {
+  return window.hermesDesktop.api<ActionResponse & { key: string }>({
+    ...capabilityScoped(profile),
+    path: `/api/tools/toolsets/${encodeURIComponent(name)}/post-setup`,
+    method: 'POST',
+    body: { key }
+  })
+}
+
+export function getTerminalBackends(): Promise<TerminalBackendsResponse> {
+  return hermesApi<TerminalBackendsResponse>({
+    ...profileScoped(),
+    path: '/api/tools/terminal/backends'
+  })
+}
+
+export function selectTerminalBackend(backend: string): Promise<{ ok: boolean; backend: string }> {
+  return hermesApi<{ ok: boolean; backend: string }>({
+    ...profileScoped(),
+    path: '/api/tools/terminal/backend',
+    method: 'PUT',
+    body: { backend }
+  })
+}
+
+export function getComputerUseStatus(): Promise<ComputerUseStatus> {
+  return hermesApi<ComputerUseStatus>({
+    ...profileScoped(),
+    path: '/api/tools/computer-use/status'
+  })
+}
+
+export function grantComputerUsePermissions(): Promise<ActionResponse> {
+  return hermesApi<ActionResponse>({
+    ...profileScoped(),
+    path: '/api/tools/computer-use/permissions/grant',
+    method: 'POST'
+  })
+}
diff --git a/apps/desktop/src/hermes.ts b/apps/desktop/src/hermes.ts
index aab8cb1ab2..6242ef5998 100644
--- a/apps/desktop/src/hermes.ts
+++ b/apps/desktop/src/hermes.ts
@@ -1,137 +1,32 @@
-import { JsonRpcGatewayClient } from '@hermes/shared'
-
-import type { HermesApiRequest, HermesConnection } from '@/global'
-import { reconnectBackoffDelayMs } from '@/lib/reconnect-backoff'
-import { recordTranscriptTail } from '@/store/transcript-tail'
-import type {
-  ActionResponse,
-  ActionStatusResponse,
-  AnalyticsResponse,
-  AudioSpeakResponse,
-  AudioTranscriptionResponse,
-  AutomationBlueprint,
-  AuxiliaryModelsResponse,
-  BackendUpdateCheckResponse,
-  ComputerUseStatus,
-  ConfigSchemaResponse,
-  CronDeliveryTarget,
-  CronJob,
-  CronJobCreatePayload,
-  CronJobUpdates,
-  CuratorStatusResponse,
-  CustomEndpointsResponse,
-  CustomEndpointUpdate,
-  CustomEndpointValidationResponse,
-  DebugShareResponse,
-  ElevenLabsVoicesResponse,
-  EnvVarInfo,
-  HermesConfig,
-  HermesConfigRecord,
-  LogsResponse,
-  McpCatalogResponse,
-  McpServerSummary,
-  MemoryProviderConfig,
-  MemoryProviderOAuthStatus,
-  MemoryStatusResponse,
-  MessagingPlatformsResponse,
-  MessagingPlatformTestResponse,
-  MessagingPlatformUpdate,
-  MoaConfigResponse,
-  ModelAssignmentRequest,
-  ModelAssignmentResponse,
-  ModelInfoResponse,
-  ModelOptionsResponse,
-  OAuthPollResponse,
-  OAuthProvidersResponse,
-  OAuthStartResponse,
-  OAuthSubmitResponse,
-  PaginatedSessions,
-  PairingResponse,
-  PairingUser,
-  ProfileCreatePayload,
-  ProfileDesktopOverlay,
-  ProfileSetupCommand,
-  ProfileSoul,
-  ProfilesResponse,
-  SessionInfo,
-  SessionMessage,
-  SessionMessagesResponse,
-  SessionSearchResponse,
-  SkillHubPreview,
-  SkillHubScanResult,
-  SkillHubSearchResponse,
-  SkillHubSourcesResponse,
-  SkillInfo,
-  StarmapGraph,
-  StatusResponse,
-  TerminalBackendsResponse,
-  ToolsetConfig,
-  ToolsetInfo,
-  ToolsetModelsResponse,
-  WebhookCreatePayload,
-  WebhookCreateResponse,
-  WebhookEnableResponse,
-  WebhooksResponse
-} from '@/types/hermes'
-
-// Desktop startup fires a burst of read-only data calls (config, profiles,
-// model info/options, cron) the moment the backend passes readiness. On a
-// profile-heavy or remote install these can each take tens of seconds — e.g.
-// /api/profiles runs list_profiles(), which does a recursive skill-tree walk
-// per profile — so the 15s default (DEFAULT_FETCH_TIMEOUT_MS in hardening.ts)
-// times out a backend that is alive-but-busy, surfacing as a spurious
-// "Timed out connecting to Hermes backend" that hangs the UI (#48504).
-//
-// Give the boot burst a generous per-call timeout instead of raising the
-// global default: interactive/runtime calls and the liveness poll (/api/status)
-// keep the short default so a genuinely-dead backend is still detected fast.
-export const STARTUP_REQUEST_TIMEOUT_MS = 60_000
-const DEFAULT_GATEWAY_REQUEST_TIMEOUT_MS = 30_000
-const SESSION_LIST_REQUEST_TIMEOUT_MS = 60_000
-// The cron trigger endpoint intentionally waits for the whole job so its
-// response reflects the persisted execution result. Agent jobs can run far
-// longer than the Electron fetch default; keep this override local to the one
-// synchronous long-operation endpoint rather than weakening all API timeouts.
-export const CRON_TRIGGER_REQUEST_TIMEOUT_MS = 24 * 60 * 60 * 1000
-// prompt.submit is effectively fire-and-forget: turn completion is signaled by
-// stream / message.complete events, NOT by the RPC return. A long turn (MoA
-// presets running references + aggregator in series, deep reasoning, large tool
-// chains) can legitimately take minutes to ACK, so bounding the ack by the
-// generic 30s default surfaces a false "request timed out" toast while the turn
-// is still running and will succeed (issue #55024). Match the backend's
-// agent-turn ceiling (agent.gateway_timeout = 1800s) so the ack timeout only
-// ever fires when the turn itself would have been abandoned server-side.
-export const PROMPT_SUBMIT_REQUEST_TIMEOUT_MS = 1_800_000
-export const AUDIO_SPEAK_MIN_REQUEST_TIMEOUT_MS = 180_000
-export const AUDIO_SPEAK_MAX_REQUEST_TIMEOUT_MS = 600_000
-const AUDIO_SPEAK_TIMEOUT_MS_PER_CHAR = 35
-
-export function audioSpeakRequestTimeoutMs(text: string): number {
-  const estimated = Math.max(
-    AUDIO_SPEAK_MIN_REQUEST_TIMEOUT_MS,
-    Math.ceil(String(text || '').length * AUDIO_SPEAK_TIMEOUT_MS_PER_CHAR)
-  )
-
-  return Math.min(AUDIO_SPEAK_MAX_REQUEST_TIMEOUT_MS, estimated)
-}
-
-export const AUDIO_TRANSCRIBE_MIN_REQUEST_TIMEOUT_MS = 180_000
-export const AUDIO_TRANSCRIBE_MAX_REQUEST_TIMEOUT_MS = 600_000
-// The transcribe payload is the base64 audio data URL itself, so its string
-// length tracks clip size. ~0.1ms/char keeps short clips at the floor while
-// letting multi-minute recordings scale toward the cap (a base64 char is
-// ~0.75 bytes, so at 128kbps ≈ 21k chars/s of audio this budgets ~2s of
-// timeout per 1s of audio before the cap clamps it).
-const AUDIO_TRANSCRIBE_TIMEOUT_MS_PER_CHAR = 0.1
-
-export function audioTranscribeRequestTimeoutMs(dataUrl: string): number {
-  const estimated = Math.max(
-    AUDIO_TRANSCRIBE_MIN_REQUEST_TIMEOUT_MS,
-    Math.ceil(String(dataUrl || '').length * AUDIO_TRANSCRIBE_TIMEOUT_MS_PER_CHAR)
-  )
-
-  return Math.min(AUDIO_TRANSCRIBE_MAX_REQUEST_TIMEOUT_MS, estimated)
-}
+// The desktop REST/WS client, split by domain under src/api/. This module is
+// the compatibility barrel: every helper keeps its historical `@/hermes`
+// import path while the implementations live in focused files.
+// client is the one module with internals: profileScoped / connectionScoped /
+// capabilityScoped are shared across api/ but must not reach call sites, or
+// request scoping stops having a single owner.
+export {
+  getApiRequestConnection,
+  getApiRequestProfile,
+  hermesApi,
+  HermesGateway,
+  profileScopeKey,
+  PROMPT_SUBMIT_REQUEST_TIMEOUT_MS,
+  setApiRequestConnection,
+  setApiRequestProfile,
+  STARTUP_REQUEST_TIMEOUT_MS
+} from './api/client'
+export type { ProfileScope } from './api/client'
+export * from './api/config'
+export * from './api/cron'
+export * from './api/mcp'
+export * from './api/messaging'
+export * from './api/models'
+export * from './api/plugins'
+export * from './api/profiles'
+export * from './api/sessions'
+export * from './api/skills'
+export * from './api/system'
+export * from './api/toolsets'
 
 export type {
   ActionResponse,
@@ -233,2016 +128,3 @@ export type {
   WebhookRoute,
   WebhooksResponse
 } from '@/types/hermes'
-
-export class HermesGateway extends JsonRpcGatewayClient {
-  constructor() {
-    super({
-      closedErrorMessage: 'Hermes gateway connection closed',
-      connectErrorMessage: 'Could not connect to Hermes gateway',
-      createRequestId: nextId => nextId,
-      notConnectedErrorMessage: 'Hermes gateway is not connected',
-      requestTimeoutMs: DEFAULT_GATEWAY_REQUEST_TIMEOUT_MS
-    })
-  }
-}
-
-// Profile that profile-scoped REST settings (config/env/skills/tools/model/…)
-// should target. Mirrors $activeGatewayProfile, pushed in from the store via
-// setApiRequestProfile so this module needs no store import (avoids a cycle).
-// Electron main consumes request.profile as request scope. Local calls whose
-// REST handlers accept profile reuse the primary dashboard via ?profile=;
-// unscoped handlers retain a profile backend. Remote overrides still route to
-// their owning backend. Null → primary, so single-profile users are unaffected.
-let _apiProfile: null | string = null
-
-export function setApiRequestProfile(profile: null | string): void {
-  _apiProfile = profile || null
-}
-
-function profileScoped(profile?: null | string): { profile?: string } {
-  const selected = profile === undefined ? _apiProfile : profile
-
-  return selected ? { profile: selected } : {}
-}
-
-/** Profile that profile-scoped REST/WS calls should target (null → primary).
- *  Read-only twin of setApiRequestProfile for modules (e.g. voice playback)
- *  that build their own connection URLs and must stay on the same backend. */
-export function getApiRequestProfile(): null | string {
-  return _apiProfile
-}
-
-// Registry connection serving the active gateway (null → the local pool).
-// Pushed from store/gateway's setActive — the single seam BOTH
-// ensureGatewayProfile and ensureGatewayAgent funnel through — so WS calls
-// that dial their own backend (pluginSocket) resolve it through the SAME
-// source of truth those paths maintain for $connection. That makes the plugin
-// socket follow registry-agent activations too, not just profile switches.
-// Same no-store-import contract as _apiProfile (avoids a cycle).
-let _apiConnectionId: null | string = null
-
-export function setApiRequestConnection(connectionId: null | string): void {
-  _apiConnectionId = connectionId || null
-}
-
-// Registry connection scope for a REST request. A registered remote gateway
-// owns its own state.db — cron jobs and their run sessions live THERE — so
-// requests for gateway-owned data must carry the connection id for the main
-// process to route them to that host (hermes:api's registry branch). Null
-// resolves to no tag, keeping single-source users byte-identical; explicit
-// 'local' must remain tagged when the legacy primary points elsewhere.
-function connectionScoped(): { connectionId?: string } {
-  return _apiConnectionId ? { connectionId: _apiConnectionId } : {}
-}
-
-// ── Capability scope: (connection, profile) routing for the Capabilities
-// surface (skills / toolsets / MCP / hub / env / toolset config) ────────────
-//
-// A profile is not a machine-global name — it belongs to ONE gateway. The
-// Capabilities surface can be pointed at any (connection, profile) pair
-// (SkillsView's scope selector, Bot Mode's fixedProfile/fixedConnection), so
-// its REST helpers accept either the legacy string form or an explicit scope
-// object:
-//
-//   - `undefined` / string → the legacy profile path, PLUS the active registry
-//     connection tag (connectionScoped, same contract the cron helpers adopted
-//     in #87882). Without the tag, a window activated onto a registered remote
-//     gateway read the LOCAL pool's skills/tools/MCP — the wrong machine.
-//   - `{ connectionId, profile }` → explicit pin. `''`/`'local'` connection
-//     ids mean the local pool and deliberately DROP the ambient connection
-//     tag, so a local-profile pick made while a remote gateway is active still
-//     routes to the local machine.
-export type ProfileScope = null | string | { connectionId?: null | string; profile?: null | string }
-
-function capabilityScoped(scope?: ProfileScope): { connectionId?: string; profile?: string } {
-  if (scope && typeof scope === 'object') {
-    const profile = (scope.profile ?? '').trim()
-    const connectionId = (scope.connectionId ?? '').trim()
-
-    return {
-      ...(profile ? { profile } : {}),
-      ...(connectionId && connectionId !== 'local' ? { connectionId } : {})
-    }
-  }
-
-  return { ...profileScoped(scope), ...connectionScoped() }
-}
-
-/** Stable cache-key for a capability scope: `profile` for the local/legacy
- *  path, `connectionId::profile` for an explicit remote pin. Mirrors
- *  normalizeProfileKey for plain strings so existing keys stay byte-identical. */
-export function profileScopeKey(scope?: ProfileScope): string {
-  if (scope && typeof scope === 'object') {
-    const profile = (scope.profile ?? '').trim() || 'default'
-    const connectionId = (scope.connectionId ?? '').trim()
-
-    return connectionId && connectionId !== 'local' ? `${connectionId}::${profile}` : profile
-  }
-
-  return (scope ?? '').trim() || 'default'
-}
-
-/** Send a REST request to the renderer's active registry source. Request-level
- *  routing may override the active source for an explicitly-owned resource. */
-export function hermesApi<T>(request: HermesApiRequest): Promise<T> {
-  return window.hermesDesktop.api<T>({ ...connectionScoped(), ...request })
-}
-
-/** Registry connection id that connection-scoped WS calls should target
- *  (null → the local pool). Read-only twin of setApiRequestConnection. */
-export function getApiRequestConnection(): null | string {
-  return _apiConnectionId
-}
-
-/** Resolve the ACTIVE backend's connection descriptor, (connectionId,
- *  profile)-scoped — mirroring how store/profile resolves $connection: a
- *  registry agent's descriptor comes from getConnectionFor (its SOURCE
- *  connection), everything else from the profile-keyed local pool. The
- *  getConnectionFor bridge is optional (older Desktop mains); without it the
- *  profile-scoped pool lookup is the best available answer. */
-async function activeConnection(): Promise<HermesConnection> {
-  const getConnectionFor = window.hermesDesktop.getConnectionFor
-
-  if (_apiConnectionId && getConnectionFor) {
-    return getConnectionFor({ connectionId: _apiConnectionId, profile: _apiProfile })
-  }
-
-  return window.hermesDesktop.getConnection(_apiProfile)
-}
-
-/** Options for a plugin REST call — mirrors the app's own `hermesDesktop.api`
- *  shape, minus the path (which is namespace-derived). */
-export interface PluginRestOptions {
-  method?: string
-  body?: unknown
-  /** Single-file multipart upload (see HermesApiRequest.upload). */
-  upload?: { filename: string; contentType?: string; bytes: ArrayBuffer }
-  timeoutMs?: number
-}
-
-// Normalize `path` to a leading-slash suffix relative to `/api/plugins/<id>`.
-// The namespace is the boundary — reject `..` so a relative segment can't
-// normalize out into another plugin's API or a core route. Check the path
-// portion only (before any query/hash).
-function pluginPathSuffix(caller: string, path: string): string {
-  const suffix = path.startsWith('/') ? path : `/${path}`
-
-  if (suffix.split(/[?#]/, 1)[0].split('/').includes('..')) {
-    throw new Error(`${caller}: illegal path traversal in "${path}"`)
-  }
-
-  return suffix
-}
-
-/** The plugin REST door. Every call is scoped BY CONSTRUCTION to the plugin's
- *  own backend namespace — `path` is relative to `/api/plugins/<pluginId>`
- *  ('/board' → `/api/plugins/kanban/board`), so a plugin can't address another
- *  plugin's API or a core route through it. Profile-aware like every desktop
- *  REST call. Broader reach (core endpoints, another namespace) is the future
- *  declared-capability seam; today the namespace IS the boundary. */
-export async function pluginRest<T>(pluginId: string, path: string, opts: PluginRestOptions = {}): Promise<T> {
-  if (!window.hermesDesktop?.api) {
-    throw new Error('Hermes desktop bridge unavailable')
-  }
-
-  const suffix = pluginPathSuffix('pluginRest', path)
-
-  return hermesApi<T>({
-    path: `/api/plugins/${pluginId}${suffix}`,
-    method: opts.method,
-    body: opts.body,
-    upload: opts.upload,
-    timeoutMs: opts.timeoutMs,
-    ...profileScoped()
-  })
-}
-
-/** The plugin WebSocket door — the live twin of `pluginRest`, scoped the same
- *  way: `path` is relative to `/api/plugins/<pluginId>` ('/events' → the
- *  plugin's own event stream). Token-mode backends auth via the same query
- *  credential the app's own sockets use; OAuth remotes resolve null (callers
- *  keep their polling fallback — every consumer must have one anyway, since a
- *  socket can drop). Auto-reconnects with backoff until disposed. */
-export function pluginSocket(pluginId: string, path: string, onMessage: (data: unknown) => void): () => void {
-  const suffix = pluginPathSuffix('pluginSocket', path)
-
-  let socket: null | WebSocket = null
-  let disposed = false
-  let attempt = 0
-
-  const connect = async () => {
-    const connection = await activeConnection().catch(() => null)
-
-    // No bridge / OAuth cookie auth (WS tickets are single-use, core-managed):
-    // stay on the polling fallback rather than half-working.
-    if (disposed || !connection || connection.authMode === 'oauth') {
-      return
-    }
-
-    const base = connection.baseUrl.replace(/^http/, 'ws')
-    const join = suffix.includes('?') ? '&' : '?'
-    socket = new WebSocket(
-      `${base}/api/plugins/${pluginId}${suffix}${join}token=${encodeURIComponent(connection.token)}`
-    )
-
-    socket.onmessage = event => {
-      attempt = 0
-
-      try {
-        onMessage(JSON.parse(String(event.data)))
-      } catch {
-        // Non-JSON frame — plugin streams are JSON by contract; skip it.
-      }
-    }
-
-    socket.onclose = () => {
-      socket = null
-
-      if (!disposed) {
-        // Full-jitter exponential backoff: same rationale as the gateway
-        // socket reconnect loops — an immediate-retry loop across many
-        // desktop clients floods the gateway with connection attempts
-        // during a restart.
-        window.setTimeout(() => void connect(), reconnectBackoffDelayMs(attempt, { baseDelayMs: 500, capMs: 30_000 }))
-        attempt += 1
-      }
-    }
-  }
-
-  void connect()
-
-  return () => {
-    disposed = true
-    socket?.close()
-  }
-}
-
-/**
- * Trim a page to its window WITHOUT discarding pinned rows.
- *
- * The list endpoints deliberately back-fill pinned conversations past their
- * LIMIT — a pin means "always reachable", so an aged-out pinned chat is
- * appended after the recency window. A plain `slice(0, limit)` throws exactly
- * those rows away again, which is why pins silently stopped rendering past
- * some count: the sidebar could only ever show the pins that happened to fall
- * inside the most-recent page.
- */
-function pageWindow(sessions: SessionInfo[], limit: number): SessionInfo[] {
-  if (sessions.length <= limit) {
-    return sessions
-  }
-
-  const recent = sessions.slice(0, limit)
-
-  return [...recent, ...sessions.slice(limit).filter(session => session.pinned)]
-}
-
-export async function listSessions(
-  limit = 40,
-  minMessages = 0,
-  archived: 'exclude' | 'include' | 'only' = 'exclude',
-  order: 'created' | 'recent' = 'recent'
-): Promise<PaginatedSessions> {
-  const result = await hermesApi<PaginatedSessions>({
-    path:
-      `/api/sessions?limit=${limit}&offset=0&min_messages=${Math.max(0, minMessages)}` +
-      `&archived=${archived}&order=${order}`,
-    timeoutMs: SESSION_LIST_REQUEST_TIMEOUT_MS
-  })
-
-  return {
-    ...result,
-    sessions: pageWindow(result.sessions, limit),
-    offset: 0
-  }
-}
-
-// Unified, read-only session list aggregated across ALL profiles. Served by the
-// primary backend straight off each profile's state.db — no per-profile backend
-// is spawned. Single-profile users get the same rows as listSessions(), tagged
-// profile="default".
-// Source scoping lets callers split the unified list into independent slices:
-// recents pass `excludeSources: ['cron']`, the cron-jobs section passes
-// `source: 'cron'`. Without this a burst of (always-newest) cron sessions
-// consumes the whole recents page and starves real conversations.
-export interface SessionSourceFilter {
-  source?: string
-  excludeSources?: string[]
-}
-
-export async function listAllProfileSessions(
-  limit = 40,
-  minMessages = 0,
-  archived: 'exclude' | 'include' | 'only' = 'exclude',
-  order: 'created' | 'recent' = 'recent',
-  profile: 'all' | (string & {}) = 'all',
-  filter: SessionSourceFilter = {}
-): Promise<PaginatedSessions> {
-  const sourceParam = filter.source ? `&source=${encodeURIComponent(filter.source)}` : ''
-
-  const excludeParam = filter.excludeSources?.length
-    ? `&exclude_sources=${encodeURIComponent(filter.excludeSources.join(','))}`
-    : ''
-
-  const result = await hermesApi<PaginatedSessions>({
-    path:
-      `/api/profiles/sessions?limit=${limit}&offset=0&min_messages=${Math.max(0, minMessages)}` +
-      `&archived=${archived}&order=${order}&profile=${encodeURIComponent(profile)}${sourceParam}${excludeParam}`,
-    timeoutMs: SESSION_LIST_REQUEST_TIMEOUT_MS
-  })
-
-  return {
-    ...result,
-    sessions: pageWindow(result.sessions, limit),
-    offset: 0
-  }
-}
-
-// Batched sidebar slices in one request: recents (scoped to the active profile),
-// cron, and messaging. The backend opens each profile's state.db once and runs
-// all three filtered queries, replacing three separate listAllProfileSessions
-// calls that each reopened + re-counted every profile DB per refresh. Electron
-// splices remote profiles per slice (see interceptSessionRequestForRemote).
-export interface SidebarSessionSlice {
-  sessions: SessionInfo[]
-  /** Per-profile "the window came back full, more rows exist on disk" flags —
-   *  what pagination needs, without a COUNT(*) per profile DB per refresh. */
-  profiles_truncated?: Record<string, boolean>
-  /** Per-profile tokens and spend over every session, not just this window.
-   *  Absent from the legacy per-slice endpoint, which has no aggregate. */
-  profiles_usage?: Record<string, { cost_usd: number; tokens: number }>
-}
-
-/** Which profiles filled their per-profile window in a returned page. The
- *  legacy per-slice endpoint doesn't report this, so derive it from the rows:
- *  a profile at (or over) the cap still has more on disk. Pinned rows are
- *  discounted — they're back-filled past the LIMIT, so counting them fakes a
- *  full page and leaves a "Load more" that can never resolve. */
-function profilesTruncatedFrom(sessions: SessionInfo[], cap: number): Record<string, boolean> {
-  const counts = new Map<string, number>()
-
-  for (const session of sessions) {
-    const key = session.profile || 'default'
-
-    counts.set(key, (counts.get(key) ?? 0) + (session.pinned ? 0 : 1))
-  }
-
-  return Object.fromEntries([...counts].map(([name, count]) => [name, count >= cap]))
-}
-
-export interface SidebarSessionsResponse {
-  recents: SidebarSessionSlice
-  cron: SidebarSessionSlice
-  messaging: SidebarSessionSlice
-  errors?: Array<{ profile: string; error: string }>
-}
-
-export interface SidebarSessionsRequest {
-  recentsProfile: 'all' | (string & {})
-  recentsLimit: number
-  recentsExclude: string[]
-  cronLimit: number
-  messagingLimit: number
-  messagingExclude: string[]
-}
-
-// The batched /sidebar endpoint shipped later than the per-slice route, so a
-// newer desktop can meet an older backend that 404s it ("No such API
-// endpoint"). Endpoint-missing is a capability signal, not a transient
-// failure: remember it (per renderer lifetime — a runtime home change reloads
-// the window and re-probes) and serve every subsequent refresh straight from
-// the three proven per-slice calls instead of re-probing a known-dead route
-// once per turn/broadcast.
-let sidebarBatchEndpointMissing = false
-
-// Capability flags are per-backend facts. A hard re-home reloads the window
-// (module state resets naturally), but a soft gateway switch re-dials in
-// place — the next backend may well have the batched route, so the switch
-// paths call this to re-probe rather than leak the old backend's capability.
-export function resetSidebarBatchCapability() {
-  sidebarBatchEndpointMissing = false
-}
-
-// True only for "the route does not exist on this backend" shapes: the
-// backend catch-all ('404: {"detail":"No such API endpoint: ...}'), FastAPI's
-// bare 404 on headless serve (surfaces as '404: ...' directly or as
-// "Error invoking remote method 'hermes:api': Error: 404: ..." through the
-// IPC bridge), and the Electron JSON-guard ("endpoint is likely missing").
-// This GET has no path params, so a 404 status can only mean route-missing —
-// but transient failures (timeouts, 5xx, connection refused) must NOT match,
-// or one blip would silently degrade the fast path for the whole session.
-function isEndpointMissingError(err: unknown): boolean {
-  const message = err instanceof Error ? err.message : String(err)
-
-  return (
-    /no such api endpoint/i.test(message) ||
-    /endpoint is likely missing/i.test(message) ||
-    /(?:^\s*|error:\s*)404\b/i.test(message)
-  )
-}
-
-// Compatibility fallback: reassemble the three sidebar slices from the
-// per-slice endpoint, mirroring the batched route's semantics (min_messages=1,
-// archived excluded, recency order; every slice scoped to the caller's profile).
-// Rides the same Electron remote-splice
-// interception as the pre-batching desktop, so remote profiles stay correct.
-async function listSidebarSessionsLegacy(req: SidebarSessionsRequest): Promise<SidebarSessionsResponse> {
-  const [recents, cron, messaging] = await Promise.all([
-    listAllProfileSessions(req.recentsLimit, 1, 'exclude', 'recent', req.recentsProfile, {
-      excludeSources: req.recentsExclude
-    }),
-    listAllProfileSessions(req.cronLimit, 1, 'exclude', 'recent', req.recentsProfile, { source: 'cron' }),
-    listAllProfileSessions(req.messagingLimit, 1, 'exclude', 'recent', req.recentsProfile, {
-      excludeSources: req.messagingExclude
-    })
-  ])
-
-  const errors = [...(recents.errors ?? []), ...(cron.errors ?? []), ...(messaging.errors ?? [])]
-
-  return {
-    recents: {
-      profiles_truncated: profilesTruncatedFrom(recents.sessions, req.recentsLimit),
-      sessions: recents.sessions
-    },
-    cron: { sessions: cron.sessions },
-    messaging: { sessions: messaging.sessions },
-    ...(errors.length ? { errors } : {})
-  }
-}
-
-/** The PR each of these sessions opened, recovered from its own transcript —
- *  for sessions whose recorded branch can't answer (they started on trunk and
- *  did the work in a worktree). Also returns every id it looked at, so the
- *  caller can remember a miss and never ask again. */
-export function scanSessionPullRequests(
-  ids: string[]
-): Promise<{ pull_requests: Record<string, { number: number; url: string }>; scanned: string[] }> {
-  return hermesApi<{
-    pull_requests: Record<string, { number: number; url: string }>
-    scanned: string[]
-  }>({
-    path: '/api/profiles/sessions/pull-requests',
-    method: 'POST',
-    body: { ids }
-  })
-}
-
-export async function listSidebarSessions(req: SidebarSessionsRequest): Promise<SidebarSessionsResponse> {
-  if (sidebarBatchEndpointMissing) {
-    return listSidebarSessionsLegacy(req)
-  }
-
-  const params = new URLSearchParams({
-    recents_profile: req.recentsProfile,
-    recents_limit: String(Math.max(1, req.recentsLimit)),
-    cron_limit: String(Math.max(1, req.cronLimit)),
-    messaging_limit: String(Math.max(1, req.messagingLimit))
-  })
-
-  if (req.recentsExclude.length) {
-    params.set('recents_exclude', req.recentsExclude.join(','))
-  }
-
-  if (req.messagingExclude.length) {
-    params.set('messaging_exclude', req.messagingExclude.join(','))
-  }
-
-  let result: SidebarSessionsResponse
-
-  try {
-    result = await hermesApi<SidebarSessionsResponse>({
-      path: `/api/profiles/sessions/sidebar?${params.toString()}`,
-      timeoutMs: SESSION_LIST_REQUEST_TIMEOUT_MS
-    })
-  } catch (err) {
-    if (!isEndpointMissingError(err)) {
-      throw err
-    }
-
-    // Older backend without the batched route (desktop/runtime version skew).
-    sidebarBatchEndpointMissing = true
-
-    return listSidebarSessionsLegacy(req)
-  }
-
-  return {
-    recents: { ...result.recents, sessions: result.recents?.sessions ?? [] },
-    cron: { ...result.cron, sessions: result.cron?.sessions ?? [] },
-    messaging: { ...result.messaging, sessions: result.messaging?.sessions ?? [] },
-    errors: result.errors
-  }
-}
-
-// Mutations take the owning `profile` so Electron can route them to the correct
-// remote backend or local profile scope. Omit for the current/default profile.
-export function setSessionArchived(id: string, archived: boolean, profile?: string | null): Promise<{ ok: boolean }> {
-  return hermesApi<{ ok: boolean }>({
-    ...(profile ? { profile } : {}),
-    path: `/api/sessions/${encodeURIComponent(id)}`,
-    method: 'PATCH',
-    body: { archived }
-  })
-}
-
-// Mirror a sidebar pin to the backend "keep" flag so the sessions.auto_archive
-// sweep (which runs backend-side, blind to Desktop localStorage) never hides a
-// pinned chat. Best-effort: the sidebar stays localStorage-driven for its own
-// display; this only feeds the backend policy.
-export function setSessionPinnedRemote(id: string, pinned: boolean, profile?: string | null): Promise<{ ok: boolean }> {
-  return hermesApi<{ ok: boolean }>({
-    ...(profile ? { profile } : {}),
-    path: `/api/sessions/${encodeURIComponent(id)}`,
-    method: 'PATCH',
-    body: { pinned }
-  })
-}
-
-// Mirror a sidebar unread toggle to the backend read-state watermark
-// (sessions.last_read_at via SessionDB.set_session_read). Same profile
-// routing as the other session mutations: a remote session's row lives only
-// on its remote host, so the owning profile must travel with the request.
-export function setSessionUnreadRemote(id: string, unread: boolean, profile?: string | null): Promise<{ ok: boolean }> {
-  return hermesApi<{ ok: boolean }>({
-    ...(profile ? { profile } : {}),
-    path: `/api/sessions/${encodeURIComponent(id)}`,
-    method: 'PATCH',
-    body: { unread }
-  })
-}
-
-export function searchSessions(query: string): Promise<SessionSearchResponse> {
-  return hermesApi<SessionSearchResponse>({
-    path: `/api/sessions/search?q=${encodeURIComponent(query)}`
-  })
-}
-
-// Resolves a single session row by id on one backend (the active profile, or
-// the given `profile`). The backend resolves exact ids and unique prefixes and
-// 404s when the id isn't on that profile — so a cheap by-id lookup replaces the
-// cross-profile list scan when locating an unknown id's owner.
-export function getSession(id: string, profile?: string | null): Promise<SessionInfo> {
-  const suffix = profile ? `?profile=${encodeURIComponent(profile)}` : ''
-
-  return hermesApi<SessionInfo>({
-    ...(profile ? { profile } : {}),
-    path: `/api/sessions/${encodeURIComponent(id)}${suffix}`
-  })
-}
-
-// Reads another profile's transcript. For a remote profile Electron reroutes
-// this GET to the remote backend (which serves its own state.db); for a local
-// profile the primary opens that profile's state.db via ?profile=. Omit for
-// the current/default profile.
-export function getSessionMessages(
-  id: string,
-  profile?: string | null,
-  page: { limit?: number; offset?: number; order?: 'latest' | 'oldest'; includeCompacted?: boolean } = {}
-): Promise<SessionMessagesResponse> {
-  const query = new URLSearchParams()
-
-  if (profile) {
-    query.set('profile', profile)
-  }
-
-  if (page.limit !== undefined) {
-    query.set('limit', String(page.limit))
-  }
-
-  if (page.offset !== undefined) {
-    query.set('offset', String(page.offset))
-  }
-
-  if (page.order) {
-    query.set('order', page.order)
-  }
-
-  if (page.includeCompacted !== undefined) {
-    query.set('include_compacted', String(page.includeCompacted))
-  }
-
-  const suffix = query.size ? `?${query.toString()}` : ''
-
-  return hermesApi<SessionMessagesResponse>({
-    ...(profile ? { profile } : {}),
-    path: `/api/sessions/${encodeURIComponent(id)}/messages${suffix}`
-  })
-}
-
-/**
- * The initial hydration page: enough tail to fill the transcript window a few
- * times over, small enough that opening a long session doesn't ship (and
- * convert) hundreds of rows nobody has scrolled to. Older rows load on demand
- * via `getOlderSessionMessages` when "Show earlier" exhausts the in-memory
- * store (see app/chat/transcript-backfill).
- */
-export const LATEST_SESSION_MESSAGES_LIMIT = 120
-
-export function getLatestSessionMessages(id: string, profile?: string | null): Promise<SessionMessagesResponse> {
-  // includeCompacted: durable display history must include rows preserved by
-  // in-place compaction (active=0, compacted=1); without them the transcript
-  // silently ends at the compaction boundary and earlier turns are unreachable.
-  return getSessionMessages(id, profile, {
-    limit: LATEST_SESSION_MESSAGES_LIMIT,
-    order: 'latest',
-    includeCompacted: true
-  }).then(page => {
-    // Record whether the tail was truncated (page came back full) and where
-    // the next older page starts, so "Show earlier" can backfill over REST
-    // (app/chat/transcript-backfill). Keyed under both the requested id and
-    // the resolved id — callers hold either.
-    recordTranscriptTail(id, page, profile)
-
-    if (page.session_id && page.session_id !== id) {
-      recordTranscriptTail(page.session_id, page, profile)
-    }
-
-    return page
-  })
-}
-
-/**
- * One page of messages OLDER than the `offset` newest rows.
- *
- * Backend semantics (`_handle_session_messages` → `SessionDB.get_messages`
- * with `latest=True`): the offset is measured back from the NEWEST message
- * and the selected page is returned in chronological order. So after a tail
- * hydration of N rows, `getOlderSessionMessages(id, profile, N)` returns the
- * page immediately preceding it, ready to prepend.
- *
- * Legacy backends without pagination support return the full transcript and
- * no `pagination` metadata — callers detect that via the missing field and
- * treat the response as the complete history (see transcript-backfill).
- */
-export function getOlderSessionMessages(
-  id: string,
-  profile: string | null | undefined,
-  offset: number,
-  limit: number = LATEST_SESSION_MESSAGES_LIMIT
-): Promise<SessionMessagesResponse> {
-  return getSessionMessages(id, profile, { includeCompacted: true, limit, offset, order: 'latest' })
-}
-
-export async function getAllSessionMessages(
-  id: string,
-  profile?: string | null,
-  options: { maxJsonChars?: number } = {}
-): Promise<SessionMessagesResponse> {
-  const messages: SessionMessage[] = []
-  const pageSize = 500
-  const maxJsonChars = options.maxJsonChars ?? 32_000_000
-  let jsonChars = 0
-  let offset = 0
-  let resolvedSessionId = id
-
-  while (true) {
-    const page = await getSessionMessages(id, profile, {
-      limit: pageSize,
-      offset,
-      order: 'oldest',
-      includeCompacted: true
-    })
-
-    resolvedSessionId = page.session_id
-    jsonChars += (JSON.stringify(page.messages) ?? '').length
-
-    if (jsonChars > maxJsonChars) {
-      throw new Error(
-        'Session transcript exceeds the Desktop safe-load limit; use the Web Dashboard export for this session.'
-      )
-    }
-
-    messages.push(...page.messages)
-
-    // Legacy backends ignore pagination and return the full transcript.
-    if (!page.pagination || page.messages.length === 0 || page.messages.length < page.pagination.limit) {
-      break
-    }
-
-    offset += page.messages.length
-  }
-
-  return { session_id: resolvedSessionId, messages }
-}
-
-export function deleteSession(id: string, profile?: string | null): Promise<{ ok: boolean }> {
-  return hermesApi<{ ok: boolean }>({
-    ...(profile ? { profile } : {}),
-    path: `/api/sessions/${encodeURIComponent(id)}`,
-    method: 'DELETE'
-  })
-}
-
-export function renameSession(
-  id: string,
-  title: string,
-  profile?: string | null
-): Promise<{ ok: boolean; title: string }> {
-  return hermesApi<{ ok: boolean; title: string }>({
-    ...(profile ? { profile } : {}),
-    path: `/api/sessions/${encodeURIComponent(id)}`,
-    method: 'PATCH',
-    body: { title, ...(profile ? { profile } : {}) }
-  })
-}
-
-export function getGlobalModelInfo(profile?: null | string): Promise<ModelInfoResponse> {
-  return hermesApi<ModelInfoResponse>({
-    ...profileScoped(profile),
-    path: '/api/model/info',
-    timeoutMs: STARTUP_REQUEST_TIMEOUT_MS
-  })
-}
-
-export function getStatus(): Promise<StatusResponse> {
-  return hermesApi<StatusResponse>({
-    ...profileScoped(),
-    path: '/api/status'
-  })
-}
-
-export function getLogs(params: {
-  component?: string
-  file?: string
-  level?: string
-  lines?: number
-  search?: string
-}): Promise<LogsResponse> {
-  const query = new URLSearchParams()
-
-  if (params.file) {
-    query.set('file', params.file)
-  }
-
-  if (typeof params.lines === 'number') {
-    query.set('lines', String(params.lines))
-  }
-
-  if (params.level && params.level !== 'ALL') {
-    query.set('level', params.level)
-  }
-
-  if (params.component && params.component !== 'all') {
-    query.set('component', params.component)
-  }
-
-  if (params.search) {
-    query.set('search', params.search)
-  }
-
-  const suffix = query.toString()
-
-  return hermesApi<LogsResponse>({
-    ...profileScoped(),
-    path: suffix ? `/api/logs?${suffix}` : '/api/logs'
-  })
-}
-
-export function getHermesConfig(profile?: string): Promise<HermesConfig> {
-  return hermesApi<HermesConfig>({
-    ...profileScoped(profile),
-    path: '/api/config',
-    timeoutMs: STARTUP_REQUEST_TIMEOUT_MS
-  })
-}
-
-export function getHermesConfigRecord(profile?: ProfileScope): Promise<HermesConfigRecord> {
-  return window.hermesDesktop.api<HermesConfigRecord>({
-    ...capabilityScoped(profile),
-    path: '/api/config'
-  })
-}
-
-export function getHermesConfigDefaults(): Promise<HermesConfigRecord> {
-  return hermesApi<HermesConfigRecord>({
-    ...profileScoped(),
-    path: '/api/config/defaults',
-    timeoutMs: STARTUP_REQUEST_TIMEOUT_MS
-  })
-}
-
-export function getHermesConfigSchema(profile?: null | string): Promise<ConfigSchemaResponse> {
-  return hermesApi<ConfigSchemaResponse>({
-    ...profileScoped(profile),
-    path: '/api/config/schema'
-  })
-}
-
-export function saveHermesConfig(config: HermesConfigRecord, profile?: null | string): Promise<{ ok: boolean }> {
-  return hermesApi<{ ok: boolean }>({
-    ...profileScoped(profile),
-    path: '/api/config',
-    method: 'PUT',
-    body: { config }
-  })
-}
-
-// surface=declared serves the curated desktop schema; the dashboard consumes the raw plugin schema.
-export function getMemoryProviderConfig(provider: string, profile?: null | string): Promise<MemoryProviderConfig> {
-  return hermesApi<MemoryProviderConfig>({
-    ...profileScoped(profile),
-    path: `/api/memory/providers/${encodeURIComponent(provider)}/config?surface=declared`
-  })
-}
-
-export function saveMemoryProviderConfig(
-  provider: string,
-  values: Record<string, string>,
-  profile?: null | string
-): Promise<{ ok: boolean }> {
-  return hermesApi<{ ok: boolean }>({
-    ...profileScoped(profile),
-    path: `/api/memory/providers/${encodeURIComponent(provider)}/config?surface=declared`,
-    method: 'PUT',
-    body: { values }
-  })
-}
-
-export function getEnvVars(profile?: null | string): Promise<Record<string, EnvVarInfo>> {
-  return hermesApi<Record<string, EnvVarInfo>>({
-    ...profileScoped(profile),
-    path: '/api/env'
-  })
-}
-
-export function setEnvVar(key: string, value: string, profile?: ProfileScope): Promise<{ ok: boolean }> {
-  return window.hermesDesktop.api<{ ok: boolean }>({
-    ...capabilityScoped(profile),
-    path: '/api/env',
-    method: 'PUT',
-    body: { key, value }
-  })
-}
-
-export function validateProviderCredential(
-  key: string,
-  value: string,
-  apiKey?: string
-): Promise<{ ok: boolean; reachable: boolean; message: string; models?: string[] }> {
-  return hermesApi<{ ok: boolean; reachable: boolean; message: string; models?: string[] }>({
-    ...profileScoped(),
-    path: '/api/providers/validate',
-    method: 'POST',
-    body: { key, value, api_key: apiKey ?? '' }
-  })
-}
-
-export function getCustomEndpoints(): Promise<CustomEndpointsResponse> {
-  return hermesApi<CustomEndpointsResponse>({
-    ...profileScoped(),
-    path: '/api/providers/custom-endpoints'
-  })
-}
-
-export function saveCustomEndpoint(endpoint: CustomEndpointUpdate): Promise<CustomEndpointsResponse> {
-  return hermesApi<CustomEndpointsResponse>({
-    ...profileScoped(),
-    path: '/api/providers/custom-endpoints',
-    method: 'POST',
-    body: endpoint
-  })
-}
-
-export function validateCustomEndpoint(endpoint: CustomEndpointUpdate): Promise<CustomEndpointValidationResponse> {
-  return hermesApi<CustomEndpointValidationResponse>({
-    path: '/api/providers/custom-endpoints/validate',
-    method: 'POST',
-    body: endpoint
-  })
-}
-
-export function activateCustomEndpoint(id: string): Promise<{ ok: boolean; provider: string; model: string }> {
-  return hermesApi<{ ok: boolean; provider: string; model: string }>({
-    ...profileScoped(),
-    path: `/api/providers/custom-endpoints/${encodeURIComponent(id)}/activate`,
-    method: 'POST'
-  })
-}
-
-export function deleteCustomEndpoint(id: string): Promise<CustomEndpointsResponse> {
-  return hermesApi<CustomEndpointsResponse>({
-    ...profileScoped(),
-    path: `/api/providers/custom-endpoints/${encodeURIComponent(id)}`,
-    method: 'DELETE'
-  })
-}
-
-export function deleteEnvVar(key: string, profile?: ProfileScope): Promise<{ ok: boolean }> {
-  return window.hermesDesktop.api<{ ok: boolean }>({
-    ...capabilityScoped(profile),
-    path: '/api/env',
-    method: 'DELETE',
-    body: { key }
-  })
-}
-
-export function revealEnvVar(key: string, profile?: ProfileScope): Promise<{ key: string; value: string }> {
-  return window.hermesDesktop.api<{ key: string; value: string }>({
-    ...capabilityScoped(profile),
-    path: '/api/env/reveal',
-    method: 'POST',
-    body: { key }
-  })
-}
-
-export function listOAuthProviders(): Promise<OAuthProvidersResponse> {
-  return hermesApi<OAuthProvidersResponse>({
-    ...profileScoped(),
-    path: '/api/providers/oauth'
-  })
-}
-
-export function disconnectOAuthProvider(providerId: string): Promise<{ ok: boolean; provider: string }> {
-  return hermesApi<{ ok: boolean; provider: string }>({
-    ...profileScoped(),
-    path: `/api/providers/oauth/${encodeURIComponent(providerId)}`,
-    method: 'DELETE'
-  })
-}
-
-export function startOAuthLogin(providerId: string, profile?: ProfileScope): Promise<OAuthStartResponse> {
-  return window.hermesDesktop.api<OAuthStartResponse>({
-    ...capabilityScoped(profile),
-    path: `/api/providers/oauth/${encodeURIComponent(providerId)}/start`,
-    method: 'POST',
-    body: {}
-  })
-}
-
-export function submitOAuthCode(providerId: string, sessionId: string, code: string): Promise<OAuthSubmitResponse> {
-  return hermesApi<OAuthSubmitResponse>({
-    ...profileScoped(),
-    path: `/api/providers/oauth/${encodeURIComponent(providerId)}/submit`,
-    method: 'POST',
-    body: { session_id: sessionId, code }
-  })
-}
-
-export function pollOAuthSession(
-  providerId: string,
-  sessionId: string,
-  profile?: ProfileScope
-): Promise<OAuthPollResponse> {
-  return window.hermesDesktop.api<OAuthPollResponse>({
-    ...capabilityScoped(profile),
-    path: `/api/providers/oauth/${encodeURIComponent(providerId)}/poll/${encodeURIComponent(sessionId)}`
-  })
-}
-
-export function cancelOAuthSession(sessionId: string): Promise<{ ok: boolean }> {
-  return hermesApi<{ ok: boolean }>({
-    ...profileScoped(),
-    path: `/api/providers/oauth/sessions/${encodeURIComponent(sessionId)}`,
-    method: 'DELETE'
-  })
-}
-
-// Memory-provider OAuth connect (provider-keyed; 404s for providers without an
-// OAuth flow). Profile-scoped: the grant lands in the active profile's config.
-export function startMemoryProviderOAuth(
-  provider: string,
-  profile?: null | string
-): Promise<MemoryProviderOAuthStatus> {
-  return hermesApi<MemoryProviderOAuthStatus>({
-    ...profileScoped(profile),
-    path: `/api/memory/providers/${encodeURIComponent(provider)}/oauth/start`,
-    method: 'POST'
-  })
-}
-
-export function getMemoryProviderOAuthStatus(
-  provider: string,
-  profile?: null | string
-): Promise<MemoryProviderOAuthStatus> {
-  return hermesApi<MemoryProviderOAuthStatus>({
-    ...profileScoped(profile),
-    path: `/api/memory/providers/${encodeURIComponent(provider)}/oauth/status`
-  })
-}
-
-export function getSkills(profile?: ProfileScope): Promise<SkillInfo[]> {
-  return window.hermesDesktop.api<SkillInfo[]>({
-    ...capabilityScoped(profile),
-    path: '/api/skills'
-  })
-}
-
-/** Raw SKILL.md text (frontmatter included) for ANY skill — bundled, hub, or
- *  learned — backing the Capabilities detail pane's full-skill view. */
-export function getSkillContent(
-  name: string,
-  profile?: ProfileScope
-): Promise<{ content: string; name: string; path: string }> {
-  return window.hermesDesktop.api<{ content: string; name: string; path: string }>({
-    ...capabilityScoped(profile),
-    path: `/api/skills/content?name=${encodeURIComponent(name)}`
-  })
-}
-
-export function getStarmapGraph(): Promise<StarmapGraph> {
-  return hermesApi<StarmapGraph>({
-    ...profileScoped(),
-    // Backend REST contract — stays /api/learning even though the UI feature is
-    // now "star map". Renaming this would break against an un-upgraded backend.
-    path: '/api/learning/graph'
-  })
-}
-
-export interface LearningNodeDetail {
-  content: string
-  kind: 'memory' | 'skill'
-  label: string
-  ok: boolean
-}
-
-export function getLearningNode(id: string, profile?: ProfileScope): Promise<LearningNodeDetail> {
-  return window.hermesDesktop.api<LearningNodeDetail>({
-    ...capabilityScoped(profile),
-    path: `/api/learning/node?id=${encodeURIComponent(id)}`
-  })
-}
-
-export function deleteLearningNode(id: string, profile?: ProfileScope): Promise<{ message: string; ok: boolean }> {
-  return window.hermesDesktop.api<{ message: string; ok: boolean }>({
-    ...capabilityScoped(profile),
-    path: '/api/learning/node',
-    method: 'DELETE',
-    body: { id }
-  })
-}
-
-export function editLearningNode(
-  id: string,
-  content: string,
-  profile?: ProfileScope
-): Promise<{ message: string; ok: boolean }> {
-  return window.hermesDesktop.api<{ message: string; ok: boolean }>({
-    ...capabilityScoped(profile),
-    path: '/api/learning/node',
-    method: 'PUT',
-    body: { content, id }
-  })
-}
-
-export function setSkillEnabled(
-  name: string,
-  enabled: boolean,
-  profile?: ProfileScope
-): Promise<{ ok: boolean; name: string; enabled: boolean }> {
-  return window.hermesDesktop.api<{ ok: boolean; name: string; enabled: boolean }>({
-    ...capabilityScoped(profile),
-    path: '/api/skills/toggle',
-    method: 'PUT',
-    body: { name, enabled }
-  })
-}
-
-export interface McpTestResult {
-  ok: boolean
-  error?: string
-  /** `schema_chars` (converted registry-schema size, chars) is additive —
-   *  older backends omit it and the cost overlay shows no token estimate. */
-  tools: { name: string; description: string; schema_chars?: number }[]
-  /** Capability counts (absent on older backends / failed probes). */
-  prompts?: number
-  resources?: number
-}
-
-export interface McpOAuthFlow {
-  flow_id: string
-  server_name: string
-  status: 'starting' | 'authorization_required' | 'approved' | 'error'
-  authorization_url: string | null
-  error: string | null
-  tools?: { name: string; description: string }[]
-}
-
-/** Connect to the server, list its tools, disconnect. Slow (spawns/handshakes
- *  for real) — well past the 15s default fetch timeout. */
-export function testMcpServer(name: string, profile?: ProfileScope): Promise<McpTestResult> {
-  return window.hermesDesktop.api<McpTestResult>({
-    ...capabilityScoped(profile),
-    path: `/api/mcp/servers/${encodeURIComponent(name)}/test`,
-    method: 'POST',
-    timeoutMs: 60_000
-  })
-}
-
-/** Replace the whole `mcp_servers` map (the mcp.json editor's save). Unlike
- *  `saveHermesConfig`, this REPLACES rather than deep-merges, so deletes,
- *  re-enables (dropping `enabled: false`), and removed nested fields persist. */
-export function saveMcpServers(
-  servers: Record<string, Record<string, unknown>>,
-  profile?: ProfileScope
-): Promise<{ ok: boolean }> {
-  return window.hermesDesktop.api<{ ok: boolean }>({
-    ...capabilityScoped(profile),
-    path: '/api/mcp/servers',
-    method: 'PUT',
-    body: { servers }
-  })
-}
-
-/** Start an MCP OAuth flow and return the authorization URL. */
-export function authMcpServer(name: string, profile?: ProfileScope): Promise<McpOAuthFlow> {
-  return window.hermesDesktop.api<McpOAuthFlow>({
-    ...capabilityScoped(profile),
-    path: `/api/mcp/servers/${encodeURIComponent(name)}/auth`,
-    method: 'POST',
-    timeoutMs: 60_000
-  })
-}
-
-export function getMcpOAuthFlow(flowId: string, profile?: ProfileScope): Promise<McpOAuthFlow> {
-  return window.hermesDesktop.api<McpOAuthFlow>({
-    ...capabilityScoped(profile),
-    path: `/api/mcp/oauth/flows/${encodeURIComponent(flowId)}`
-  })
-}
-
-/** Cancel an in-flight MCP OAuth flow server-side, freeing the per-server
- *  "already in progress" slot so a retry doesn't 409. */
-export function cancelMcpOAuthFlow(flowId: string, profile?: null | string): Promise<{ ok: boolean; status: string }> {
-  return hermesApi<{ ok: boolean; status: string }>({
-    ...profileScoped(profile),
-    path: `/api/mcp/oauth/flows/${encodeURIComponent(flowId)}`,
-    method: 'DELETE'
-  })
-}
-
-// The optional trailing `profile` on every capability fetcher below is the
-// Capabilities view's profile-scope override: it lets the Skills/Tools/MCP
-// panels configure ANY profile without swapping the app-wide active profile.
-// Omitting it (every pre-existing caller) means `profileScoped(undefined)`
-// falls back to the app-wide `_apiProfile`, so behavior is byte-identical.
-export function getToolsets(profile?: ProfileScope): Promise<ToolsetInfo[]> {
-  return window.hermesDesktop.api<ToolsetInfo[]>({
-    ...capabilityScoped(profile),
-    path: '/api/tools/toolsets'
-  })
-}
-
-export function setToolsetEnabled(
-  name: string,
-  enabled: boolean,
-  profile?: ProfileScope
-): Promise<{ ok: boolean; name: string; enabled: boolean }> {
-  return window.hermesDesktop.api<{ ok: boolean; name: string; enabled: boolean }>({
-    ...capabilityScoped(profile),
-    path: `/api/tools/toolsets/${encodeURIComponent(name)}`,
-    method: 'PUT',
-    body: { enabled }
-  })
-}
-
-export function getToolsetConfig(name: string, profile?: ProfileScope): Promise<ToolsetConfig> {
-  return window.hermesDesktop.api<ToolsetConfig>({
-    ...capabilityScoped(profile),
-    path: `/api/tools/toolsets/${encodeURIComponent(name)}/config`
-  })
-}
-
-export function getToolsetModels(
-  name: string,
-  provider?: string,
-  profile?: ProfileScope
-): Promise<ToolsetModelsResponse> {
-  const suffix = provider ? `?provider=${encodeURIComponent(provider)}` : ''
-
-  return window.hermesDesktop.api<ToolsetModelsResponse>({
-    ...capabilityScoped(profile),
-    path: `/api/tools/toolsets/${encodeURIComponent(name)}/models${suffix}`
-  })
-}
-
-export function selectToolsetModel(
-  name: string,
-  model: string,
-  provider?: string,
-  profile?: ProfileScope
-): Promise<{ ok: boolean; name: string; model: string }> {
-  return window.hermesDesktop.api<{ ok: boolean; name: string; model: string }>({
-    ...capabilityScoped(profile),
-    path: `/api/tools/toolsets/${encodeURIComponent(name)}/model`,
-    method: 'PUT',
-    body: { model, provider }
-  })
-}
-
-export interface SelectToolsetProviderResponse {
-  ok: boolean
-  name: string
-  provider: string
-  /** Present when the selection was scoped to one web capability. */
-  capability?: string
-  /** Present (true) when a managed Nous row was selected but the Portal
-   *  entitlement is missing — the row won't activate until the user signs
-   *  in to Nous Portal. */
-  needs_nous_auth?: boolean
-  /** The managed feature key (e.g. "browser") when needs_nous_auth is set. */
-  feature?: string
-}
-
-export function selectToolsetProvider(
-  name: string,
-  provider: string,
-  capability?: 'search' | 'extract',
-  profile?: ProfileScope
-): Promise<SelectToolsetProviderResponse> {
-  return window.hermesDesktop.api<SelectToolsetProviderResponse>({
-    ...capabilityScoped(profile),
-    path: `/api/tools/toolsets/${encodeURIComponent(name)}/provider`,
-    method: 'PUT',
-    body: capability ? { provider, capability } : { provider }
-  })
-}
-
-export function runToolsetPostSetup(
-  name: string,
-  key: string,
-  profile?: ProfileScope
-): Promise<ActionResponse & { key: string }> {
-  return window.hermesDesktop.api<ActionResponse & { key: string }>({
-    ...capabilityScoped(profile),
-    path: `/api/tools/toolsets/${encodeURIComponent(name)}/post-setup`,
-    method: 'POST',
-    body: { key }
-  })
-}
-
-export function getTerminalBackends(): Promise<TerminalBackendsResponse> {
-  return hermesApi<TerminalBackendsResponse>({
-    ...profileScoped(),
-    path: '/api/tools/terminal/backends'
-  })
-}
-
-export function selectTerminalBackend(backend: string): Promise<{ ok: boolean; backend: string }> {
-  return hermesApi<{ ok: boolean; backend: string }>({
-    ...profileScoped(),
-    path: '/api/tools/terminal/backend',
-    method: 'PUT',
-    body: { backend }
-  })
-}
-
-export function getComputerUseStatus(): Promise<ComputerUseStatus> {
-  return hermesApi<ComputerUseStatus>({
-    ...profileScoped(),
-    path: '/api/tools/computer-use/status'
-  })
-}
-
-export function grantComputerUsePermissions(): Promise<ActionResponse> {
-  return hermesApi<ActionResponse>({
-    ...profileScoped(),
-    path: '/api/tools/computer-use/permissions/grant',
-    method: 'POST'
-  })
-}
-
-export function getMessagingPlatforms(profile?: null | string): Promise<MessagingPlatformsResponse> {
-  return hermesApi<MessagingPlatformsResponse>({
-    ...profileScoped(profile),
-    path: '/api/messaging/platforms'
-  })
-}
-
-export function updateMessagingPlatform(
-  platformId: string,
-  body: MessagingPlatformUpdate,
-  profile?: null | string
-): Promise<{ ok: boolean; platform: string }> {
-  return hermesApi<{ ok: boolean; platform: string }>({
-    ...profileScoped(profile),
-    path: `/api/messaging/platforms/${encodeURIComponent(platformId)}`,
-    method: 'PUT',
-    body
-  })
-}
-
-export function testMessagingPlatform(
-  platformId: string,
-  profile?: null | string
-): Promise<MessagingPlatformTestResponse> {
-  return hermesApi<MessagingPlatformTestResponse>({
-    ...profileScoped(profile),
-    path: `/api/messaging/platforms/${encodeURIComponent(platformId)}/test`,
-    method: 'POST'
-  })
-}
-
-// -- Pairing (who may DM the bot) --------------------------------------------
-// Unknown DMers get a one-time code and land in `pending` until an admin
-// approves them. Approval grants on the row's `request_id`, never on the code:
-// the code is the requester's proof that the channel is theirs and is never
-// returned by the API, while an authenticated admin is only ever identifying
-// a row they can already see.
-
-export function getPairing(profile?: null | string): Promise<PairingResponse> {
-  return hermesApi<PairingResponse>({
-    ...profileScoped(profile),
-    path: '/api/pairing'
-  })
-}
-
-export function approvePairing(
-  platform: string,
-  requestId: string,
-  profile?: null | string
-): Promise<{ ok: boolean; user: PairingUser }> {
-  return hermesApi<{ ok: boolean; user: PairingUser }>({
-    ...profileScoped(profile),
-    path: '/api/pairing/approve',
-    method: 'POST',
-    // These endpoints read the profile off the body, not the query string —
-    // `profileScoped()` alone would approve into the wrong profile's store.
-    body: { platform, request_id: requestId, ...profileScoped(profile) }
-  })
-}
-
-export function revokePairing(platform: string, userId: string, profile?: null | string): Promise<{ ok: boolean }> {
-  return hermesApi<{ ok: boolean }>({
-    ...profileScoped(profile),
-    path: '/api/pairing/revoke',
-    method: 'POST',
-    body: { platform, user_id: userId, ...profileScoped(profile) }
-  })
-}
-
-// -- Webhooks (subscription CRUD) --------------------------------------------
-// The webhook receiver is its own gateway platform; subscriptions live in a
-// shared JSON store the CLI/dashboard also drive. Enable mutates config and
-// best-effort restarts the gateway; subscription changes hot-reload.
-
-export function getWebhooks(): Promise<WebhooksResponse> {
-  return hermesApi<WebhooksResponse>({
-    ...profileScoped(),
-    path: '/api/webhooks'
-  })
-}
-
-export function enableWebhooks(): Promise<WebhookEnableResponse> {
-  return hermesApi<WebhookEnableResponse>({
-    ...profileScoped(),
-    path: '/api/webhooks/enable',
-    method: 'POST'
-  })
-}
-
-export function createWebhook(body: WebhookCreatePayload): Promise<WebhookCreateResponse> {
-  return hermesApi<WebhookCreateResponse>({
-    ...profileScoped(),
-    path: '/api/webhooks',
-    method: 'POST',
-    body
-  })
-}
-
-export function deleteWebhook(name: string): Promise<{ ok: boolean }> {
-  return hermesApi<{ ok: boolean }>({
-    ...profileScoped(),
-    path: `/api/webhooks/${encodeURIComponent(name)}`,
-    method: 'DELETE'
-  })
-}
-
-export function setWebhookEnabled(
-  name: string,
-  enabled: boolean
-): Promise<{ enabled: boolean; name: string; ok: boolean }> {
-  return hermesApi<{ enabled: boolean; name: string; ok: boolean }>({
-    ...profileScoped(),
-    path: `/api/webhooks/${encodeURIComponent(name)}/enabled`,
-    method: 'PUT',
-    body: { enabled }
-  })
-}
-
-// Cron jobs are stored per-profile (<HERMES_HOME>/cron/jobs.json), and the
-// backend's list endpoint defaults to 'all'. Pass a concrete profile key to
-// list just that profile's jobs, or 'all' for the unified cross-profile view.
-// Omitting the arg keeps the legacy 'all' default for non-profile callers.
-// profileScoped() still rides along for backend-process routing.
-export function getCronJobs(profile?: string): Promise<CronJob[]> {
-  const suffix = profile ? `?profile=${encodeURIComponent(profile)}` : ''
-
-  return hermesApi<CronJob[]>({
-    ...profileScoped(),
-    ...connectionScoped(),
-    path: `/api/cron/jobs${suffix}`,
-    timeoutMs: STARTUP_REQUEST_TIMEOUT_MS
-  })
-}
-
-export function getCronJob(jobId: string): Promise<CronJob> {
-  return hermesApi<CronJob>({
-    ...profileScoped(),
-    ...connectionScoped(),
-    path: `/api/cron/jobs/${encodeURIComponent(jobId)}`
-  })
-}
-
-export async function getCronJobRuns(jobId: string, limit = 20): Promise<SessionInfo[]> {
-  const { runs } = await hermesApi<{ runs: SessionInfo[] }>({
-    ...profileScoped(),
-    ...connectionScoped(),
-    path: `/api/cron/jobs/${encodeURIComponent(jobId)}/runs?limit=${limit}`
-  })
-
-  return runs ?? []
-}
-
-// The single source of truth for cron delivery targets (local + configured
-// gateways). Both the manual cron editor and the blueprint dialog use this so
-// they never offer a platform that isn't connected. Mirrors the dashboard.
-export async function getCronDeliveryTargets(): Promise<CronDeliveryTarget[]> {
-  const { targets } = await hermesApi<{ targets: CronDeliveryTarget[] }>({
-    ...profileScoped(),
-    ...connectionScoped(),
-    path: '/api/cron/delivery-targets'
-  })
-
-  return targets ?? []
-}
-
-export function createCronJob(body: CronJobCreatePayload): Promise<CronJob> {
-  return hermesApi<CronJob>({
-    ...profileScoped(),
-    ...connectionScoped(),
-    path: '/api/cron/jobs',
-    method: 'POST',
-    body
-  })
-}
-
-export function updateCronJob(jobId: string, updates: CronJobUpdates): Promise<CronJob> {
-  return hermesApi<CronJob>({
-    ...profileScoped(),
-    ...connectionScoped(),
-    path: `/api/cron/jobs/${encodeURIComponent(jobId)}`,
-    method: 'PUT',
-    body: { updates }
-  })
-}
-
-export function pauseCronJob(jobId: string): Promise<CronJob> {
-  return hermesApi<CronJob>({
-    ...profileScoped(),
-    ...connectionScoped(),
-    path: `/api/cron/jobs/${encodeURIComponent(jobId)}/pause`,
-    method: 'POST'
-  })
-}
-
-export function resumeCronJob(jobId: string): Promise<CronJob> {
-  return hermesApi<CronJob>({
-    ...profileScoped(),
-    ...connectionScoped(),
-    path: `/api/cron/jobs/${encodeURIComponent(jobId)}/resume`,
-    method: 'POST'
-  })
-}
-
-export function triggerCronJob(jobId: string): Promise<CronJob> {
-  return hermesApi<CronJob>({
-    ...profileScoped(),
-    ...connectionScoped(),
-    path: `/api/cron/jobs/${encodeURIComponent(jobId)}/trigger`,
-    method: 'POST',
-    timeoutMs: CRON_TRIGGER_REQUEST_TIMEOUT_MS
-  })
-}
-
-export function deleteCronJob(jobId: string): Promise<{ ok: boolean }> {
-  return hermesApi<{ ok: boolean }>({
-    ...profileScoped(),
-    ...connectionScoped(),
-    path: `/api/cron/jobs/${encodeURIComponent(jobId)}`,
-    method: 'DELETE'
-  })
-}
-
-// Automation Blueprints — parameterized cron templates the backend serves from
-// cron/blueprint_catalog.py. getAutomationBlueprints returns the gallery
-// (deliver options already rewritten to this machine's configured gateways);
-// instantiateAutomationBlueprint fills the slots and creates a real cron job via
-// the same create_job path as createCronJob.
-//
-// Profile-scoping is intentionally asymmetric: the GET catalog is global (the
-// list endpoint takes no profile — only deliver options are rewritten from the
-// configured gateways), so it carries only the profileScoped() header for
-// routing. instantiate creates a real per-profile job, so it names the target
-// profile explicitly via ?profile=. This mirrors the dashboard's api.ts.
-export function getAutomationBlueprints(): Promise<{ blueprints: AutomationBlueprint[] }> {
-  return hermesApi<{ blueprints: AutomationBlueprint[] }>({
-    ...profileScoped(),
-    ...connectionScoped(),
-    path: '/api/cron/blueprints',
-    timeoutMs: STARTUP_REQUEST_TIMEOUT_MS
-  })
-}
-
-export function instantiateAutomationBlueprint(
-  body: { blueprint: string; values: Record<string, string> },
-  profile: string
-): Promise<CronJob> {
-  return hermesApi<CronJob>({
-    ...profileScoped(),
-    ...connectionScoped(),
-    path: `/api/cron/blueprints/instantiate?profile=${encodeURIComponent(profile)}`,
-    method: 'POST',
-    body
-  })
-}
-
-export function getProfiles(): Promise<ProfilesResponse> {
-  return hermesApi<ProfilesResponse>({
-    path: '/api/profiles',
-    timeoutMs: STARTUP_REQUEST_TIMEOUT_MS
-  })
-}
-
-export function createProfile(body: ProfileCreatePayload): Promise<{ name: string; ok: boolean; path: string }> {
-  return hermesApi<{ name: string; ok: boolean; path: string }>({
-    path: '/api/profiles',
-    method: 'POST',
-    body
-  })
-}
-
-export function renameProfile(name: string, newName: string): Promise<{ name: string; ok: boolean; path: string }> {
-  return hermesApi<{ name: string; ok: boolean; path: string }>({
-    path: `/api/profiles/${encodeURIComponent(name)}`,
-    method: 'PATCH',
-    body: { new_name: newName }
-  })
-}
-
-export function deleteProfile(name: string): Promise<{ ok: boolean; path: string }> {
-  return hermesApi<{ ok: boolean; path: string }>({
-    path: `/api/profiles/${encodeURIComponent(name)}`,
-    method: 'DELETE'
-  })
-}
-
-export function getProfileSoul(name: string): Promise<ProfileSoul> {
-  return hermesApi<ProfileSoul>({
-    path: `/api/profiles/${encodeURIComponent(name)}/soul`
-  })
-}
-
-export function updateProfileSoul(name: string, content: string): Promise<{ ok: boolean }> {
-  return hermesApi<{ ok: boolean }>({
-    path: `/api/profiles/${encodeURIComponent(name)}/soul`,
-    method: 'PUT',
-    body: { content }
-  })
-}
-
-export function getProfileSetupCommand(name: string): Promise<ProfileSetupCommand> {
-  return hermesApi<ProfileSetupCommand>({
-    path: `/api/profiles/${encodeURIComponent(name)}/setup-command`
-  })
-}
-
-/** Export a profile to a shareable .tar.gz on the backend's filesystem.
- *  `extraFiles` stages extra root-level files (desktop.json — the appearance/
- *  interface overlay) into the archive alongside the profile's own artifacts. */
-export function exportProfileArchive(
-  name: string,
-  opts: { extraFiles?: Record<string, string>; output?: string } = {}
-): Promise<{ archive: string; ok: boolean }> {
-  return hermesApi<{ archive: string; ok: boolean }>({
-    path: `/api/profiles/${encodeURIComponent(name)}/export`,
-    method: 'POST',
-    body: { extra_files: opts.extraFiles ?? {}, output: opts.output ?? '' },
-    timeoutMs: STARTUP_REQUEST_TIMEOUT_MS
-  })
-}
-
-/** Import a profile .tar.gz as a new profile. Returns the bundled desktop
- *  appearance overlay too (when the archive carried one) so the caller can
- *  apply theme/layout without another round-trip. */
-export function importProfileArchive(
-  archive: string,
-  name?: string
-): Promise<{ desktop: null | ProfileDesktopOverlay; name: string; ok: boolean; path: string }> {
-  return hermesApi<{ desktop: null | ProfileDesktopOverlay; name: string; ok: boolean; path: string }>({
-    path: '/api/profiles/import',
-    method: 'POST',
-    body: { archive, name: name || null },
-    timeoutMs: STARTUP_REQUEST_TIMEOUT_MS
-  })
-}
-
-export function getUsageAnalytics(days = 30, profile?: ProfileScope): Promise<AnalyticsResponse> {
-  return window.hermesDesktop.api<AnalyticsResponse>({
-    ...capabilityScoped(profile),
-    path: `/api/analytics/usage?days=${Math.max(1, Math.floor(days))}`
-  })
-}
-
-export function getGlobalModelOptions(
-  opts?: {
-    refresh?: boolean
-    includeUnconfigured?: boolean
-    explicitOnly?: boolean
-  },
-  profile?: null | string
-): Promise<ModelOptionsResponse> {
-  const params = new URLSearchParams()
-
-  if (opts?.refresh) {
-    params.set('refresh', '1')
-  }
-
-  if (opts?.includeUnconfigured) {
-    params.set('include_unconfigured', '1')
-  }
-
-  if (opts?.explicitOnly !== false) {
-    params.set('explicit_only', '1')
-  }
-
-  return hermesApi<ModelOptionsResponse>({
-    ...profileScoped(profile),
-    path: params.size > 0 ? `/api/model/options?${params.toString()}` : '/api/model/options',
-    timeoutMs: STARTUP_REQUEST_TIMEOUT_MS
-  })
-}
-
-export interface RecommendedDefaultModel {
-  provider: string
-  model: string
-  /** True/false for Nous (free vs paid tier); null for other providers. */
-  free_tier: boolean | null
-}
-
-// Recommended default model for a freshly-authenticated provider. Mirrors the
-// curation `hermes model` does — for Nous it honors the free/paid tier so a
-// free user gets a free model instead of a paid default.
-export function getRecommendedDefaultModel(
-  provider: string,
-  profile?: null | string
-): Promise<RecommendedDefaultModel> {
-  return hermesApi<RecommendedDefaultModel>({
-    ...profileScoped(profile),
-    path: `/api/model/recommended-default?provider=${encodeURIComponent(provider)}`
-  })
-}
-
-export function setGlobalModel(
-  provider: string,
-  model: string
-): Promise<{ ok: boolean; provider: string; model: string }> {
-  return hermesApi<{ ok: boolean; provider: string; model: string }>({
-    ...profileScoped(),
-    path: '/api/model/set',
-    method: 'POST',
-    body: {
-      scope: 'main',
-      provider,
-      model
-    }
-  })
-}
-
-export function getAuxiliaryModels(profile?: null | string): Promise<AuxiliaryModelsResponse> {
-  return hermesApi<AuxiliaryModelsResponse>({
-    ...profileScoped(profile),
-    path: '/api/model/auxiliary'
-  })
-}
-
-export function getMoaModels(profile?: null | string): Promise<MoaConfigResponse> {
-  return hermesApi<MoaConfigResponse>({
-    ...profileScoped(profile),
-    path: '/api/model/moa'
-  })
-}
-
-export function saveMoaModels(
-  body: MoaConfigResponse,
-  profile?: null | string
-): Promise<MoaConfigResponse & { ok: boolean }> {
-  return hermesApi<MoaConfigResponse & { ok: boolean }>({
-    ...profileScoped(profile),
-    path: '/api/model/moa',
-    method: 'PUT',
-    body
-  })
-}
-
-export function setModelAssignment(
-  body: ModelAssignmentRequest,
-  profile?: null | string
-): Promise<ModelAssignmentResponse> {
-  return hermesApi<ModelAssignmentResponse>({
-    ...profileScoped(profile),
-    path: '/api/model/set',
-    method: 'POST',
-    body
-  })
-}
-
-export function restartGateway(): Promise<ActionResponse> {
-  return hermesApi<ActionResponse>({
-    ...profileScoped(),
-    path: '/api/gateway/restart',
-    method: 'POST'
-  })
-}
-
-export function updateHermes(): Promise<ActionResponse> {
-  return hermesApi<ActionResponse>({
-    ...profileScoped(),
-    path: '/api/hermes/update',
-    method: 'POST'
-  })
-}
-
-/** Query the connected backend's own update state. In remote mode this is the
- *  authoritative source for the backend's behind-count + "what's changed",
- *  distinct from the Electron client clone's git state. */
-export function checkHermesUpdate(force = false): Promise<BackendUpdateCheckResponse> {
-  return hermesApi<BackendUpdateCheckResponse>({
-    ...profileScoped(),
-    path: `/api/hermes/update/check${force ? '?force=true' : ''}`
-  })
-}
-
-export function getActionStatus(name: string, lines = 200, profile?: ProfileScope): Promise<ActionStatusResponse> {
-  return window.hermesDesktop.api<ActionStatusResponse>({
-    ...capabilityScoped(profile),
-    path: `/api/actions/${encodeURIComponent(name)}/status?lines=${Math.max(1, lines)}`
-  })
-}
-
-export function transcribeAudio(dataUrl: string, mimeType?: string): Promise<AudioTranscriptionResponse> {
-  return hermesApi<AudioTranscriptionResponse>({
-    path: '/api/audio/transcribe',
-    method: 'POST',
-    ...profileScoped(),
-    body: {
-      data_url: dataUrl,
-      mime_type: mimeType
-    },
-    // Transcription blocks until provider STT, file handling, and response
-    // encoding finish. Remote providers and long clips regularly exceed the
-    // default 15s Electron backend timeout.
-    timeoutMs: audioTranscribeRequestTimeoutMs(dataUrl)
-  })
-}
-
-export function speakText(text: string): Promise<AudioSpeakResponse> {
-  return hermesApi<AudioSpeakResponse>({
-    ...profileScoped(),
-    path: '/api/audio/speak',
-    method: 'POST',
-    body: { text },
-    // TTS blocks until provider synthesis, file read, and base64 encoding
-    // finish. Remote providers and large messages regularly exceed the
-    // default 15s Electron backend timeout.
-    timeoutMs: audioSpeakRequestTimeoutMs(text)
-  })
-}
-
-export function getElevenLabsVoices(profile?: null | string): Promise<ElevenLabsVoicesResponse> {
-  return hermesApi<ElevenLabsVoicesResponse>({
-    path: '/api/audio/elevenlabs/voices',
-    ...profileScoped(profile)
-  })
-}
-
-// ---------------------------------------------------------------------------
-// Skills hub — search / preview / scan / install (parity with `hermes skills`
-// and the dashboard's Browse-hub tab). Installs spawn background actions whose
-// logs are tailed via getActionStatus().
-// ---------------------------------------------------------------------------
-
-const HUB_REQUEST_TIMEOUT_MS = 45_000
-
-export function getSkillHubSources(profile?: null | string): Promise<SkillHubSourcesResponse> {
-  return hermesApi<SkillHubSourcesResponse>({
-    ...profileScoped(profile),
-    path: '/api/skills/hub/sources',
-    timeoutMs: HUB_REQUEST_TIMEOUT_MS
-  })
-}
-
-export function searchSkillsHub(
-  query: string,
-  source = 'all',
-  limit = 20,
-  profile?: null | string
-): Promise<SkillHubSearchResponse> {
-  const params = new URLSearchParams({ q: query, source, limit: String(limit) })
-
-  return hermesApi<SkillHubSearchResponse>({
-    ...profileScoped(profile),
-    path: `/api/skills/hub/search?${params.toString()}`,
-    timeoutMs: HUB_REQUEST_TIMEOUT_MS
-  })
-}
-
-export function previewSkillHub(identifier: string, profile?: null | string): Promise<SkillHubPreview> {
-  return hermesApi<SkillHubPreview>({
-    ...profileScoped(profile),
-    path: `/api/skills/hub/preview?identifier=${encodeURIComponent(identifier)}`,
-    timeoutMs: HUB_REQUEST_TIMEOUT_MS
-  })
-}
-
-export function scanSkillHub(identifier: string, profile?: null | string): Promise<SkillHubScanResult> {
-  return hermesApi<SkillHubScanResult>({
-    ...profileScoped(profile),
-    path: `/api/skills/hub/scan?identifier=${encodeURIComponent(identifier)}`,
-    timeoutMs: HUB_REQUEST_TIMEOUT_MS
-  })
-}
-
-export function installSkillFromHub(identifier: string, profile?: ProfileScope): Promise<ActionResponse> {
-  return window.hermesDesktop.api<ActionResponse>({
-    ...capabilityScoped(profile),
-    path: '/api/skills/hub/install',
-    method: 'POST',
-    body: { identifier }
-  })
-}
-
-export function uninstallSkillFromHub(name: string, profile?: ProfileScope): Promise<ActionResponse> {
-  return window.hermesDesktop.api<ActionResponse>({
-    ...capabilityScoped(profile),
-    path: '/api/skills/hub/uninstall',
-    method: 'POST',
-    body: { name }
-  })
-}
-
-export function updateSkillsFromHub(profile?: ProfileScope): Promise<ActionResponse> {
-  return window.hermesDesktop.api<ActionResponse>({
-    ...capabilityScoped(profile),
-    path: '/api/skills/hub/update',
-    method: 'POST',
-    body: {}
-  })
-}
-
-// ---------------------------------------------------------------------------
-// MCP servers — structured list / test / enable toggle / catalog (parity with
-// `hermes mcp` and the dashboard MCP page). Raw JSON editing stays in
-// config.yaml via saveHermesConfig.
-// ---------------------------------------------------------------------------
-
-export function listMcpServers(): Promise<{ servers: McpServerSummary[] }> {
-  return hermesApi<{ servers: McpServerSummary[] }>({
-    ...profileScoped(),
-    path: '/api/mcp/servers'
-  })
-}
-
-/** Add one server to `mcp_servers` (validated + name-collision-checked
- *  server-side — the same endpoint the dashboard's add form uses). */
-export function addMcpServer(body: {
-  name: string
-  url?: string
-  command?: string
-  args?: string[]
-  env?: Record<string, string>
-  auth?: string
-}): Promise<McpServerSummary> {
-  return hermesApi<McpServerSummary>({
-    ...profileScoped(),
-    path: '/api/mcp/servers',
-    method: 'POST',
-    body
-  })
-}
-
-/** Remove one server from `mcp_servers` (the inline setup card's rollback
- *  when a directory install is cancelled after the config write). */
-export function removeMcpServer(name: string): Promise<{ ok: boolean }> {
-  return hermesApi<{ ok: boolean }>({
-    ...profileScoped(),
-    path: `/api/mcp/servers/${encodeURIComponent(name)}`,
-    method: 'DELETE'
-  })
-}
-
-export function setMcpServerEnabled(name: string, enabled: boolean): Promise<{ ok: boolean }> {
-  return hermesApi<{ ok: boolean }>({
-    ...profileScoped(),
-    path: `/api/mcp/servers/${encodeURIComponent(name)}/enabled`,
-    method: 'PUT',
-    body: { enabled }
-  })
-}
-
-export function getMcpCatalog(profile?: ProfileScope): Promise<McpCatalogResponse> {
-  return window.hermesDesktop.api<McpCatalogResponse>({
-    ...capabilityScoped(profile),
-    path: '/api/mcp/catalog'
-  })
-}
-
-/** `gh` CLI presence + auth state, for the composer's GitHub skill pill
- *  (GitHub is deliberately not an MCP — the github/* skills are the
- *  integration). Backend caches for 5 minutes; `refresh` bypasses. */
-export function getGhAuthStatus(refresh = false): Promise<{ available: boolean; authenticated: boolean }> {
-  return hermesApi<{ available: boolean; authenticated: boolean }>({
-    ...profileScoped(),
-    path: `/api/git/gh-auth${refresh ? '?refresh=true' : ''}`
-  })
-}
-
-export function installMcpCatalogEntry(
-  name: string,
-  env: Record<string, string> = {},
-  profile?: ProfileScope
-): Promise<{ ok: boolean; name?: string; pid?: number; action?: string; background?: boolean }> {
-  return window.hermesDesktop.api<{ ok: boolean; name?: string; pid?: number; action?: string; background?: boolean }>({
-    ...capabilityScoped(profile),
-    path: '/api/mcp/catalog/install',
-    method: 'POST',
-    body: { name, env, enable: true },
-    timeoutMs: 60_000
-  })
-}
-
-// ---------------------------------------------------------------------------
-// Memory data + curator (parity with `hermes memory` / `hermes curator`).
-// ---------------------------------------------------------------------------
-
-export function getMemoryStatus(): Promise<MemoryStatusResponse> {
-  return hermesApi<MemoryStatusResponse>({
-    ...profileScoped(),
-    path: '/api/memory'
-  })
-}
-
-export function resetMemory(target: 'all' | 'memory' | 'user'): Promise<{ ok: boolean; deleted: string[] }> {
-  return hermesApi<{ ok: boolean; deleted: string[] }>({
-    ...profileScoped(),
-    path: '/api/memory/reset',
-    method: 'POST',
-    body: { target }
-  })
-}
-
-export function getCuratorStatus(): Promise<CuratorStatusResponse> {
-  return hermesApi<CuratorStatusResponse>({
-    ...profileScoped(),
-    path: '/api/curator'
-  })
-}
-
-export function setCuratorPaused(paused: boolean): Promise<{ ok: boolean; paused: boolean }> {
-  return hermesApi<{ ok: boolean; paused: boolean }>({
-    ...profileScoped(),
-    path: '/api/curator/paused',
-    method: 'PUT',
-    body: { paused }
-  })
-}
-
-export function runCurator(): Promise<ActionResponse> {
-  return hermesApi<ActionResponse>({
-    ...profileScoped(),
-    path: '/api/curator/run',
-    method: 'POST',
-    body: {}
-  })
-}
-
-// ---------------------------------------------------------------------------
-// Maintenance operations (parity with `hermes doctor` / `hermes security
-// audit` / `hermes backup` / `hermes debug share` and the dashboard System
-// page). All except debug share are spawn-based background actions tailed via
-// getActionStatus().
-// ---------------------------------------------------------------------------
-
-export function runDoctor(): Promise<ActionResponse> {
-  return hermesApi<ActionResponse>({ path: '/api/ops/doctor', method: 'POST', body: {} })
-}
-
-export function runSecurityAudit(): Promise<ActionResponse> {
-  return hermesApi<ActionResponse>({ path: '/api/ops/security-audit', method: 'POST', body: {} })
-}
-
-export function runBackup(): Promise<ActionResponse & { archive?: string }> {
-  return hermesApi<ActionResponse & { archive?: string }>({
-    path: '/api/ops/backup',
-    method: 'POST',
-    body: {}
-  })
-}
-
-export function runDebugShare(): Promise<DebugShareResponse> {
-  return hermesApi<DebugShareResponse>({
-    path: '/api/ops/debug-share',
-    method: 'POST',
-    body: {},
-    // Synchronous upload of report + logs to the paste service.
-    timeoutMs: 120_000
-  })
-}

From eb523288570408132b4e005f58d6cfecb78055ef Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 19 Aug 2026 02:09:58 -0500
Subject: [PATCH 08/48] feat(desktop): back window glass with Windows 11 system
 materials
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Glass was macOS-only because it rode setVibrancy. Windows 11 22H2 has a
first-party equivalent in setBackgroundMaterial, so the mode now resolves
its backing per platform instead of per-OS-check: macOS keeps vibrancy,
Windows 11 gets DWM acrylic / tabbed / mica, and everything older stays on
Clear. No third-party native addon.

Two Windows-specific details the mapping has to respect. DWM only paints
the client area of a transparent window (electron#49443), so glass-capable
Windows chat windows are born transparent with the opaque themed
backgroundColor covering them while glass is off — a live Clear/Glass
toggle then needs no window recreate. And Windows exposes three backdrops
for four frost rungs, so the two heaviest both resolve to mica; the mapping
stays total so a frost saved on a Mac still renders.

Glass support is computed once from os.release() and shared: main uses it
for the persisted default and every window, preload publishes it to the
renderer so the UI can't offer a mode the window can't back.
---
 apps/desktop/electron/main.ts               |  59 +++++--
 apps/desktop/electron/preload.ts            |   5 +
 apps/desktop/electron/translucency.test.ts  | 177 +++++++++++++++++--
 apps/desktop/electron/translucency.ts       |   8 +
 apps/desktop/src/global.d.ts                |   4 +
 apps/desktop/src/i18n/ar.ts                 |   6 +-
 apps/desktop/src/i18n/en.ts                 |   7 +-
 apps/desktop/src/i18n/ja.ts                 |   6 +-
 apps/desktop/src/i18n/types.ts              |   2 +
 apps/desktop/src/i18n/zh-hant.ts            |   6 +-
 apps/desktop/src/i18n/zh.ts                 |   6 +-
 apps/desktop/src/lib/platform.ts            |  13 +-
 apps/desktop/src/store/translucency.test.ts |   5 +-
 apps/desktop/src/store/translucency.ts      |  47 +++++-
 apps/desktop/src/styles.css                 |  32 ++--
 apps/shared/src/index.ts                    |   8 +
 apps/shared/src/translucency.ts             | 178 ++++++++++++++++----
 17 files changed, 476 insertions(+), 93 deletions(-)

diff --git a/apps/desktop/electron/main.ts b/apps/desktop/electron/main.ts
index 8e35bbefd9..c4746fc313 100644
--- a/apps/desktop/electron/main.ts
+++ b/apps/desktop/electron/main.ts
@@ -302,7 +302,9 @@ import {
 import { createStreamThrottle } from './stream-throttle'
 import { nativeOverlayWidth as computeNativeOverlayWidth, macTitleBarOverlayHeight } from './titlebar-overlay-width'
 import {
+  backgroundMaterialFor,
   glassActive,
+  glassSupportedOn,
   normalizeState as normalizeTranslucency,
   vibrancyFor as vibrancyForTranslucency,
   windowBackingOptions,
@@ -397,6 +399,9 @@ const IS_WSL = isWslEnvironment()
 // Truthful macOS kernel major (Tahoe = 25). Product version lies (16 vs 26) per
 // build SDK, so gate Tahoe workarounds on Darwin instead.
 const DARWIN_MAJOR = IS_MAC ? Number.parseInt(os.release(), 10) || 0 : 0
+// Glass: macOS vibrancy, or Windows 11 22H2+ system backdrop. Computed once
+// so the renderer, the persisted default, and every chat window agree.
+const GLASS_SUPPORTED = glassSupportedOn(process.platform, os.release())
 const APP_ROOT = app.getAppPath()
 
 // Device-local preference: block F12 from opening DevTools.
@@ -893,18 +898,19 @@ nativeTheme.themeSource = readPersistedThemeSource()
 // Window translucency (see-through window). One lever, 0–100; 0 = off (the
 // default). Two modes share the lever (see electron/translucency.ts and
 // store/translucency): 'clear' maps it to the native window opacity so the
-// desktop shows through the whole window; 'glass' (macOS) keeps the window
-// opaque and lets the renderer thin its surfaces over the vibrancy material
-// instead — a matte blur with full-contrast text. Persisted so a cold launch
-// applies it at window creation, before the renderer reports its value.
+// desktop shows through the whole window; 'glass' keeps the window opaque
+// and lets the renderer thin its surfaces over a platform material instead
+// — a matte blur with full-contrast text. macOS uses vibrancy; Windows 11
+// uses DWM acrylic/mica/tabbed. Persisted so a cold launch applies it at
+// window creation, before the renderer reports its value.
 // macOS + Windows only; `setOpacity` is a no-op on Linux.
 const TRANSLUCENCY_CONFIG_PATH = path.join(app.getPath('userData'), 'translucency.json')
 
 function readPersistedTranslucency() {
   try {
-    return normalizeTranslucency(JSON.parse(fs.readFileSync(TRANSLUCENCY_CONFIG_PATH, 'utf8')), IS_MAC)
+    return normalizeTranslucency(JSON.parse(fs.readFileSync(TRANSLUCENCY_CONFIG_PATH, 'utf8')), GLASS_SUPPORTED)
   } catch {
-    return normalizeTranslucency(null, IS_MAC)
+    return normalizeTranslucency(null, GLASS_SUPPORTED)
   }
 }
 
@@ -932,17 +938,20 @@ function windowOpacity() {
 // Re-apply translucency to a live window (runtime toggle, no recreation).
 // `setOpacity` is a no-op on Linux, which is fine — it just stays opaque there.
 // The backing swap is the glass half: Chromium composites the page against
-// the window backing BEFORE macOS composites the window, so glass needs the
-// backing dropped for the vibrancy material to reach a transparent page, and
+// the window backing BEFORE the OS composites the window, so glass needs the
+// backing dropped for the platform material to reach a transparent page, and
 // every other state needs the opaque themed backing (anti-flash, and it is
 // what makes clear mode fade to the desktop instead of to black).
 //
 // `changed` says which native properties actually need touching. Dragging the
 // intensity slider emits ~100 updates, and in glass mode NONE of them change
-// anything native — the effect is painted by the renderer and windowOpacityFor
-// returns 1 throughout. Re-issuing setVibrancy on every tick restarts its
-// 150ms animation before macOS can settle the material, which reads as jank
-// and flattens the frost levels into each other.
+// anything native — the tint is painted by the renderer and windowOpacityFor
+// answers off `fade`, not `intensity`, there. Re-issuing setVibrancy on every
+// tick restarts its 150ms animation before macOS can settle the material,
+// which reads as jank and flattens the frost levels into each other. Windows
+// setBackgroundMaterial is instantaneous but still skipped on tint-only ticks.
+// The glass Fade lever is the one glass drag that does reach main, and it
+// costs exactly what a Clear drag costs: one setOpacity.
 //
 // CAUTION (measured, macOS 26 / Electron 40): a runtime
 // setBackgroundColor('#00000000') is silently LOST on a window whose
@@ -964,11 +973,18 @@ function applyWindowTranslucency(win, changed = { backing: true, material: true,
         win.setBackgroundColor(glassActive(translucencyState) ? '#00000000' : getWindowBackgroundColor())
       }
 
-      // Glass frost level = the vibrancy material (macOS has no blur-radius
-      // knob). Animate the hop so a deliberate frost switch feels continuous —
-      // which only works if we don't re-issue it on unrelated updates.
-      if (changed.material && IS_MAC && typeof win.setVibrancy === 'function') {
-        win.setVibrancy(vibrancyForTranslucency(translucencyState), { animationDuration: 150 })
+      if (changed.material) {
+        // Glass frost level = the platform material. Animate the macOS hop so
+        // a deliberate frost switch feels continuous — which only works if we
+        // don't re-issue it on unrelated updates. Windows has no equivalent
+        // animation option; setBackgroundMaterial is instantaneous.
+        if (IS_MAC && typeof win.setVibrancy === 'function') {
+          win.setVibrancy(vibrancyForTranslucency(translucencyState), { animationDuration: 150 })
+        }
+
+        if (IS_WINDOWS && GLASS_SUPPORTED && typeof win.setBackgroundMaterial === 'function') {
+          win.setBackgroundMaterial(backgroundMaterialFor(translucencyState))
+        }
       }
     }
 
@@ -1001,6 +1017,12 @@ function chatWindowSurfaceOptions() {
     // user's frost choice whenever they click elsewhere. Only observable
     // under glass — everywhere else the page buries the material.
     visualEffectState: IS_MAC ? ('active' as const) : undefined,
+    // Win11 DWM materials only reach the client area on a transparent window
+    // (electron#49443). Chat windows on glass-capable Windows are born
+    // transparent so a live Clear→Glass toggle doesn't need a recreate; the
+    // opaque themed backgroundColor covers it while glass is off.
+    ...(IS_WINDOWS && GLASS_SUPPORTED ? { transparent: true } : {}),
+    backgroundMaterial: IS_WINDOWS && GLASS_SUPPORTED ? backgroundMaterialFor(translucencyState) : undefined,
     opacity: windowOpacity(),
     ...windowBackingOptions(translucencyState, getWindowBackgroundColor())
   }
@@ -14085,11 +14107,12 @@ app.on('before-quit', () => {
 })
 
 ipcMain.on('hermes:translucency', (_event, payload) => {
-  const next = normalizeTranslucency(payload, IS_MAC)
+  const next = normalizeTranslucency(payload, GLASS_SUPPORTED)
   const previous = translucencyState
 
   if (
     next.intensity === previous.intensity &&
+    next.fade === previous.fade &&
     next.mode === previous.mode &&
     next.material === previous.material &&
     next.scope === previous.scope
diff --git a/apps/desktop/electron/preload.ts b/apps/desktop/electron/preload.ts
index 7e2e52a319..1296d08ff9 100644
--- a/apps/desktop/electron/preload.ts
+++ b/apps/desktop/electron/preload.ts
@@ -1,6 +1,11 @@
 import { contextBridge, ipcRenderer, webFrame, webUtils } from 'electron'
+import os from 'node:os'
+
+import { glassSupportedOn, translucencySupportedOn } from '../../shared/src/translucency'
 
 contextBridge.exposeInMainWorld('hermesDesktop', {
+  glassSupported: glassSupportedOn(process.platform, os.release()),
+  translucencySupported: translucencySupportedOn(process.platform),
   getConnection: profile => ipcRenderer.invoke('hermes:connection', profile),
   // Registry-scoped backend resolution: { connectionId, profile } → descriptor.
   getConnectionFor: payload => ipcRenderer.invoke('hermes:connection:for', payload),
diff --git a/apps/desktop/electron/translucency.test.ts b/apps/desktop/electron/translucency.test.ts
index 3db509f14b..44f90a2d12 100644
--- a/apps/desktop/electron/translucency.test.ts
+++ b/apps/desktop/electron/translucency.test.ts
@@ -11,6 +11,7 @@
 import { describe, expect, it } from 'vitest'
 
 import {
+  backgroundMaterialFor,
   clampIntensity,
   DEFAULT_GLASS_MATERIAL,
   DEFAULT_GLASS_SCOPE,
@@ -18,6 +19,9 @@ import {
   GLASS_SCOPES,
   glassActive,
   type GlassMaterial,
+  glassMaterialForPicker,
+  glassMaterialsFor,
+  glassSupportedOn,
   glassSurfaceKeep,
   normalizeMaterial,
   normalizeMode,
@@ -28,7 +32,10 @@ import {
   TRANSLUCENCY_MIN,
   TRANSLUCENCY_OPACITY_FLOOR,
   type TranslucencyState,
+  translucencySupportedOn,
   vibrancyFor,
+  WINDOWS_BACKGROUND_MATERIALS,
+  WINDOWS_GLASS_MIN_BUILD,
   windowBackingOptions,
   windowOpacityFor
 } from './translucency'
@@ -38,13 +45,15 @@ const legacyOpacity = (intensity: number) => 1 - (intensity / 100) * 0.7
 
 const clear = (intensity: number): TranslucencyState => ({
   intensity,
+  fade: 0,
   mode: 'clear',
   material: DEFAULT_GLASS_MATERIAL,
   scope: DEFAULT_GLASS_SCOPE
 })
 
-const glass = (intensity: number, material: GlassMaterial = DEFAULT_GLASS_MATERIAL): TranslucencyState => ({
+const glass = (intensity: number, material: GlassMaterial = DEFAULT_GLASS_MATERIAL, fade = 0): TranslucencyState => ({
   intensity,
+  fade,
   mode: 'glass',
   material,
   scope: DEFAULT_GLASS_SCOPE
@@ -78,7 +87,7 @@ describe('clampIntensity', () => {
 })
 
 describe('normalizeMode', () => {
-  it('accepts glass on macOS only — there is no vibrancy to ride elsewhere', () => {
+  it('accepts glass only on a platform that has a native material', () => {
     expect(normalizeMode('glass', true)).toBe('glass')
     expect(normalizeMode('glass', false)).toBe('clear')
   })
@@ -90,7 +99,7 @@ describe('normalizeMode', () => {
 
   // Glass is pre-selected so the better half of the feature is the one you
   // find, which is free because the intensity still starts at 0.
-  it('pre-selects glass on macOS when nothing is recorded', () => {
+  it('pre-selects glass when the platform supports it and nothing is recorded', () => {
     expect(normalizeMode(undefined, true)).toBe('glass')
     expect(normalizeMode('acrylic', true)).toBe('glass')
     expect(normalizeMode(42, true)).toBe('glass')
@@ -163,11 +172,23 @@ describe('windowOpacityFor', () => {
     expect(windowOpacityFor(clear(240))).toBe(windowOpacityFor(clear(TRANSLUCENCY_MAX)))
   })
 
-  it('never fades the native window in glass mode — the renderer paints that effect', () => {
+  // The tint is painted by the renderer, so the intensity lever must never
+  // reach setOpacity under glass — that separation is what keeps text sharp.
+  it('ignores the intensity lever entirely in glass mode', () => {
     expect(windowOpacityFor(glass(0))).toBe(1)
     expect(windowOpacityFor(glass(60))).toBe(1)
     expect(windowOpacityFor(glass(100))).toBe(1)
   })
+
+  it('fades a glass window only through its own lever, on the ramp clear uses', () => {
+    expect(windowOpacityFor(glass(60, DEFAULT_GLASS_MATERIAL, 0))).toBe(1)
+    expect(windowOpacityFor(glass(60, DEFAULT_GLASS_MATERIAL, 40))).toBe(windowOpacityFor(clear(40)))
+    expect(windowOpacityFor(glass(0, DEFAULT_GLASS_MATERIAL, 100))).toBe(windowOpacityFor(clear(100)))
+  })
+
+  it('leaves fade inert under clear, where the intensity lever already is the opacity', () => {
+    expect(windowOpacityFor({ ...clear(40), fade: 100 })).toBe(windowOpacityFor(clear(40)))
+  })
 })
 
 describe('glassSurfaceKeep', () => {
@@ -224,10 +245,125 @@ describe('vibrancyFor', () => {
   })
 })
 
+describe('glassSupportedOn', () => {
+  it('is on for macOS regardless of kernel version', () => {
+    expect(glassSupportedOn('darwin')).toBe(true)
+    expect(glassSupportedOn('darwin', '24.6.0')).toBe(true)
+  })
+
+  it('is on for Windows 11 22H2 and newer, off for everything older', () => {
+    expect(glassSupportedOn('win32', `10.0.${WINDOWS_GLASS_MIN_BUILD}`)).toBe(true)
+    expect(glassSupportedOn('win32', `10.0.${WINDOWS_GLASS_MIN_BUILD}.1`)).toBe(true)
+    expect(glassSupportedOn('win32', `10.0.${WINDOWS_GLASS_MIN_BUILD - 1}`)).toBe(false)
+    expect(glassSupportedOn('win32', '10.0.19045')).toBe(false)
+    expect(glassSupportedOn('win32', '10.0')).toBe(false)
+    expect(glassSupportedOn('win32', '')).toBe(false)
+  })
+
+  it('is off on Linux — Electron has no first-party desktop material there', () => {
+    expect(glassSupportedOn('linux', '6.8.0')).toBe(false)
+  })
+})
+
+describe('backgroundMaterialFor', () => {
+  it('is none while glass is off so DWM does not keep drawing under the backing', () => {
+    expect(backgroundMaterialFor(glass(0, 'header'))).toBe('none')
+    expect(backgroundMaterialFor(clear(60))).toBe('none')
+  })
+
+  it('maps the sheer → heavy frost ladder onto acrylic / tabbed / mica', () => {
+    expect(backgroundMaterialFor(glass(60, 'under-window'))).toBe('acrylic')
+    expect(backgroundMaterialFor(glass(60, 'popover'))).toBe('tabbed')
+    expect(backgroundMaterialFor(glass(60, 'titlebar'))).toBe('mica')
+  })
+
+  // Windows 11 has three system materials for four rungs, so the two heaviest
+  // land on mica. The mapping stays total — a saved 'header' still resolves —
+  // and the picker drops the duplicate instead (see glassMaterialsFor).
+  it('collapses Glare onto mica with Bright', () => {
+    expect(backgroundMaterialFor(glass(60, 'header'))).toBe('mica')
+    expect(backgroundMaterialFor(glass(60, 'header'))).toBe(backgroundMaterialFor(glass(60, 'titlebar')))
+  })
+
+  it('resolves every shipped rung to a real system material', () => {
+    for (const material of GLASS_MATERIALS) {
+      expect(WINDOWS_BACKGROUND_MATERIALS, material).toContain(backgroundMaterialFor(glass(60, material)))
+    }
+  })
+})
+
+describe('translucencySupportedOn', () => {
+  it('covers the two platforms where setOpacity or a native material exists', () => {
+    expect(translucencySupportedOn('darwin')).toBe(true)
+    expect(translucencySupportedOn('win32')).toBe(true)
+  })
+
+  // Electron documents setOpacity as doing nothing on Linux, and there is no
+  // material either — so the setting has no working half to offer there.
+  it('is off on Linux, where neither mode does anything', () => {
+    expect(translucencySupportedOn('linux')).toBe(false)
+    expect(translucencySupportedOn('freebsd')).toBe(false)
+  })
+
+  // Win10 loses glass but keeps clear, so the row must survive there.
+  it('stays on for a Windows build too old for glass', () => {
+    const oldWindows = `10.0.${WINDOWS_GLASS_MIN_BUILD - 1}`
+
+    expect(glassSupportedOn('win32', oldWindows)).toBe(false)
+    expect(translucencySupportedOn('win32')).toBe(true)
+  })
+})
+
+describe('the frost rungs a platform offers', () => {
+  it('offers the whole ladder on macOS', () => {
+    expect(glassMaterialsFor(false)).toEqual(GLASS_MATERIALS)
+  })
+
+  // The census rule, now enforced on Windows too: no two options in the picker
+  // may composite to the same thing. Bright and Glare are both mica.
+  it('never offers two rungs that render the same Windows backdrop', () => {
+    const backdrops = glassMaterialsFor(true).map(material => backgroundMaterialFor(glass(60, material)))
+
+    expect(new Set(backdrops).size).toBe(backdrops.length)
+    expect(glassMaterialsFor(true).length).toBeLessThan(GLASS_MATERIALS.length)
+  })
+
+  it('keeps every distinct Windows backdrop reachable from the picker', () => {
+    const backdrops = new Set(glassMaterialsFor(true).map(material => backgroundMaterialFor(glass(60, material))))
+    const reachable = new Set(GLASS_MATERIALS.map(material => backgroundMaterialFor(glass(60, material))))
+
+    expect(backdrops).toEqual(reachable)
+  })
+
+  // Settings synced from a Mac carry a rung Windows has no button for. The
+  // picker highlights the button that renders the same backdrop rather than
+  // showing nothing selected — and does NOT rewrite what the Mac saved.
+  it('folds a dropped rung onto the button that looks the same', () => {
+    expect(glassMaterialForPicker('header', true)).toBe('titlebar')
+    expect(glassMaterialsFor(true)).toContain(glassMaterialForPicker('header', true))
+    expect(backgroundMaterialFor(glass(60, glassMaterialForPicker('header', true)))).toBe(
+      backgroundMaterialFor(glass(60, 'header'))
+    )
+  })
+
+  it('leaves every rung alone on macOS and every offered rung alone on Windows', () => {
+    for (const material of GLASS_MATERIALS) {
+      expect(glassMaterialForPicker(material, false)).toBe(material)
+    }
+
+    for (const material of glassMaterialsFor(true)) {
+      expect(glassMaterialForPicker(material, true)).toBe(material)
+    }
+  })
+})
+
 describe('normalizeState', () => {
   it('parses a modern payload', () => {
-    expect(normalizeState({ intensity: 40, mode: 'glass', material: 'header', scope: 'sidebar' }, true)).toEqual({
+    expect(
+      normalizeState({ intensity: 40, fade: 15, mode: 'glass', material: 'header', scope: 'sidebar' }, true)
+    ).toEqual({
       intensity: 40,
+      fade: 15,
       mode: 'glass',
       material: 'header',
       scope: 'sidebar'
@@ -239,19 +375,28 @@ describe('normalizeState', () => {
   it('keeps a legacy intensity-only payload on clear', () => {
     expect(normalizeState({ intensity: 70 }, true)).toEqual({
       intensity: 70,
+      fade: 0,
       mode: 'clear',
       material: DEFAULT_GLASS_MATERIAL,
       scope: DEFAULT_GLASS_SCOPE
     })
   })
 
-  it('survives junk payloads', () => {
-    const base = { intensity: 0, material: DEFAULT_GLASS_MATERIAL, scope: DEFAULT_GLASS_SCOPE }
+  // Fade arrived after glass shipped, so a profile written by the older build
+  // has no key for it and must come back unfaded rather than undefined.
+  it('defaults a payload written before fade existed to no fade', () => {
+    expect(normalizeState({ intensity: 60, mode: 'glass' }, true).fade).toBe(0)
+  })
 
-    // A fresh macOS profile lands on glass at zero intensity: selected, but off.
+  it('survives junk payloads', () => {
+    const base = { intensity: 0, fade: 0, material: DEFAULT_GLASS_MATERIAL, scope: DEFAULT_GLASS_SCOPE }
+
+    // A fresh glass-capable profile lands on glass at zero intensity: selected, but off.
     expect(normalizeState(null, true)).toEqual({ ...base, mode: 'glass' })
     expect(normalizeState('nope', true)).toEqual({ ...base, mode: 'glass' })
-    expect(normalizeState({ intensity: 'x', material: 'nope', mode: 'glass', scope: 'nope' }, false)).toEqual({
+    expect(
+      normalizeState({ intensity: 'x', fade: 'x', material: 'nope', mode: 'glass', scope: 'nope' }, false)
+    ).toEqual({
       ...base,
       mode: 'clear'
     })
@@ -266,8 +411,8 @@ describe('glassActive', () => {
   })
 })
 
-// The default must be selected-but-off: a fresh macOS profile shows Glass in
-// the picker while the window itself is untouched until the lever moves.
+// The default must be selected-but-off: a fresh glass-capable profile shows
+// Glass in the picker while the window itself is untouched until the lever moves.
 describe('a fresh profile', () => {
   const fresh = normalizeState(null, true)
 
@@ -326,12 +471,22 @@ describe('what an update actually changes natively', () => {
     expect(nativeDiff(clear(40), clear(41))).toEqual({ backing: false, material: false, opacity: true })
   })
 
+  // The one glass drag that reaches main, and it costs what a clear drag costs.
+  it('is only the opacity while dragging fade under glass', () => {
+    expect(nativeDiff(glass(60, DEFAULT_GLASS_MATERIAL, 40), glass(60, DEFAULT_GLASS_MATERIAL, 41))).toEqual({
+      backing: false,
+      material: false,
+      opacity: true
+    })
+  })
+
   it('is the material alone when the frost level changes', () => {
     expect(nativeDiff(glass(60, 'under-window'), glass(60, 'header'))).toEqual({
       backing: false,
       material: true,
       opacity: false
     })
+    expect(backgroundMaterialFor(glass(60, 'under-window'))).not.toBe(backgroundMaterialFor(glass(60, 'header')))
   })
 
   // Crossing zero flips glass on/off, which is exactly when the backing has to
diff --git a/apps/desktop/electron/translucency.ts b/apps/desktop/electron/translucency.ts
index cb9b2f28bf..aefedc21f0 100644
--- a/apps/desktop/electron/translucency.ts
+++ b/apps/desktop/electron/translucency.ts
@@ -14,6 +14,7 @@
 import { glassActive, type TranslucencyState } from '../../shared/src/translucency'
 
 export {
+  backgroundMaterialFor,
   clampIntensity,
   DEFAULT_GLASS_MATERIAL,
   DEFAULT_GLASS_SCOPE,
@@ -21,6 +22,9 @@ export {
   GLASS_SCOPES,
   glassActive,
   type GlassMaterial,
+  glassMaterialForPicker,
+  glassMaterialsFor,
+  glassSupportedOn,
   glassSurfaceKeep,
   normalizeMaterial,
   normalizeMode,
@@ -31,7 +35,11 @@ export {
   TRANSLUCENCY_MIN,
   TRANSLUCENCY_OPACITY_FLOOR,
   type TranslucencyState,
+  translucencySupportedOn,
   vibrancyFor,
+  WINDOWS_BACKGROUND_MATERIALS,
+  WINDOWS_GLASS_MIN_BUILD,
+  type WindowsBackgroundMaterial,
   windowOpacityFor
 } from '../../shared/src/translucency'
 
diff --git a/apps/desktop/src/global.d.ts b/apps/desktop/src/global.d.ts
index db4eb8d15f..1bd046c80d 100644
--- a/apps/desktop/src/global.d.ts
+++ b/apps/desktop/src/global.d.ts
@@ -247,6 +247,10 @@ declare global {
       setActiveWork?: (payload: HermesActiveWork) => void
       setTitleBarTheme?: (payload: HermesTitleBarTheme) => void
       setNativeTheme?: (mode: 'dark' | 'light' | 'system') => void
+      /** Main-process fact: this OS can back glass with a native material. */
+      glassSupported?: boolean
+      /** Main-process fact: this OS can do any translucency at all (not Linux). */
+      translucencySupported?: boolean
       setTranslucency?: (payload: TranslucencyState) => void
       setKeepAwake?: (on: boolean) => void
       setDisableF12?: (blocked: boolean) => void
diff --git a/apps/desktop/src/i18n/ar.ts b/apps/desktop/src/i18n/ar.ts
index 2c0f27e653..43821a35d5 100644
--- a/apps/desktop/src/i18n/ar.ts
+++ b/apps/desktop/src/i18n/ar.ts
@@ -413,10 +413,12 @@ export const ar = defineLocale({
       reasoningCollapsedTitle: 'طي التفكير افتراضيًا',
       reasoningCollapsedDesc: 'أبقِ التفكير المتدفق متاحًا دون توسيعه حتى تفتحه.',
       translucencyTitle: 'شفافية النافذة',
-      translucencyDesc: 'إظهار سطح المكتب من خلال النافذة بالكامل. متاح على macOS وWindows فقط.',
-      translucencyGlassDesc: 'زجاج غير لامع: يظهر سطح المكتب كضبابية ناعمة بينما يبقى النص واضحًا. متاح على macOS فقط.',
+      translucencyDesc: 'إظهار سطح المكتب من خلال النافذة بالكامل، بما في ذلك النص.',
+      translucencyGlassDesc: 'زجاج غير لامع: يظهر سطح المكتب كضبابية ناعمة بينما يبقى النص واضحًا.',
       translucencyModeClear: 'شفاف',
       translucencyModeGlass: 'زجاج',
+      translucencyTintTitle: 'التلوين',
+      translucencyFadeTitle: 'التلاشي',
       translucencyFrostTitle: 'نوع الضبابية',
       translucencyFrost: {
         'under-window': 'عميق',
diff --git a/apps/desktop/src/i18n/en.ts b/apps/desktop/src/i18n/en.ts
index 091ae1b828..deda09136d 100644
--- a/apps/desktop/src/i18n/en.ts
+++ b/apps/desktop/src/i18n/en.ts
@@ -522,11 +522,12 @@ export const en: Translations = {
       terminalFontPreview: 'Glyph preview',
       terminalFontReset: 'Use default',
       translucencyTitle: 'Window Translucency',
-      translucencyDesc: 'See your desktop through the whole window. macOS and Windows only.',
-      translucencyGlassDesc:
-        'Matte glass: the desktop shows through as a smooth blur while text stays sharp. macOS only.',
+      translucencyDesc: 'See your desktop through the whole window, text and all.',
+      translucencyGlassDesc: 'Matte glass: the desktop shows through as a smooth blur while text stays sharp.',
       translucencyModeClear: 'Clear',
       translucencyModeGlass: 'Glass',
+      translucencyTintTitle: 'Tint',
+      translucencyFadeTitle: 'Fade',
       translucencyFrostTitle: 'Frost',
       translucencyFrost: {
         'under-window': 'Deep',
diff --git a/apps/desktop/src/i18n/ja.ts b/apps/desktop/src/i18n/ja.ts
index 5110bf27aa..b924693600 100644
--- a/apps/desktop/src/i18n/ja.ts
+++ b/apps/desktop/src/i18n/ja.ts
@@ -346,10 +346,12 @@ export const ja = defineLocale({
       terminalFontPreview: 'グリフのプレビュー',
       terminalFontReset: '既定値を使用',
       translucencyTitle: 'ウィンドウの透過',
-      translucencyDesc: 'ウィンドウ全体を透過させてデスクトップを表示します。macOS と Windows のみ。',
-      translucencyGlassDesc: 'マットガラス: デスクトップが滑らかなぼかしとして透け、テキストは鮮明なまま。macOS のみ。',
+      translucencyDesc: 'テキストも含めウィンドウ全体を透過させてデスクトップを表示します。',
+      translucencyGlassDesc: 'マットガラス: デスクトップが滑らかなぼかしとして透け、テキストは鮮明なまま。',
       translucencyModeClear: 'クリア',
       translucencyModeGlass: 'ガラス',
+      translucencyTintTitle: '色味',
+      translucencyFadeTitle: 'フェード',
       translucencyFrostTitle: 'くもりの質感',
       translucencyFrost: {
         'under-window': '深い',
diff --git a/apps/desktop/src/i18n/types.ts b/apps/desktop/src/i18n/types.ts
index 25ba1df58b..da2b71ce8b 100644
--- a/apps/desktop/src/i18n/types.ts
+++ b/apps/desktop/src/i18n/types.ts
@@ -424,6 +424,8 @@ export interface Translations {
       translucencyGlassDesc: string
       translucencyModeClear: string
       translucencyModeGlass: string
+      translucencyTintTitle: string
+      translucencyFadeTitle: string
       translucencyFrostTitle: string
       translucencyFrost: {
         'under-window': string
diff --git a/apps/desktop/src/i18n/zh-hant.ts b/apps/desktop/src/i18n/zh-hant.ts
index 54bb68ecc7..4a4716cb84 100644
--- a/apps/desktop/src/i18n/zh-hant.ts
+++ b/apps/desktop/src/i18n/zh-hant.ts
@@ -338,10 +338,12 @@ export const zhHant = defineLocale({
       terminalFontPreview: '字形預覽',
       terminalFontReset: '使用預設字型',
       translucencyTitle: '視窗透明',
-      translucencyDesc: '讓整個視窗透出桌面。僅支援 macOS 與 Windows。',
-      translucencyGlassDesc: '霧面玻璃：桌面以柔和模糊透出，文字保持清晰。僅支援 macOS。',
+      translucencyDesc: '讓整個視窗（包括文字）透出桌面。',
+      translucencyGlassDesc: '霧面玻璃：桌面以柔和模糊透出，文字保持清晰。',
       translucencyModeClear: '透明',
       translucencyModeGlass: '玻璃',
+      translucencyTintTitle: '色調',
+      translucencyFadeTitle: '淡出',
       translucencyFrostTitle: '磨砂質感',
       translucencyFrost: {
         'under-window': '深邃',
diff --git a/apps/desktop/src/i18n/zh.ts b/apps/desktop/src/i18n/zh.ts
index c78354f41e..a18da9779d 100644
--- a/apps/desktop/src/i18n/zh.ts
+++ b/apps/desktop/src/i18n/zh.ts
@@ -511,10 +511,12 @@ export const zh: Translations = {
       terminalFontPreview: '字形预览',
       terminalFontReset: '使用默认字体',
       translucencyTitle: '窗口透明',
-      translucencyDesc: '让整个窗口透出桌面。仅支持 macOS 和 Windows。',
-      translucencyGlassDesc: '磨砂玻璃：桌面以柔和模糊透出，文字保持清晰。仅支持 macOS。',
+      translucencyDesc: '让整个窗口（包括文字）透出桌面。',
+      translucencyGlassDesc: '磨砂玻璃：桌面以柔和模糊透出，文字保持清晰。',
       translucencyModeClear: '透明',
       translucencyModeGlass: '玻璃',
+      translucencyTintTitle: '色调',
+      translucencyFadeTitle: '淡出',
       translucencyFrostTitle: '磨砂质感',
       translucencyFrost: {
         'under-window': '深邃',
diff --git a/apps/desktop/src/lib/platform.ts b/apps/desktop/src/lib/platform.ts
index 011d3afc4e..6bcb7358ed 100644
--- a/apps/desktop/src/lib/platform.ts
+++ b/apps/desktop/src/lib/platform.ts
@@ -2,9 +2,18 @@
  * Platform detection for the renderer.
  *
  * The renderer has no `process.platform`, and several surfaces need to know
- * whether they're on a Mac — keybind glyphs, terminal shortcuts, and the
- * macOS-only vibrancy features. One definition so they can't disagree.
+ * which OS they're on — keybind glyphs, terminal shortcuts, and glass. One
+ * definition so they can't disagree.
+ *
+ * Win10 vs Win11 is not visible here (both report NT 10.0). The real glass
+ * gate is `hermesDesktop.glassSupported`, which main/preload compute from
+ * `os.release()`.
  */
 
 export const isMacPlatform = (): boolean =>
   typeof navigator !== 'undefined' && /mac/i.test(navigator.platform || navigator.userAgent || '')
+
+// Not `/win/i` — that matches the substring inside `darwin`, which is jsdom's
+// default userAgent. Win32 / Windows NT are the real tokens.
+export const isWindowsPlatform = (): boolean =>
+  typeof navigator !== 'undefined' && /win32|windows/i.test(navigator.platform || navigator.userAgent || '')
diff --git a/apps/desktop/src/store/translucency.test.ts b/apps/desktop/src/store/translucency.test.ts
index 933e738d7c..538db4faab 100644
--- a/apps/desktop/src/store/translucency.test.ts
+++ b/apps/desktop/src/store/translucency.test.ts
@@ -59,6 +59,7 @@ describe('window translucency lever', () => {
   it('starts off, with glass pre-selected on macOS', () => {
     expect(initialTranslucency).toEqual({
       intensity: TRANSLUCENCY_MIN,
+      fade: TRANSLUCENCY_MIN,
       mode: GLASS_SUPPORTED ? 'glass' : 'clear',
       material: DEFAULT_GLASS_MATERIAL,
       scope: DEFAULT_GLASS_SCOPE
@@ -122,6 +123,7 @@ describe('window translucency lever', () => {
         op: 'write',
         value: JSON.stringify({
           intensity: 23,
+          fade: 0,
           mode: 'clear',
           material: DEFAULT_GLASS_MATERIAL,
           scope: DEFAULT_GLASS_SCOPE
@@ -150,6 +152,7 @@ describe('window translucency lever', () => {
       expect(calls).toHaveLength(5)
       expect(calls.at(-1)).toEqual({
         intensity: 40,
+        fade: 0,
         mode: 'clear',
         material: DEFAULT_GLASS_MATERIAL,
         scope: DEFAULT_GLASS_SCOPE
@@ -191,7 +194,7 @@ describe('glass mode', () => {
     setTranslucency(TRANSLUCENCY_MIN)
   })
 
-  it('rejects glass off macOS and applies it on macOS', () => {
+    it('rejects glass when the platform cannot back it', () => {
     setTranslucency(50)
     setTranslucencyMode('glass')
 
diff --git a/apps/desktop/src/store/translucency.ts b/apps/desktop/src/store/translucency.ts
index 337c358321..b37bc25989 100644
--- a/apps/desktop/src/store/translucency.ts
+++ b/apps/desktop/src/store/translucency.ts
@@ -7,7 +7,7 @@
  *
  * The renderer owns the value and mirrors it to the main process over IPC.
  * Glass additionally needs page-level work, which lives here: the field
- * surfaces have to get out of the way for the vibrancy material underneath the
+ * surfaces have to get out of the way for the platform material underneath the
  * web contents to read (see the `[data-hermes-glass]` block in styles.css).
  */
 
@@ -16,6 +16,8 @@ import {
   GLASS_MATERIALS,
   GLASS_SCOPES,
   type GlassMaterial,
+  glassMaterialForPicker,
+  glassMaterialsFor,
   type GlassScope,
   glassSurfaceKeep,
   normalizeMaterial,
@@ -29,13 +31,43 @@ import {
 } from '@hermes/shared/translucency'
 import { atom } from 'nanostores'
 
-import { isMacPlatform } from '@/lib/platform'
+import { isMacPlatform, isWindowsPlatform } from '@/lib/platform'
 import { readJson, writeJson } from '@/lib/storage'
 
-export { GLASS_MATERIALS, GLASS_SCOPES, TRANSLUCENCY_MAX, TRANSLUCENCY_MIN, TRANSLUCENCY_STEP }
+export {
+  GLASS_MATERIALS,
+  GLASS_SCOPES,
+  glassMaterialForPicker,
+  glassMaterialsFor,
+  TRANSLUCENCY_MAX,
+  TRANSLUCENCY_MIN,
+  TRANSLUCENCY_STEP
+}
 
-/** Glass rides on the macOS vibrancy material; other platforms only have Clear. */
-export const GLASS_SUPPORTED = isMacPlatform()
+/**
+ * Glass needs a native window material. Electron is authoritative (preload
+ * sets `hermesDesktop.glassSupported` from `os.release()` so Win10 cannot
+ * sneak through). Tests and non-Electron shells fall back to a UA sniff —
+ * Mac or Windows — which is why this file pins `navigator.platform` before
+ * import.
+ */
+export const GLASS_SUPPORTED =
+  typeof window !== 'undefined' && typeof window.hermesDesktop?.glassSupported === 'boolean'
+    ? window.hermesDesktop.glassSupported
+    : isMacPlatform() || isWindowsPlatform()
+
+/**
+ * Whether the setting is worth showing at all. Linux has neither half —
+ * `setOpacity` is a documented no-op and there is no native material — so
+ * Settings hides the row rather than offering a lever that does nothing.
+ */
+export const TRANSLUCENCY_SUPPORTED =
+  typeof window !== 'undefined' && typeof window.hermesDesktop?.translucencySupported === 'boolean'
+    ? window.hermesDesktop.translucencySupported
+    : isMacPlatform() || isWindowsPlatform()
+
+/** Windows collapses the frost ladder — see `glassMaterialsFor`. */
+export const GLASS_IS_WINDOWS = GLASS_SUPPORTED && !isMacPlatform()
 
 const KEY = 'hermes.desktop.translucency.v1'
 
@@ -57,6 +89,10 @@ export function setTranslucency(intensity: number): void {
   $translucency.set({ ...$translucency.get(), intensity: clampIntensity(intensity) })
 }
 
+export function setTranslucencyFade(fade: number): void {
+  $translucency.set({ ...$translucency.get(), fade: clampIntensity(fade) })
+}
+
 export function setTranslucencyMode(mode: TranslucencyMode): void {
   $translucency.set({ ...$translucency.get(), mode: mode === 'glass' && GLASS_SUPPORTED ? 'glass' : 'clear' })
 }
@@ -300,6 +336,7 @@ if (typeof window !== 'undefined') {
 
     if (
       next.intensity !== current.intensity ||
+      next.fade !== current.fade ||
       next.mode !== current.mode ||
       next.material !== current.material ||
       next.scope !== current.scope
diff --git a/apps/desktop/src/styles.css b/apps/desktop/src/styles.css
index 24364e00e2..3816915bf8 100644
--- a/apps/desktop/src/styles.css
+++ b/apps/desktop/src/styles.css
@@ -551,23 +551,25 @@
   }
 
   /* ── Window glass (Settings → Appearance → Window Translucency: Glass) ──
-     Set on <html> by store/translucency.ts; macOS chat windows only. Every
-     chat window already carries an NSVisualEffectView (`vibrancy: 'sidebar'`
-     in electron/main.ts) that WindowServer composites BELOW the web contents;
-     the page normally buries it under fully opaque surfaces.
+     Set on <html> by store/translucency.ts; chat windows on a glass-capable
+     OS (macOS vibrancy, Windows 11 DWM acrylic/mica). The native material
+     composites BELOW the web contents; the page normally buries it under
+     fully opaque surfaces.
 
      ONE PAINTER: <body> paints the glass tint exactly once, at
-     `--translucency-glass-keep` (set inline from the intensity slider, floor
-     30%), and the field tokens (chat / sidebar / editor surface) go fully
-     transparent. The field surfaces NEST — body > pane container > chat
-     section > transcript wrapper all wear these tokens — so thinning the
-     tokens themselves stacks the tint once per layer and a session pane ends
-     up near-opaque (~0.93 at 60%) while the landing page, with fewer layers,
-     reads far clearer. With a single painter the field alpha is the same
-     number on every route. Raised content (cards, popovers, bubbles, the
-     composer) keeps its own opaque fills over full-contrast text; regions
-     still read distinct through their borders and the material itself.
-     Unlike Clear, nothing on the page fades.
+     `--translucency-glass-keep` (set inline from the Tint slider, linear to
+     zero — the top of the lever is bare material), and the field tokens
+     (chat / sidebar / editor surface) go fully transparent. The field
+     surfaces NEST — body > pane container > chat section > transcript
+     wrapper all wear these tokens — so thinning the tokens themselves stacks
+     the tint once per layer and a session pane ends up near-opaque (~0.93 at
+     60%) while the landing page, with fewer layers, reads far clearer. With a
+     single painter the field alpha is the same number on every route. Raised
+     content (cards, popovers, bubbles, the composer) keeps its own opaque
+     fills over full-contrast text; regions still read distinct through their
+     borders and the material itself. Unlike Clear, nothing on the page fades
+     — the separate Fade lever does that natively, at the window level, and
+     defaults to off.
 
      The boot script in index.html pins an opaque inline background on <html>
      before first paint; it has to go transparent here or it sits behind the
diff --git a/apps/shared/src/index.ts b/apps/shared/src/index.ts
index b4f6299ca2..7f96081096 100644
--- a/apps/shared/src/index.ts
+++ b/apps/shared/src/index.ts
@@ -63,6 +63,7 @@ export {
   type SkinColorToken
 } from './skin'
 export {
+  backgroundMaterialFor,
   clampIntensity,
   DEFAULT_GLASS_MATERIAL,
   DEFAULT_GLASS_SCOPE,
@@ -71,6 +72,9 @@ export {
   glassActive,
   type GlassMaterial,
   type GlassScope,
+  glassMaterialForPicker,
+  glassMaterialsFor,
+  glassSupportedOn,
   glassSurfaceKeep,
   normalizeMaterial,
   normalizeMode,
@@ -83,7 +87,11 @@ export {
   TRANSLUCENCY_STEP,
   type TranslucencyMode,
   type TranslucencyState,
+  translucencySupportedOn,
   vibrancyFor,
+  WINDOWS_BACKGROUND_MATERIALS,
+  WINDOWS_GLASS_MIN_BUILD,
+  type WindowsBackgroundMaterial,
   windowOpacityFor
 } from './translucency'
 export {
diff --git a/apps/shared/src/translucency.ts b/apps/shared/src/translucency.ts
index c30306a837..da32fd102f 100644
--- a/apps/shared/src/translucency.ts
+++ b/apps/shared/src/translucency.ts
@@ -8,10 +8,11 @@
  * - 'clear' — the main process maps the lever to native window opacity
  *   (`setOpacity`), so the whole window fades, text included. macOS + Windows;
  *   `setOpacity` is a no-op on Linux.
- * - 'glass' — macOS only. The window stays fully opaque at the native level and
- *   the renderer thins its page surfaces instead, letting the vibrancy material
- *   every chat window already carries read as a matte blur while text keeps
- *   full contrast.
+ * - 'glass' — the window stays fully opaque at the native level and the
+ *   renderer thins its page surfaces instead, letting a platform material
+ *   read as a matte blur while text keeps full contrast. macOS rides
+ *   `setVibrancy`; Windows 11 (22H2+) rides `setBackgroundMaterial`. Linux
+ *   has no first-party desktop material, so glass is not offered there.
  *
  * The renderer owns the value and mirrors it to main over IPC; main persists it
  * so a cold launch can apply it at window creation, before the renderer reports
@@ -53,8 +54,59 @@ export type GlassScope = (typeof GLASS_SCOPES)[number]
 
 export const DEFAULT_GLASS_SCOPE: GlassScope = 'window'
 
+/**
+ * Electron `setBackgroundMaterial` values. `'auto'` is deliberately absent —
+ * it lets DWM pick, which would silently erase the frost choice.
+ */
+export const WINDOWS_BACKGROUND_MATERIALS = ['acrylic', 'tabbed', 'mica', 'none'] as const
+
+export type WindowsBackgroundMaterial = (typeof WINDOWS_BACKGROUND_MATERIALS)[number]
+
+/**
+ * Frost (sheer → heavy) → Windows 11 system backdrop. Acrylic is the live-blur
+ * transient material, closest to macOS under-window vibrancy; tabbed and mica
+ * sample the wallpaper and read more opaque.
+ *
+ * Three backdrops for four rungs, so the two heaviest both land on mica. The
+ * mapping stays total — a frost saved on a Mac still resolves — and the PICKER
+ * drops the duplicate instead (see `glassMaterialsFor`).
+ */
+const WINDOWS_MATERIAL_BY_FROST: Record<GlassMaterial, Exclude<WindowsBackgroundMaterial, 'none'>> = {
+  'under-window': 'acrylic',
+  popover: 'tabbed',
+  titlebar: 'mica',
+  header: 'mica'
+}
+
+/**
+ * The frost rungs Windows can render as DISTINCT looks: the first rung for each
+ * backdrop. Shipping two options that composite identically is the mistake the
+ * macOS census already corrected once (sidebar/hud); deriving the list from the
+ * mapping means a change there can never reintroduce a duplicate.
+ */
+const WINDOWS_GLASS_MATERIALS: readonly GlassMaterial[] = GLASS_MATERIALS.filter(
+  (material, index) =>
+    GLASS_MATERIALS.findIndex(rung => WINDOWS_MATERIAL_BY_FROST[rung] === WINDOWS_MATERIAL_BY_FROST[material]) === index
+)
+
+/**
+ * Windows 11 22H2 (build 22621) is the floor Electron documents for
+ * `setBackgroundMaterial`. Windows 11 still reports kernel 10.0; the build
+ * number is the discriminator. Fail closed on a missing/unparseable release.
+ *
+ * @see https://www.electronjs.org/docs/latest/api/browser-window#winsetbackgroundmaterialmaterial-windows
+ */
+export const WINDOWS_GLASS_MIN_BUILD = 22621
+
 export interface TranslucencyState {
   intensity: number
+  /**
+   * Glass only: native window opacity, on the same ramp Clear's lever uses.
+   * Defaults to 0 (no fade) because fading a glass window fades its text too —
+   * the very thing Glass exists to avoid. It is offered as a deliberate second
+   * lever, never as part of the tint.
+   */
+  fade: number
   mode: TranslucencyMode
   material: GlassMaterial
   scope: GlassScope
@@ -84,20 +136,49 @@ export function clampIntensity(value: unknown): number {
 }
 
 /**
- * Glass rides on the macOS vibrancy material, so it is macOS-only and 'clear'
- * is the fallback everywhere else.
- *
- * With no mode recorded, macOS gets glass — it is the better-looking half of
- * the feature and the one worth finding, and pre-selecting it costs a fresh
- * profile nothing because the intensity still starts at 0 (the whole feature
- * is off until the user raises the lever). `legacyIntensity` is the escape
- * hatch: a profile that already carries a NON-ZERO intensity but no mode
- * predates this setting and has been rendering as clear all along, so it keeps
- * rendering as clear. Flipping a window someone already tuned is the one thing
- * a default must not do.
+ * Whether this OS can do ANY translucency. Clear rides `setOpacity`, which
+ * Electron documents as doing nothing on Linux, and glass needs a native
+ * material Linux does not have — so the whole setting is dead there and the
+ * row should not be shown at all.
  */
-export function normalizeMode(value: unknown, isMac: boolean, legacyIntensity = 0): TranslucencyMode {
-  if (!isMac) {
+export function translucencySupportedOn(platform: string): boolean {
+  return platform === 'darwin' || platform === 'win32'
+}
+
+/**
+ * Whether this OS can back glass with a first-party Electron material.
+ * macOS: `setVibrancy`. Windows 11 22H2+: `setBackgroundMaterial`. Linux and
+ * older Windows: no.
+ */
+export function glassSupportedOn(platform: string, release = ''): boolean {
+  if (platform === 'darwin') {
+    return true
+  }
+
+  if (platform !== 'win32') {
+    return false
+  }
+
+  const build = Number.parseInt(release.split('.')[2] ?? '', 10)
+
+  return Number.isFinite(build) && build >= WINDOWS_GLASS_MIN_BUILD
+}
+
+/**
+ * Glass needs a native window material, so unsupported platforms stay on
+ * 'clear'.
+ *
+ * With no mode recorded, a glass-capable OS gets glass — it is the
+ * better-looking half of the feature and the one worth finding, and
+ * pre-selecting it costs a fresh profile nothing because the intensity still
+ * starts at 0 (the whole feature is off until the user raises the lever).
+ * `legacyIntensity` is the escape hatch: a profile that already carries a
+ * NON-ZERO intensity but no mode predates this setting and has been rendering
+ * as clear all along, so it keeps rendering as clear. Flipping a window
+ * someone already tuned is the one thing a default must not do.
+ */
+export function normalizeMode(value: unknown, glassSupported: boolean, legacyIntensity = 0): TranslucencyMode {
+  if (!glassSupported) {
     return 'clear'
   }
 
@@ -119,32 +200,38 @@ export function normalizeScope(value: unknown): GlassScope {
 }
 
 /** Parse a persisted translucency.json / IPC payload into a safe state. */
-export function normalizeState(payload: unknown, isMac: boolean): TranslucencyState {
+export function normalizeState(payload: unknown, glassSupported: boolean): TranslucencyState {
   const record = payload && typeof payload === 'object' ? (payload as Record<string, unknown>) : {}
   const intensity = clampIntensity(record.intensity)
 
   return {
     intensity,
-    mode: normalizeMode(record.mode, isMac, intensity),
+    fade: clampIntensity(record.fade),
+    mode: normalizeMode(record.mode, glassSupported, intensity),
     material: normalizeMaterial(record.material),
     scope: normalizeScope(record.scope)
   }
 }
 
-/**
- * Native window opacity for a state. Glass never fades the native window — its
- * see-through effect is painted by the renderer over the vibrancy material.
- */
-export function windowOpacityFor({ intensity, mode }: TranslucencyState): number {
-  if (mode === 'glass') {
-    return 1
-  }
-
-  const ratio = clampIntensity(intensity) / TRANSLUCENCY_MAX
+/** Lever percent → native window opacity, floored so it stays usable. */
+function opacityRamp(lever: number): number {
+  const ratio = clampIntensity(lever) / TRANSLUCENCY_MAX
 
   return 1 - (1 - TRANSLUCENCY_OPACITY_FLOOR) * Math.pow(ratio, TRANSLUCENCY_CURVE)
 }
 
+/**
+ * Native window opacity for a state.
+ *
+ * Under Clear the lever IS the opacity. Under Glass the lever paints the tint
+ * and only the separate `fade` reaches the window, so a glass window stays at
+ * 1 until the user opts into fading it — which is what keeps a tint drag from
+ * touching anything native.
+ */
+export function windowOpacityFor({ intensity, fade, mode }: TranslucencyState): number {
+  return opacityRamp(mode === 'glass' ? fade : intensity)
+}
+
 /**
  * Whether glass is visually active. Both processes branch on this: main to
  * decide a window's backing, the renderer to decide whether to thin surfaces.
@@ -155,7 +242,7 @@ export function glassActive({ intensity, mode }: TranslucencyState): boolean {
 
 /**
  * Percent of the surface tint the renderer KEEPS at a given intensity. Linear
- * to zero: at 100 the tint is fully gone — bare vibrancy glass — so the slider
+ * to zero: at 100 the tint is fully gone — bare platform glass — so the slider
  * spans the whole range from opaque theme to untinted blur. Text and cards
  * keep their own opaque tokens for contrast; only the field surfaces thin.
  */
@@ -172,3 +259,34 @@ export function glassSurfaceKeep(intensity: number): number {
 export function vibrancyFor(state: TranslucencyState): GlassMaterial | 'sidebar' {
   return glassActive(state) ? state.material : 'sidebar'
 }
+
+/**
+ * The Windows 11 system backdrop a chat window should carry. 'none' while
+ * glass is off so DWM does not keep drawing mica/acrylic under the opaque
+ * themed backing.
+ */
+export function backgroundMaterialFor(state: TranslucencyState): WindowsBackgroundMaterial {
+  return glassActive(state) ? WINDOWS_MATERIAL_BY_FROST[state.material] : 'none'
+}
+
+/** The frost rungs to offer on this platform. */
+export function glassMaterialsFor(isWindows: boolean): readonly GlassMaterial[] {
+  return isWindows ? WINDOWS_GLASS_MATERIALS : GLASS_MATERIALS
+}
+
+/**
+ * The rung the picker highlights. A frost with no rung of its own here — a
+ * Mac's 'header' read on Windows — folds onto the rung that renders the same
+ * backdrop, so the picker shows a truthful selection without rewriting the
+ * value the user saved on their other machine.
+ */
+export function glassMaterialForPicker(material: GlassMaterial, isWindows: boolean): GlassMaterial {
+  if (!isWindows) {
+    return material
+  }
+
+  return (
+    WINDOWS_GLASS_MATERIALS.find(rung => WINDOWS_MATERIAL_BY_FROST[rung] === WINDOWS_MATERIAL_BY_FROST[material]) ??
+    DEFAULT_GLASS_MATERIAL
+  )
+}

From 759d320eeb62f178fdba2f37c102143f090c5594 Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 19 Aug 2026 01:32:26 -0500
Subject: [PATCH 09/48] fix(desktop): keep recents when ALL-profiles scope has
 one profile
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Grouping → Profile persists ALL even with a single profile. Recents
filtered that pool against the __all__ sentinel and emptied the list.
Cron and messaging already used filterSessionsByProfileScope; recents
now does too.

Co-authored-by: andyst-dev <150129844+andyst-dev@users.noreply.github.com>
---
 apps/desktop/src/app/chat/sidebar/index.tsx           | 11 +++++++----
 .../src/app/chat/sidebar/profile-scope.test.ts        |  8 ++++++++
 apps/desktop/src/app/chat/sidebar/profile-scope.ts    |  8 +++++++-
 3 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/apps/desktop/src/app/chat/sidebar/index.tsx b/apps/desktop/src/app/chat/sidebar/index.tsx
index 6930c5343d..d36903a5ee 100644
--- a/apps/desktop/src/app/chat/sidebar/index.tsx
+++ b/apps/desktop/src/app/chat/sidebar/index.tsx
@@ -467,16 +467,19 @@ export function ChatSidebar({
 
   // Profile scope = the "workspace switcher" context. Concrete scope shows only
   // that profile's sessions (clean rows, no per-row tags); ALL fans every
-  // profile in, grouped by profile below. Single-profile users land here with
-  // scope === their only profile, so nothing is filtered out.
+  // profile in. Grouped rendering stays gated on `showAllProfiles` (multi-profile
+  // + ALL) so a single-profile user is never stranded in a grouped view with no
+  // rail — but the *data* still has to fan in when the persisted scope is ALL
+  // (Grouping → Profile). Filtering that pool against the `__all__` sentinel
+  // matches nothing and empties recents + pins.
   // Archived rows are excluded from the sessions query, so Archived is a view of
   // its own set rather than a filter over this one — a flat list of archived
   // rows, no project tree, no date or status dividers.
   const scopedSessions = useMemo(() => {
     const pool = showArchived ? archivedSessions : sessions
 
-    return showAllProfiles ? pool : pool.filter(s => normalizeProfileKey(s.profile) === profileScope)
-  }, [sessions, archivedSessions, showArchived, showAllProfiles, profileScope])
+    return filterSessionsByProfileScope(pool, profileScope)
+  }, [sessions, archivedSessions, showArchived, profileScope])
 
   // One predicate for the status/project filters, so the flat list and the
   // project lanes narrow by the same rule. A project lane holds rows the loaded
diff --git a/apps/desktop/src/app/chat/sidebar/profile-scope.test.ts b/apps/desktop/src/app/chat/sidebar/profile-scope.test.ts
index 14e73edb61..68585af986 100644
--- a/apps/desktop/src/app/chat/sidebar/profile-scope.test.ts
+++ b/apps/desktop/src/app/chat/sidebar/profile-scope.test.ts
@@ -27,4 +27,12 @@ describe('filterSessionsByProfileScope', () => {
 
     expect(filterSessionsByProfileScope(rows, ALL_PROFILES)).toBe(rows)
   })
+
+  it('does not empty ALL scope when every row is one profile', () => {
+    // Grouping → Profile persists ALL even with one profile. Filtering
+    // against the `__all__` sentinel would empty recents and pins.
+    const rows = [row('a', 'default'), row('b', 'default'), row('c', 'default')]
+
+    expect(filterSessionsByProfileScope(rows, ALL_PROFILES)).toBe(rows)
+  })
 })
diff --git a/apps/desktop/src/app/chat/sidebar/profile-scope.ts b/apps/desktop/src/app/chat/sidebar/profile-scope.ts
index 45686d8252..d585b14c9b 100644
--- a/apps/desktop/src/app/chat/sidebar/profile-scope.ts
+++ b/apps/desktop/src/app/chat/sidebar/profile-scope.ts
@@ -1,7 +1,13 @@
 import { ALL_PROFILES, normalizeProfileKey } from '@/store/profile'
 import type { SessionInfo } from '@/types/hermes'
 
-/** Return the sessions visible in one sidebar profile scope, or the original unified list for All profiles. */
+/**
+ * Sessions visible in one sidebar profile scope.
+ *
+ * ALL (`__all__`) returns the caller's list unchanged — including the
+ * single-profile case, where Grouping → Profile persists that sentinel
+ * while grouped rendering stays off. Never filter against `__all__`.
+ */
 export function filterSessionsByProfileScope(sessions: SessionInfo[], profileScope: string): SessionInfo[] {
   if (profileScope === ALL_PROFILES) {
     return sessions

From 0553a06728fedc59ddd67a2f83be5fb7a0f7269d Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 19 Aug 2026 03:34:49 -0500
Subject: [PATCH 10/48] refactor(desktop): split gateway-event.ts into
 per-family handler modules
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The monolithic if/else-if dispatcher becomes nine modules by event
family. The routing preamble runs once, then each handler consumes its
own types and reports whether it did, so dispatch stops at the first
taker. Families are mutually exclusive by type, so ordering between them
is inert; ordering within a family is unchanged.

Restores two things the extraction dropped against a moving base: the
layout.apply handler, and the multi-question clarify.request path. A
batch clarify was consumed and never parked, so the agent blocked on
clarify.respond with no card rendered — the existing tests passed
because they assert "exactly one clarify card", which is also true when
the request is dropped and only the tool.start row exists.
---
 .../hooks/use-message-stream/gateway-event.ts | 1717 -----------------
 .../gateway-event/desktop-bridge.ts           |  217 +++
 .../use-message-stream/gateway-event/index.ts |  264 +++
 .../gateway-event/input-requests.ts           |  280 +++
 .../gateway-event/lifecycle.ts                |  102 +
 .../gateway-event/message-stream.ts           |  392 ++++
 .../gateway-event/session-info.ts             |  385 ++++
 .../gateway-event/status.ts                   |  177 ++
 .../use-message-stream/gateway-event/tools.ts |  141 ++
 .../use-message-stream/gateway-event/types.ts |   72 +
 10 files changed, 2030 insertions(+), 1717 deletions(-)
 delete mode 100644 apps/desktop/src/app/session/hooks/use-message-stream/gateway-event.ts
 create mode 100644 apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/desktop-bridge.ts
 create mode 100644 apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/index.ts
 create mode 100644 apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/input-requests.ts
 create mode 100644 apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/lifecycle.ts
 create mode 100644 apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/message-stream.ts
 create mode 100644 apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/session-info.ts
 create mode 100644 apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/status.ts
 create mode 100644 apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/tools.ts
 create mode 100644 apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/types.ts

diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event.ts b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event.ts
deleted file mode 100644
index 8a247c8263..0000000000
--- a/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event.ts
+++ /dev/null
@@ -1,1717 +0,0 @@
-import type { BillingBlock } from '@hermes/shared'
-import { registryBackendScopeKey } from '@hermes/shared'
-import type { HermesSkin } from '@hermes/shared/skin'
-import type { QueryClient } from '@tanstack/react-query'
-import { type MutableRefObject, useCallback, useEffect, useRef } from 'react'
-
-import { readActivePreview } from '@/app/chat/right-rail/preview-reader'
-import { writeAgentTerminalChunk } from '@/app/right-sidebar/terminal/agent-terminal-stream'
-import { readActiveTerminal } from '@/app/right-sidebar/terminal/buffer'
-import { closeAgentTerminalByProc } from '@/app/right-sidebar/terminal/terminals'
-import { burstVibeHearts } from '@/components/chat/vibe-hearts'
-import { translateNow } from '@/i18n'
-import { type GatewayEventPayload, textPart } from '@/lib/chat-messages'
-import { coerceGatewayText, coerceThinkingText, normalizePersonalityValue } from '@/lib/chat-runtime'
-import { playCompletionSound } from '@/lib/completion-sound'
-import {
-  approvalReplaySessionId,
-  resolveGatewayEventSessionId,
-  UNSCOPED_STREAM_EVENT_TYPES
-} from '@/lib/gateway-events'
-import { triggerHaptic } from '@/lib/haptics'
-import { modelOptionsQueryKey } from '@/lib/model-options'
-import { isProviderSetupErrorMessage } from '@/lib/provider-setup-errors'
-import { invalidateSlashCompletions } from '@/lib/slash-completion-cache'
-import type { TourAction, TourStep } from '@/lib/tour'
-import { type AgentNoticePayload, clearAgentNotice, nativeNoticeInput, showAgentNotice } from '@/store/agent-notices'
-import { reconcileApprovalModeForProfile } from '@/store/approval-mode'
-import { billingCtaLabel, clearBillingBlock, runBillingRecovery, setBillingBlock } from '@/store/billing-block'
-import {
-  clearClarifyRequest,
-  normalizeChoices,
-  normalizeQuestions,
-  setClarifyRequest,
-  warnDroppedChoices
-} from '@/store/clarify'
-import { setSessionCompacting } from '@/store/compaction'
-import { refreshBackgroundProcesses } from '@/store/composer-status'
-import { $gateway, activeGatewayConnectionId } from '@/store/gateway'
-import { applyGoalStatusText } from '@/store/goals'
-import {
-  notifyCronChanged,
-  notifyPairingChanged,
-  notifyPetChanged,
-  notifyPlatformsChanged,
-  notifySessionsChanged,
-  type PetChangeMeta,
-  setChangeEventsAvailable
-} from '@/store/live-sync'
-import { setMcpSetupRequest } from '@/store/mcp-setup'
-import { dispatchNativeNotification } from '@/store/native-notifications'
-import { isDiskFullErrorMessage, notify, notifyError } from '@/store/notifications'
-import { requestDesktopOnboarding, requestDesktopOnboardingForCredentialWarning } from '@/store/onboarding'
-import { applyDesktopLayoutPreset, revealDesktopPane } from '@/store/pane-focus'
-import { flashPetActivity, markPetUnread, setPetActivity } from '@/store/pet'
-import { $activeGatewayProfile, normalizeProfileKey } from '@/store/profile'
-import { followActiveSessionCwd } from '@/store/projects'
-import {
-  clearAllPrompts,
-  receiveApprovalRequest,
-  replayPendingApproval,
-  setSecretRequest,
-  setSudoRequest
-} from '@/store/prompts'
-import { providerWaitText, setSessionProviderWait } from '@/store/provider-wait'
-import { recordAgentReaction } from '@/store/reactions-local'
-import {
-  $currentCwd,
-  $currentModel,
-  $currentProvider,
-  $selectedStoredSessionId,
-  $sessions,
-  sessionMatchesStoredId,
-  setCurrentBranch,
-  setCurrentCwdTransient,
-  setCurrentFastMode,
-  setCurrentPersonality,
-  setCurrentReasoningEffort,
-  setCurrentServiceTier,
-  setCurrentUsage,
-  setMessages,
-  setSessions,
-  setTerminalBackend,
-  setTurnStartedAt,
-  setWorkspaceCwdOwner,
-  setYoloActive
-} from '@/store/session'
-import { dropSessionState, unbindTileRuntime } from '@/store/session-states'
-import { pruneDelegateFallbackSubagents, pruneFinishedSessionSubagents, upsertSubagent } from '@/store/subagents'
-import { reportMcpToolResult } from '@/store/suggestion-providers/repair'
-import { invalidateSkillSuggestionIndex } from '@/store/suggestion-providers/skill'
-import { requestScrollToBottom } from '@/store/thread-scroll'
-import { clearActiveSessionTodos } from '@/store/todos'
-import { recordToolDiff } from '@/store/tool-diffs'
-import { setSessionDraftingTool } from '@/store/tool-drafting'
-import { reportInstallMethodWarning } from '@/store/updates'
-import { notifyWorkspaceChanged, toolChangedPath, toolMayMutateFiles } from '@/store/workspace-events'
-// Leaf import (not the `@/themes` barrel) to avoid pulling the ThemeProvider
-// module graph into the gateway event hot path.
-import { ingestBackendSkin } from '@/themes/backend-sync'
-import type { RpcEvent } from '@/types/hermes'
-
-import type { ClientSessionState } from '../../../types'
-import { finalizeInterruptedMessages } from '../use-prompt-actions/rewind'
-
-import {
-  hasSessionInfoStatePatch,
-  PRE_TURN_LIVE_SETTLE_GRACE_MS,
-  sessionInfoStatePatch,
-  SUBAGENT_EVENT_TYPES,
-  toTodoPayload
-} from './utils'
-
-function firstBillingLine(text: string): string {
-  return (text || '').split('\n')[0]?.trim() ?? ''
-}
-
-/**
- * Whether a `session.info` payload's `stored_session_id` may be treated as the
- * selected conversation's, so its cwd can be claimed for it (#71254).
- *
- * Absent is not the same as different: the backend omits the id on a
- * not-yet-built (`lazy`) session, and refusing there would leave the workspace
- * marked un-owned for the rest of the conversation. Matching goes through the
- * lineage (`sessionMatchesStoredId`) so a compression-rotated tip and the root
- * a pinned-row selection may hold still read as one conversation.
- */
-function sessionInfoDescribesSelectedSession(storedSessionId: string | undefined): boolean {
-  const infoStoredSessionId = storedSessionId?.trim() || null
-  const selected = $selectedStoredSessionId.get() ?? null
-
-  if (!infoStoredSessionId) {
-    return true
-  }
-
-  // A named session cannot describe a fresh draft. Treating a null selection as
-  // a wildcard let a background tile's `session.info` rehome the draft to the
-  // tile's workspace.
-  if (!selected) {
-    return false
-  }
-
-  if (infoStoredSessionId === selected) {
-    return true
-  }
-
-  // Either id may be the live tip or the lineage root, so ask whether ONE row
-  // answers to both rather than assuming which side rotated.
-  return $sessions
-    .get()
-    .some(session => sessionMatchesStoredId(session, infoStoredSessionId) && sessionMatchesStoredId(session, selected))
-}
-
-/**
- * A turn failed on a billing wall (out of credits / payment required). The
- * gateway forwards the structured descriptor built by `agent/billing_links.py`;
- * we cache it per-session (drives the in-chat banner) AND raise one sticky,
- * billing-specific toast — never the generic "Hermes error" — with a smart CTA
- * (Nous → in-app Settings → Billing, other providers → their billing page).
- */
-function surfaceBillingBlock(sessionId: string, raw: unknown): void {
-  if (!raw || typeof raw !== 'object') {
-    return
-  }
-
-  const block = raw as BillingBlock
-
-  if (typeof block.provider !== 'string') {
-    return
-  }
-
-  setBillingBlock(sessionId, block)
-
-  const ctaCopy = {
-    addCredits: translateNow('billingBlock.addCredits'),
-    openBilling: translateNow('billingBlock.openBilling')
-  }
-
-  notify({
-    // Collapse repeat walls from the same provider into one toast.
-    id: `billing-block:${block.provider}`,
-    kind: 'warning',
-    icon: 'credit-card',
-    title: block.is_nous
-      ? translateNow('billingBlock.titleNous')
-      : translateNow('billingBlock.titleProvider', block.provider_label),
-    message: firstBillingLine(block.message) || translateNow('billingBlock.fallbackMessage'),
-    // Sticky: a credit wall blocks every turn until resolved.
-    durationMs: 0,
-    action: { label: billingCtaLabel(block, ctaCopy), onClick: () => runBillingRecovery(block) }
-  })
-}
-
-/**
- * Events that retire a "drafting a tool call" claim.
- *
- * `tool.generating` opens the claim and nothing closes it — a draft can be
- * abandoned without ever reaching `tool.start`, so enumerating the ways one
- * *ends* left the label on screen for the rest of the turn. Inverted: the
- * claim only covers what the model is emitting right now, and any other output
- * from the session proves it moved on. Same rule the TUI applies to its
- * transient trail lines (`turnController.pruneTransient`).
- */
-const DRAFT_SUPERSEDING_EVENT_TYPES = new Set([
-  'error',
-  'message.complete',
-  'message.delta',
-  'message.start',
-  'reasoning.delta',
-  'thinking.delta',
-  'tool.complete',
-  'tool.progress',
-  'tool.start'
-])
-
-const COMPACTION_RESUME_EVENT_TYPES = new Set([
-  'message.delta',
-  'message.interim',
-  'thinking.delta',
-  'reasoning.delta',
-  'reasoning.available',
-  'moa.reference',
-  'moa.aggregating',
-  'moa.progress',
-  'moa.phase',
-  'tool.start',
-  'tool.progress',
-  'tool.generating',
-  'tool.complete'
-])
-
-const PROVIDER_WAIT_SUPERSEDING_EVENT_TYPES = new Set([
-  'error',
-  'message.complete',
-  'message.delta',
-  'message.interim',
-  'message.start',
-  'reasoning.available',
-  'reasoning.delta',
-  'tool.complete',
-  'tool.generating',
-  'tool.progress',
-  'tool.start'
-])
-
-interface GatewayEventDeps {
-  activeGatewayProfile: string
-  activeSessionIdRef: MutableRefObject<string | null>
-  compactedTurnRef: MutableRefObject<Set<string>>
-  lastCwdInfoSessionRef: MutableRefObject<string | null>
-  nativeSubagentSessionsRef: MutableRefObject<Set<string>>
-  appendAssistantDelta: (sessionId: string, delta: string, occurredAt?: number) => void
-  appendReasoningDelta: (sessionId: string, delta: string, replace?: boolean, occurredAt?: number) => void
-  completeAssistantMessage: (
-    sessionId: string,
-    text: string,
-    responsePreviewed?: boolean,
-    failure?: { error: string; partial: boolean },
-    occurredAt?: number
-  ) => void
-  failAssistantMessage: (sessionId: string, errorMessage: string, occurredAt?: number) => void
-  flushQueuedDeltas: (sessionId?: string) => void
-  finalizeInterimAssistantMessage: (sessionId: string, text: string, occurredAt?: number) => void
-  hydrateFromStoredSession: (
-    attempts?: number,
-    storedSessionId?: string | null,
-    runtimeSessionId?: string | null
-  ) => Promise<void>
-  queryClient: QueryClient
-  refreshHermesConfig: () => Promise<void>
-  scheduleSessionsRefresh: () => void
-  sessionInterrupted: (sessionId: string) => boolean
-  sessionStateByRuntimeIdRef: MutableRefObject<Map<string, ClientSessionState>>
-  updateSessionState: (
-    sessionId: string,
-    updater: (state: ClientSessionState) => ClientSessionState,
-    storedSessionId?: string | null
-  ) => ClientSessionState
-  upsertToolCall: (
-    sessionId: string,
-    payload: GatewayEventPayload | undefined,
-    phase: 'running' | 'complete',
-    sourceEventType?: string,
-    occurredAt?: number
-  ) => void
-}
-
-/** The gateway-event dispatcher, extracted from useMessageStream. */
-export function useGatewayEventHandler(deps: GatewayEventDeps) {
-  const {
-    appendAssistantDelta,
-    appendReasoningDelta,
-    activeGatewayProfile,
-    activeSessionIdRef,
-    compactedTurnRef,
-    lastCwdInfoSessionRef,
-    nativeSubagentSessionsRef,
-    completeAssistantMessage,
-    failAssistantMessage,
-    flushQueuedDeltas,
-    finalizeInterimAssistantMessage,
-    hydrateFromStoredSession,
-    queryClient,
-    refreshHermesConfig,
-    scheduleSessionsRefresh,
-    sessionInterrupted,
-    sessionStateByRuntimeIdRef,
-    updateSessionState,
-    upsertToolCall
-  } = deps
-
-  const unscopedStreamSessionIdRef = useRef<string | null>(null)
-
-  // session.info arrives in bursts (agent build ready + turn end + title /
-  // MCP / compress edges within the same second). Each used to fire its own
-  // refreshHermesConfig — two REST calls (config + defaults) per event, per
-  // turn, including for BACKGROUND sessions whose values the fetch can't even
-  // apply. Coalesce to one trailing fetch per burst; the caller gates on
-  // `apply` so background traffic doesn't schedule anything.
-  const configRefreshTimerRef = useRef<null | number>(null)
-
-  const scheduleConfigRefresh = useCallback(() => {
-    if (configRefreshTimerRef.current !== null) {
-      return
-    }
-
-    if (typeof window === 'undefined') {
-      void refreshHermesConfig()
-
-      return
-    }
-
-    configRefreshTimerRef.current = window.setTimeout(() => {
-      configRefreshTimerRef.current = null
-      void refreshHermesConfig()
-    }, 300)
-  }, [refreshHermesConfig])
-
-  useEffect(
-    () => () => {
-      if (configRefreshTimerRef.current !== null && typeof window !== 'undefined') {
-        window.clearTimeout(configRefreshTimerRef.current)
-        configRefreshTimerRef.current = null
-      }
-    },
-    []
-  )
-
-  return useCallback(
-    (event: RpcEvent) => {
-      const payload = event.payload as GatewayEventPayload | undefined
-
-      // "From the active profile" must mean "from the active SOURCE": every
-      // registered connection exposes a 'default' profile, so a bare profile
-      // comparison attributes gateway B's 'default' events to gateway A's
-      // 'default'. Compare the composite (connectionId, profile) scope with
-      // registryBackendScopeKey — untagged primary events keep the legacy
-      // bare-profile behavior byte-identical.
-      const fromActiveSource = (): boolean =>
-        (!event.profile || normalizeProfileKey(event.profile) === normalizeProfileKey($activeGatewayProfile.get())) &&
-        registryBackendScopeKey(event.connectionId ?? null, event.profile ?? null) ===
-          registryBackendScopeKey(activeGatewayConnectionId(), event.profile ?? null)
-
-      const occurredAt =
-        typeof payload?.timestamp === 'number' && Number.isFinite(payload.timestamp)
-          ? payload.timestamp
-          : Date.now() / 1000
-
-      const explicitSid = event.session_id || ''
-
-      const route = resolveGatewayEventSessionId({
-        activeSessionId: activeSessionIdRef.current,
-        eventType: event.type,
-        explicitSessionId: explicitSid,
-        unscopedStreamSessionId: unscopedStreamSessionIdRef.current
-      })
-
-      unscopedStreamSessionIdRef.current = route.nextUnscopedStreamSessionId
-
-      if (route.drop) {
-        return
-      }
-
-      const sessionId = route.sessionId
-
-      // Late stragglers: an unscoped stream event attributed via the
-      // active-session fallback (no pin) to a session that has no live turn
-      // belongs to a turn that already ended elsewhere. Dropping it keeps the
-      // previous session's tail events (a delayed `thinking.delta` or
-      // `status.update`) from landing in a freshly opened chat (#43142 family:
-      // busy/streaming UI inherited when switching sessions).
-      if (
-        sessionId &&
-        !explicitSid &&
-        !route.pinned &&
-        event.type &&
-        event.type !== 'message.start' &&
-        UNSCOPED_STREAM_EVENT_TYPES.has(event.type)
-      ) {
-        const state = sessionStateByRuntimeIdRef.current.get(sessionId)
-
-        const hasLiveTurn = Boolean(
-          state && (state.awaitingResponse || state.busy || state.streamId || state.sawAssistantPayload)
-        )
-
-        if (!hasLiveTurn) {
-          return
-        }
-      }
-
-      const isActiveEvent = !!sessionId && sessionId === activeSessionIdRef.current
-
-      const replaySessionId = approvalReplaySessionId(event.type, activeSessionIdRef.current, sessionId)
-
-      if (replaySessionId) {
-        void replayPendingApproval($gateway.get(), replaySessionId).catch(() => undefined)
-      }
-
-      // Mid-turn compaction does not emit another message.start. The first
-      // model output or tool event proves summarization has finished and the
-      // turn has resumed, so retire the phase label without waiting for the
-      // whole turn to complete.
-      if (sessionId && COMPACTION_RESUME_EVENT_TYPES.has(event.type) && compactedTurnRef.current.has(sessionId)) {
-        setSessionCompacting(sessionId, false)
-      }
-
-      if (sessionId && DRAFT_SUPERSEDING_EVENT_TYPES.has(event.type)) {
-        setSessionDraftingTool(sessionId, '')
-      }
-
-      if (sessionId && PROVIDER_WAIT_SUPERSEDING_EVENT_TYPES.has(event.type)) {
-        setSessionProviderWait(sessionId, '')
-      }
-
-      if (event.type === 'gateway.ready') {
-        // Seed the active skin into the desktop theme registry without applying,
-        // so a fresh connect never overrides the user's persisted desktop theme.
-        ingestBackendSkin((payload as { skin?: HermesSkin } | undefined)?.skin, { apply: false })
-        // Backends with the change watcher broadcast pet/cron/sessions change
-        // events; consumers demote their legacy polls to slow backstops.
-        setChangeEventsAvailable(Boolean((payload as { change_events?: boolean } | undefined)?.change_events))
-
-        return
-      } else if (event.type === 'skin.changed') {
-        // A runtime skin switch (Hermes activating an authored skin, or `/skin`
-        // on another surface). Only the active source+profile's change repaints.
-        if (fromActiveSource()) {
-          ingestBackendSkin(payload as HermesSkin | undefined, { apply: true })
-        }
-
-        return
-      } else if (
-        event.type === 'pet.changed' ||
-        event.type === 'cron.changed' ||
-        event.type === 'sessions.changed' ||
-        event.type === 'platforms.changed' ||
-        event.type === 'pairing.changed'
-      ) {
-        // Change-watcher broadcasts (server._broadcast_watched_changes): the
-        // backend's on-disk signature moved. Route to the live-sync ticks the
-        // former pollers now subscribe to. Only the active source+profile's
-        // changes apply — background profile sockets (and other connections'
-        // gateways) watch their own homes.
-        if (fromActiveSource()) {
-          if (event.type === 'pet.changed') {
-            notifyPetChanged(payload as PetChangeMeta | undefined)
-          } else if (event.type === 'cron.changed') {
-            notifyCronChanged()
-          } else if (event.type === 'platforms.changed') {
-            notifyPlatformsChanged()
-          } else if (event.type === 'pairing.changed') {
-            notifyPairingChanged()
-          } else {
-            notifySessionsChanged()
-          }
-        }
-
-        return
-      } else if (event.type === 'session.reclaimed') {
-        // The backend reclaimed a live session we may still be holding (idle
-        // TTL, LRU cap, or the WS-orphan reap). Without this the runtime id
-        // stays cached until something fails against it, which reads as the
-        // session vanishing rather than being reclaimed. Drop the cached state
-        // now — the stored row is untouched, so the sidebar keeps the
-        // conversation and reopening it resumes from the DB.
-        const reclaimedRuntimeId = String((payload as { session_id?: string } | undefined)?.session_id ?? '')
-
-        if (reclaimedRuntimeId) {
-          dropSessionState(reclaimedRuntimeId)
-          // A tile bound to the reclaimed runtime would otherwise render an
-          // empty transcript forever: its view reads $sessionStates[runtime]
-          // (just dropped) and its resume effect is gated on !runtimeId, so a
-          // bound tile never re-resumes (#82620). Unbind it so the effect
-          // refires against the intact stored session — and purge the wiring
-          // cache's entry, or resumeTile's warm path would hand the dead
-          // runtime straight back instead of cold-resuming a live one.
-          unbindTileRuntime(reclaimedRuntimeId)
-          sessionStateByRuntimeIdRef.current.delete(reclaimedRuntimeId)
-        }
-
-        // The row's ended_at moved, so refresh the lists that render it.
-        notifySessionsChanged()
-
-        return
-      } else if (event.type === 'session.info') {
-        // Apply session-scoped fields when the event targets the active
-        // session, OR when it's a global broadcast and we have no session.
-        const apply = explicitSid ? isActiveEvent : !activeSessionIdRef.current
-        const statePatch = sessionInfoStatePatch(payload)
-        const hasStatePatch = hasSessionInfoStatePatch(statePatch)
-        const modelChanged = typeof payload?.model === 'string'
-        const providerChanged = typeof payload?.provider === 'string'
-        const runningChanged = typeof payload?.running === 'boolean'
-        // The backend stamps model/provider (as strings) on EVERY session.info,
-        // so the presence flags above are true on every heartbeat/turn edge —
-        // fine for the cheap atom writes below (nanostores skips identical
-        // values), but they also drove queryClient.invalidateQueries, refetching
-        // the model-options provider catalog once or twice per turn for a model
-        // that never changed. Only a genuine VALUE change (vs the session's own
-        // cached runtime state, captured before the state patch below applies;
-        // composer atoms as the fallback for an uncached session) invalidates.
-        const knownState = sessionId ? sessionStateByRuntimeIdRef.current.get(sessionId) : undefined
-        const modelValueChanged = modelChanged && payload!.model !== (knownState?.model ?? $currentModel.get())
-
-        const providerValueChanged =
-          providerChanged && payload!.provider !== (knownState?.provider ?? $currentProvider.get())
-
-        // Config is profile-scoped, but session.info also arrives for background
-        // sessions. Only an active-session event from the currently active
-        // gateway may reconcile the foreground cache. Requiring the renderer's
-        // source tag prevents an event queued before a profile swap from being
-        // attributed to the newly active profile.
-        if (isActiveEvent && typeof payload?.approval_mode === 'string' && event.profile && fromActiveSource()) {
-          reconcileApprovalModeForProfile(event.profile, payload.approval_mode)
-        }
-
-        if (apply) {
-          // Do not call setCurrentModel / setCurrentProvider here. Composer
-          // model/provider is sticky UI state (localStorage + manual picks).
-          // Periodic session.info heartbeats often carry the profile default
-          // (or a stale session model) and would silently revert the dropdown.
-          // Active-session model/provider still flows through the session state
-          // cache via updateSessionState → syncRuntimeMetadataToView below.
-
-          if (typeof payload?.cwd === 'string' && sessionInfoDescribesSelectedSession(payload.stored_session_id)) {
-            // The active session's agent can relocate itself (new repo/worktree
-            // via the terminal). When the SAME active session's cwd actually
-            // moves, follow it — refresh the project tree + scope so the sidebar
-            // tracks the live thread. A fresh selection (different session id)
-            // is a switch, not a move, so it refreshes data without yanking scope.
-            const cwdMoved = payload.cwd !== $currentCwd.get()
-            const sameSession = !!sessionId && sessionId === lastCwdInfoSessionRef.current
-
-            lastCwdInfoSessionRef.current = sessionId
-            setCurrentCwdTransient(payload.cwd)
-
-            // The backend just confirmed the selected conversation's real
-            // workspace, so it owns the path we wrote. Without the claim the
-            // marker keeps naming whoever held it before — including the
-            // released state a detached resume leaves behind — and the primary
-            // workspace-derived surfaces stay hidden against a folder the
-            // backend has confirmed (#71254).
-            setWorkspaceCwdOwner($selectedStoredSessionId.get())
-
-            if (cwdMoved && sameSession) {
-              void followActiveSessionCwd(payload.cwd)
-            }
-          }
-
-          if (typeof payload?.branch === 'string') {
-            setCurrentBranch(payload.branch)
-          }
-
-          if (typeof payload?.terminal_backend === 'string') {
-            setTerminalBackend(payload.terminal_backend)
-          }
-
-          if (typeof payload?.personality === 'string') {
-            setCurrentPersonality(normalizePersonalityValue(payload.personality))
-          }
-
-          if (typeof payload?.reasoning_effort === 'string') {
-            setCurrentReasoningEffort(payload.reasoning_effort)
-          }
-
-          if (typeof payload?.service_tier === 'string') {
-            setCurrentServiceTier(payload.service_tier)
-          }
-
-          if (typeof payload?.fast === 'boolean') {
-            setCurrentFastMode(payload.fast)
-          }
-
-          if (typeof payload?.yolo === 'boolean') {
-            setYoloActive(payload.yolo)
-          }
-        }
-
-        if (sessionId && hasStatePatch) {
-          updateSessionState(
-            sessionId,
-            state => ({
-              ...state,
-              ...statePatch,
-              branch: statePatch.branch ?? state.branch,
-              cwd: statePatch.cwd ?? state.cwd
-            }),
-            payload?.stored_session_id || undefined
-          )
-        }
-
-        // The running→busy transition must reach EVERY session, not just the
-        // active one. The `apply` gate above correctly scopes view-only side
-        // effects (setCurrentCwd, etc.) to the focused chat,
-        // but the per-session busy state is what drives the sidebar working
-        // indicator — a background session's turn start/finish must update
-        // its dot without the user opening it. updateSessionState only
-        // mutates the per-runtime cache entry, and syncSessionStateToView
-        // guards the view publish to the active session, so this is safe.
-        if (runningChanged && sessionId) {
-          // Set when THIS event released a turn that ended without ever
-          // producing an assistant payload, so the catch-up side effects below
-          // run on that edge only. The updater is invoked exactly once,
-          // synchronously, by updateSessionState.
-          let recoveredWithoutPayload = false
-
-          const nextState = updateSessionState(
-            sessionId,
-            state => {
-              const busy = Boolean(payload!.running)
-
-              if (state.busy === busy && (busy || !state.awaitingResponse)) {
-                return state
-              }
-
-              if (busy) {
-                // Don't re-arm busy from a stale session.info if the user
-                // just clicked Stop (interrupted=true). The backend's
-                // cooperative interrupt may not have propagated yet, so
-                // running is still true in the heartbeat. The turn's
-                // finally block will emit running=false to clear busy.
-                if (state.interrupted) {
-                  return state
-                }
-
-                // Prefer the gateway-reported turn_started_at so the timer
-                // survives session switches and session.info heartbeats.
-                const gatewayTurnStartedAt =
-                  typeof payload!.turn_started_at === 'number' && payload!.turn_started_at > 0
-                    ? payload!.turn_started_at * 1000
-                    : null
-
-                return {
-                  ...state,
-                  busy,
-                  // running=true from the backend is turn-live proof, same as
-                  // message.start (e.g. resuming an already-running session
-                  // that never replays its start event).
-                  turnLive: true,
-                  turnStartedAt: state.turnStartedAt ?? gatewayTurnStartedAt ?? Date.now()
-                }
-              }
-
-              // The turn has not started backend-side yet. submit arms
-              // busy/awaitingResponse optimistically, so a running=false
-              // heartbeat that lands in the gap before the turn spins up is a
-              // pre-start report, not a finished turn — settling on it would
-              // drop the spinner and re-open the send guard mid-flight.
-              // turnLive is stamped only once the backend reports the turn
-              // live (message.start, the running=true edge, or a resumed
-              // in-flight turn) and is cleared by every settle, so false
-              // here is exactly "no turn has been reported running yet".
-              // (turnStartedAt can't discriminate — it is optimistically
-              // seeded at submit so the visible timer starts at Enter.)
-              //
-              // BOUNDED (#86795): an armed turn that never goes live — a
-              // restore/edit whose rewind was refused after the optimistic
-              // arm, a submit response lost to a gateway bounce, a terminal
-              // error event that never arrived — would otherwise hold this
-              // gate forever. busy then latches until app restart:
-              // isTargetSessionBusy refuses every send, the composer queues
-              // each message, and the queue drain (gated on busy→false) never
-              // fires. turnStartedAt is seeded at the optimistic arm, so its
-              // age bounds the hold; past the grace window (or with no clock
-              // at all) the gateway's running=false is authoritative and the
-              // settle below releases the session.
-              const armedAt = state.turnStartedAt
-
-              const withinPreStartGrace =
-                typeof armedAt === 'number' && Date.now() - armedAt < PRE_TURN_LIVE_SETTLE_GRACE_MS
-
-              if (state.awaitingResponse && !state.sawAssistantPayload && !state.turnLive && withinPreStartGrace) {
-                return state
-              }
-
-              // Past that gate the turn DID start and the backend now reports it
-              // finished. When no assistant payload ever arrived (gateway crash
-              // mid-stream, provider error before the first delta, agent-build
-              // failure) message.complete never fires, so this is the only event
-              // that can release the session. Bailing here instead left
-              // awaitingResponse/busy latched until app restart (#46517): the
-              // per-session busy flag is authoritative for isTargetSessionBusy,
-              // so submitPrompt and the slash dispatcher silently returned false
-              // and the session accepted no further input.
-              recoveredWithoutPayload = state.awaitingResponse && !state.sawAssistantPayload
-
-              return {
-                ...state,
-                awaitingResponse: false,
-                busy,
-                // The turn is over but its streaming bubble may still say
-                // pending — running=false from the agent loop's finally block
-                // is the ONLY settle signal when message.complete never
-                // arrives (turn crash, reconnect gap). Left pending, that
-                // bubble shows a thinking indicator forever, stranded
-                // mid-transcript once the next user message lands after it.
-                // finalizeInterruptedMessages un-pends kept text and drops
-                // empty placeholders; on the normal path message.complete
-                // already settled everything and this is a no-op.
-                messages: finalizeInterruptedMessages(state.messages, state.streamId, occurredAt),
-                pendingBranchGroup: null,
-                streamId: null,
-                turnStartedAt: null,
-                turnLive: false
-              }
-            },
-            payload?.stored_session_id || undefined
-          )
-
-          if (recoveredWithoutPayload) {
-            // Stays unscoped, like the settle above: a background session's
-            // sidebar row has to drop its working dot without the user opening
-            // it. This fires on the recovery edge only — once awaitingResponse
-            // is false the `state.busy === busy` guard above short-circuits
-            // every later heartbeat — so it costs one coalesced refresh per
-            // broken turn, not one per tick.
-            scheduleSessionsRefresh()
-
-            // The transcript catch-up IS scoped. The stream died, but the turn
-            // itself may have completed and been persisted, so refetch stored
-            // history for the session actually on screen; a background session
-            // reads its history when the user opens it, and hydrating every one
-            // of them here would fan a REST call out per idle session.
-            if (isActiveEvent) {
-              void hydrateFromStoredSession(3, nextState.storedSessionId, sessionId)
-            }
-          }
-        }
-
-        if (payload?.usage && (!explicitSid || isActiveEvent)) {
-          setCurrentUsage(current => ({ ...current, ...payload.usage }))
-        }
-
-        requestDesktopOnboardingForCredentialWarning(payload?.credential_warning)
-
-        if (apply) {
-          reportInstallMethodWarning(payload?.install_warning)
-          // Config refetch is only meaningful for the foreground context —
-          // everything refreshHermesConfig applies is either active-session
-          // guarded or a composer/global pref. Background sessions' heartbeats
-          // used to trigger it too (two REST calls each, every turn).
-          scheduleConfigRefresh()
-        }
-
-        if (modelValueChanged || providerValueChanged) {
-          void queryClient.invalidateQueries({
-            queryKey:
-              explicitSid && sessionId ? modelOptionsQueryKey(activeGatewayProfile, sessionId) : ['model-options']
-          })
-        }
-      } else if (event.type === 'session.usage') {
-        // Live usage tick emitted while a turn is mid-flight (see tui_gateway
-        // _start_usage_ticker) so the status-bar context window tracks growth
-        // during the turn instead of only jumping at message.complete.
-        if (payload?.usage && sessionId) {
-          // Per-session twin first: a focused secondary tile reads this cache,
-          // while the primary-only global mirrors the active session.
-          updateSessionState(sessionId, state => ({
-            ...state,
-            usage: { calls: 0, input: 0, output: 0, total: 0, ...state.usage, ...payload.usage }
-          }))
-
-          if (isActiveEvent) {
-            setCurrentUsage(current => ({ ...current, ...payload.usage }))
-          }
-        }
-      } else if (event.type === 'message.start') {
-        if (!sessionId) {
-          return
-        }
-
-        flushQueuedDeltas(sessionId)
-        pruneFinishedSessionSubagents(sessionId)
-        setSessionCompacting(sessionId, false)
-        compactedTurnRef.current.delete(sessionId)
-        nativeSubagentSessionsRef.current.delete(sessionId)
-        // A fresh turn on this session optimistically clears its billing wall;
-        // if credits are still exhausted the next failure re-raises it.
-        clearBillingBlock(sessionId)
-
-        if (isActiveEvent) {
-          triggerHaptic('streamStart')
-        }
-
-        // Submit→accept latency: seedOptimistic armed the clock at Enter; this
-        // event is the backend accepting the turn. Debug-only visibility into
-        // how long the arm actually took (the "no progress box for seconds"
-        // complaint) — reads the pre-update cache, costs nothing when clean.
-        const seededAt = sessionStateByRuntimeIdRef.current.get(sessionId)?.turnStartedAt
-
-        if (typeof seededAt === 'number') {
-          console.debug('[turn-accept-latency]', { sessionId, ms: Date.now() - seededAt })
-        }
-
-        updateSessionState(sessionId, state => {
-          // If the user clicked Stop (cancelRun set interrupted=true), don't
-          // let a stale message.start from a chained turn (goal follow-up,
-          // completion drain) or an in-flight LLM response re-arm busy.
-          // The interrupt is user intent — the backend's cooperative cancel
-          // may not have propagated yet, so its events are stale. The turn's
-          // finally block will emit session.info with running=false to clear
-          // busy for real once the agent loop actually exits.
-          if (state.interrupted) {
-            return state
-          }
-
-          return {
-            ...state,
-            busy: true,
-            awaitingResponse: true,
-            sawAssistantPayload: false,
-            interrupted: false,
-            interimBoundaryPending: false,
-            // Backend accepted the turn — the no-payload settle gate below may
-            // now treat a running=false heartbeat as a real turn end.
-            turnLive: true,
-            // Keep the submit-time seed (submit.ts seedOptimistic) — resetting
-            // here would hide the submit→accept round trip from the timer.
-            // Backend-originated turns (queue drain elsewhere, goal follow-up)
-            // have no seed and arm here.
-            turnStartedAt: state.turnStartedAt ?? Date.now()
-          }
-        })
-
-        if (isActiveEvent) {
-          // Belt-and-suspenders mirror of the ACTIVE session's per-session
-          // clock (the load-bearing mirror is the view-sync flush in
-          // use-session-state-cache). Mirror the seeded value, not Date.now():
-          // resetting to accept-time here would visibly snap the timer back
-          // after the submit-time seed above already started it.
-          setTurnStartedAt(sessionStateByRuntimeIdRef.current.get(sessionId)?.turnStartedAt ?? Date.now())
-        }
-      } else if (event.type === 'message.delta') {
-        if (sessionId) {
-          appendAssistantDelta(sessionId, coerceGatewayText(payload?.text), occurredAt)
-        }
-      } else if (event.type === 'message.interim') {
-        // The agent emitted interim assistant commentary (text alongside tool
-        // calls, or the attempted final answer before a verify-on-stop nudge).
-        // Finalize it as its own sealed bubble so message.complete doesn't wipe
-        // it — the text was already streamed via message.delta and is visible.
-        if (sessionId) {
-          flushQueuedDeltas(sessionId)
-          const text = coerceGatewayText(payload?.text)
-
-          if (text) {
-            finalizeInterimAssistantMessage(sessionId, text, occurredAt)
-          }
-        }
-      } else if (event.type === 'thinking.delta') {
-        // Most thinking.delta frames are kawaii spinner rewrites and stay out
-        // of the transcript. Explained provider waits are different: the core
-        // emits them after prolonged silence, so name that wait in the existing
-        // bottom-of-thread status row instead of leaving only an unlabeled timer.
-        if (sessionId) {
-          setSessionProviderWait(sessionId, providerWaitText(coerceGatewayText(payload?.text)))
-        }
-      } else if (event.type === 'reaction') {
-        // Core-detected affection (ily / <3 / good bot) on the user's message.
-        // Play hearts only for the visible session so background turns stay quiet.
-        if (isActiveEvent && (payload?.kind ?? 'vibe') === 'vibe') {
-          burstVibeHearts()
-        }
-      } else if (event.type === 'reasoning.delta') {
-        if (sessionId) {
-          appendReasoningDelta(sessionId, coerceThinkingText(payload?.text), false, occurredAt)
-        }
-
-        if (isActiveEvent) {
-          setPetActivity({ reasoning: true })
-        }
-      } else if (event.type === 'reasoning.available') {
-        if (sessionId) {
-          appendReasoningDelta(sessionId, coerceThinkingText(payload?.text), true, occurredAt)
-        }
-
-        if (isActiveEvent) {
-          setPetActivity({ reasoning: true })
-        }
-      } else if (event.type === 'moa.reference') {
-        // MoA reference-model output — surface as a labelled thinking chunk
-        // (tagged with the source model) before the aggregator's response, so
-        // the mixture-of-agents process is visible. Reuses the reasoning
-        // disclosure rather than introducing a parallel surface.
-        if (sessionId) {
-          const label = coerceGatewayText(payload?.label) || 'reference'
-          const idx = typeof payload?.index === 'number' ? payload.index : undefined
-          const cnt = typeof payload?.count === 'number' ? payload.count : undefined
-          const header = idx && cnt ? `◇ Reference ${idx}/${cnt} — ${label}` : `◇ Reference — ${label}`
-          const body = coerceThinkingText(payload?.text)
-          const text = `${header}\n${body}\n\n`
-
-          if (idx === undefined || idx <= 1) {
-            // First reference: clear any stale reasoning left over from
-            // before this turn's references start, same as before.
-            appendReasoningDelta(sessionId, text, true, occurredAt)
-          } else {
-            // Later references must accumulate, not replace — otherwise
-            // each new reference wipes out the ones already shown (#64658).
-            // Queue-then-flush (rather than the streamed/batched queue path)
-            // applies it immediately, since each reference arrives as one
-            // complete block rather than incremental tokens. reasoning.delta
-            // cannot be mid-flight here: MoAChatCompletions.reference_callback
-            // (agent/moa_loop.py) fires "moa.reference" once per reference's
-            // already-complete text, with no concurrent token stream for the
-            // reference-gathering phase, so there is no in-flight delta to
-            // collide with in the shared queue bucket.
-            appendReasoningDelta(sessionId, text, false, occurredAt)
-            flushQueuedDeltas(sessionId)
-          }
-        }
-
-        if (isActiveEvent) {
-          setPetActivity({ reasoning: true })
-        }
-      } else if (event.type === 'moa.aggregating') {
-        // Status transition only; the aggregator's reply arrives via the normal
-        // message stream. No reasoning/transcript mutation here.
-        if (isActiveEvent) {
-          setPetActivity({ reasoning: true })
-        }
-      } else if (event.type === 'moa.progress') {
-        // Live reference fan-out progress ("refs k/n") — surfaced in the same
-        // reasoning disclosure the references land in. These lines arrive
-        // BEFORE any moa.reference event (references are only emitted once the
-        // whole fan-out completes), and the first moa.reference replaces the
-        // block, so the progress trail is self-cleaning.
-        if (sessionId && typeof payload?.refs_done === 'number' && typeof payload?.refs_total === 'number') {
-          const label = coerceGatewayText(payload?.label)
-
-          const line = label
-            ? `◇ MoA refs ${payload.refs_done}/${payload.refs_total} — ${label}\n`
-            : `◇ MoA refs ${payload.refs_done}/${payload.refs_total}\n`
-
-          appendReasoningDelta(sessionId, line, payload.refs_done <= 1, occurredAt)
-          flushQueuedDeltas(sessionId)
-        }
-
-        if (isActiveEvent) {
-          setPetActivity({ reasoning: true })
-        }
-      } else if (event.type === 'moa.phase') {
-        // Phase transition — currently only phase="aggregator" (fan-out done,
-        // aggregator acting). Append a one-line marker; the first
-        // moa.reference that follows replaces the whole block.
-        if (sessionId && payload?.phase === 'aggregator') {
-          appendReasoningDelta(sessionId, '◇ MoA aggregating…\n', false, occurredAt)
-          flushQueuedDeltas(sessionId)
-        }
-
-        if (isActiveEvent) {
-          setPetActivity({ reasoning: true })
-        }
-      } else if (event.type === 'message.complete') {
-        if (!sessionId) {
-          return
-        }
-
-        // Turn ended — drop any blocking prompt still open for THIS session
-        // (e.g. interrupted, or the approval already resolved). Scoped to the
-        // session so a background turn finishing can't wipe the active chat's
-        // prompt, and vice versa.
-        clearAllPrompts(sessionId)
-        clearClarifyRequest(undefined, sessionId)
-        // Turn ended without a final `todo` update — drop a still-unfinished
-        // list so "Tasks N/M" doesn't stay pinned above the composer with the
-        // last item stuck pending/in_progress. Finished lists keep their linger.
-        clearActiveSessionTodos(sessionId)
-        setSessionCompacting(sessionId, false)
-
-        flushQueuedDeltas(sessionId)
-
-        // Keyed by session so only one window beeps when several are open.
-        playCompletionSound(sessionId)
-
-        const finalText = coerceGatewayText(payload?.text) || coerceGatewayText(payload?.rendered)
-
-        // Terminal error frames (status "error") carry the failure in
-        // structured fields: `error` is the message, and `partial` marks
-        // `text` as streamed output to keep rather than the error string.
-        const failure =
-          payload?.status === 'error'
-            ? {
-                error: coerceGatewayText(payload.error).trim() || finalText || 'Hermes reported an error',
-                partial: Boolean(payload.partial)
-              }
-            : undefined
-
-        completeAssistantMessage(sessionId, finalText, payload?.response_previewed, failure, occurredAt)
-
-        // Structured billing wall forwarded by the gateway (out of credits /
-        // payment required) — cache it + raise a billing-specific toast.
-        if (payload?.billing) {
-          surfaceBillingBlock(sessionId, payload.billing)
-        }
-
-        if (isActiveEvent) {
-          setTurnStartedAt(null)
-
-          // Pet beat: a finished turn always celebrates — go straight to the
-          // jump, never linger on the run/reason pose. One atom update (clears
-          // toolRunning/reasoning AND sets celebrate together) so no stray "run"
-          // frame leaks to the sprite — including the popped-out overlay, which
-          // mirrors each activity change. The jump runs ~2 loops, then settles.
-          flashPetActivity({ celebrate: true, reasoning: false, toolRunning: false }, 2200)
-
-          // Light up the pet's mail icon if the user wasn't looking when the turn
-          // finished — a glanceable "new message" hint on the popped-out overlay.
-          // Cleared when they open the app via the mail icon or refocus the window.
-          if (typeof document !== 'undefined' && !document.hasFocus()) {
-            markPetUnread()
-          }
-        }
-
-        if (payload?.usage) {
-          // Per-session twin FIRST (the statusbar reads it for focused tiles);
-          // the primary-only global mirrors the ACTIVE session — ungated it
-          // let a background tile's turn overwrite the primary's count.
-          updateSessionState(sessionId, state => ({
-            ...state,
-            usage: { calls: 0, input: 0, output: 0, total: 0, ...state.usage, ...payload.usage }
-          }))
-
-          if (isActiveEvent) {
-            setCurrentUsage(current => ({ ...current, ...payload.usage }))
-          }
-        }
-      } else if (event.type === 'session.title') {
-        // Live auto-title push (titler runs async, after the turn's refresh).
-        const storedId = typeof payload?.session_id === 'string' ? payload.session_id : ''
-        const nextTitle = typeof payload?.title === 'string' ? payload.title.trim() : ''
-
-        if (storedId && nextTitle) {
-          setSessions(prev => prev.map(s => (sessionMatchesStoredId(s, storedId) ? { ...s, title: nextTitle } : s)))
-        }
-      } else if (event.type === 'tool.generating') {
-        // Announced while the model is still emitting the call's JSON, so it
-        // carries a name and nothing else — no id, no args. Materializing a row
-        // from it strands an argless placeholder whenever the bubble is sealed
-        // before the real `tool.start` arrives, because the two can no longer be
-        // reconciled across the boundary. It's a status, so say it as one.
-        // A stopped turn can still emit a frame or two before the backend
-        // notices, and naming a tool we will never run leaves the label up
-        // until something else retires it. `mutateStream` drops late tool rows
-        // on the same condition; the status line has to agree with it.
-        if (!sessionId || sessionInterrupted(sessionId)) {
-          return
-        }
-
-        setSessionDraftingTool(sessionId, typeof payload?.name === 'string' ? payload.name : '')
-
-        if (isActiveEvent) {
-          setPetActivity({ reasoning: false, toolRunning: true })
-        }
-      } else if (event.type === 'tool.start' || event.type === 'tool.progress') {
-        if (!sessionId) {
-          return
-        }
-
-        flushQueuedDeltas(sessionId)
-        upsertToolCall(sessionId, toTodoPayload(payload) ?? payload, 'running', event.type, occurredAt)
-
-        if (isActiveEvent) {
-          setPetActivity({ reasoning: false, toolRunning: true })
-        }
-      } else if (event.type === 'tool.complete') {
-        if (sessionId) {
-          flushQueuedDeltas(sessionId)
-          upsertToolCall(sessionId, toTodoPayload(payload) ?? payload, 'complete', event.type, occurredAt)
-
-          if (isActiveEvent) {
-            setPetActivity({ toolRunning: false })
-
-            // A tool can fail without ending the turn when the agent recovers
-            // and continues. Surface that failure as a short pet beat too;
-            // otherwise only turn-level errors ever reach the failed state.
-            if (payload?.error) {
-              flashPetActivity({ error: true })
-            }
-          }
-
-          // A pending clarify blocks the turn, so the first tool.complete after
-          // one is the clarify resolving — drop the "needs input" flag here so
-          // the sidebar indicator clears as soon as it's answered, not only at
-          // message.complete.
-          updateSessionState(sessionId, state => (state.needsInput ? { ...state, needsInput: false } : state))
-
-          // terminal/process tool calls are the only things that spawn or reap
-          // background processes — sync the composer status stack right after.
-          if (!sessionInterrupted(sessionId) && (payload?.name === 'terminal' || payload?.name === 'process')) {
-            void refreshBackgroundProcesses(sessionId)
-          }
-        }
-
-        // The agent just created/deleted/renamed a skill, which adds or removes
-        // its `/name` command. Drop the composer's cached `/` list so the new
-        // skill is offerable now rather than after the hour-long TTL — and the
-        // skill-suggestion provider's index with it.
-        if (payload?.name === 'skill_manage') {
-          invalidateSlashCompletions()
-          invalidateSkillSuggestionIndex()
-        }
-
-        // MCP tool outcomes feed the connection-repair suggestion provider:
-        // an auth/connection-shaped failure offers a reconnect pill; a later
-        // success against the same server withdraws it.
-        if (sessionId && typeof payload?.name === 'string' && payload.name.startsWith('mcp__')) {
-          reportMcpToolResult(
-            sessionId,
-            payload.name,
-            Boolean(payload.error),
-            [payload.error, payload.result].filter(part => typeof part === 'string').join(' ')
-          )
-        }
-
-        if (typeof payload?.inline_diff === 'string' && payload.inline_diff.trim()) {
-          recordToolDiff(payload.tool_id || payload.name || '', payload.inline_diff)
-        }
-
-        // A file-mutating tool just finished — nudge the git-mirroring surfaces
-        // (coding rail, review pane, file tree) to refresh. Event-driven, not
-        // polled: fires exactly when the agent touches the tree.
-        if (payload && toolMayMutateFiles(payload)) {
-          notifyWorkspaceChanged(toolChangedPath(payload))
-        }
-      } else if (SUBAGENT_EVENT_TYPES.has(event.type)) {
-        if (sessionId && payload && !sessionInterrupted(sessionId)) {
-          if (!nativeSubagentSessionsRef.current.has(sessionId)) {
-            pruneDelegateFallbackSubagents(sessionId)
-          }
-
-          nativeSubagentSessionsRef.current.add(sessionId)
-          upsertSubagent(
-            sessionId,
-            payload as Record<string, unknown>,
-            event.type === 'subagent.spawn_requested' || event.type === 'subagent.start',
-            event.type
-          )
-        }
-      } else if (event.type === 'clarify.request') {
-        // Surface the clarify tool's overlay. The Python side is blocked on
-        // `clarify.respond`, so without this handler the agent would hang
-        // forever (see tools/clarify_tool.py + tui_gateway/server.py:_block).
-        //
-        // Store the request for whichever session raised it — even a background
-        // one. clarify.request is a one-shot event; if we dropped it for an
-        // unfocused session, that session would block on `clarify.respond`
-        // indefinitely and re-focusing it could never recover (the event is
-        // gone). Parking it per-session lets the user answer once they switch
-        // over; the inline ClarifyTool reads the active session's entry.
-        const requestId = typeof payload?.request_id === 'string' ? payload.request_id : ''
-        const question = typeof payload?.question === 'string' ? payload.question : ''
-        const rawChoices = payload?.choices
-        const choices = normalizeChoices(rawChoices)
-        const multiSelect = payload?.multi_select === true
-        // Batch (multi-question) clarify: `questions` replaces question/choices
-        // on the wire. `answers` rides along only on reconnect replay, carrying
-        // the per-question locks the server already accepted.
-        const questions = normalizeQuestions(payload?.questions)
-
-        const lockedAnswers =
-          typeof payload?.answers === 'object' && payload?.answers !== null
-            ? Object.fromEntries(
-                Object.entries(payload.answers as Record<string, unknown>).filter(
-                  (entry): entry is [string, string] => typeof entry[1] === 'string'
-                )
-              )
-            : undefined
-
-        if (requestId && questions.length > 0) {
-          setClarifyRequest({
-            choices: null,
-            lockedAnswers,
-            multiSelect: false,
-            question: '',
-            questions,
-            requestId,
-            sessionId: sessionId ?? null
-          })
-
-          if (sessionId) {
-            // Same hydration-race guard as the single-question path below: the
-            // form mounts from the tool row, so upsert a stable one keyed by
-            // the request id in case tool.start was missed.
-            upsertToolCall(
-              sessionId,
-              {
-                args: {
-                  questions: questions.map(q => ({
-                    choices: q.choices ?? undefined,
-                    multi_select: q.multiSelect || undefined,
-                    question: q.question
-                  }))
-                },
-                name: 'clarify',
-                tool_id: requestId
-              },
-              'running',
-              event.type,
-              occurredAt
-            )
-            updateSessionState(sessionId, state => ({ ...state, needsInput: true }))
-
-            if (sessionId === activeSessionIdRef.current) {
-              requestScrollToBottom()
-            }
-          }
-
-          dispatchNativeNotification({
-            body: questions.map(q => q.question).join(' · '),
-            kind: 'input',
-            sessionId,
-            title: translateNow('notifications.native.inputTitle')
-          })
-        } else if (requestId && question) {
-          if (rawChoices != null && choices.length === 0) {
-            warnDroppedChoices('gateway', question, rawChoices)
-          }
-
-          setClarifyRequest({
-            requestId,
-            question,
-            choices: choices.length > 0 ? choices : null,
-            multiSelect,
-            sessionId: sessionId ?? null
-          })
-
-          if (sessionId) {
-            // `clarify.request` is the blocking event the Python side waits on,
-            // while the inline UI normally mounts from the earlier `tool.start`
-            // row. If that row was missed (stream reconnect / hydration race) the
-            // sidebar still says "needs input" but there is nowhere to render the
-            // choices. Upsert a stable pending clarify tool row from the request
-            // itself so the prompt stays answerable; a real tool.start/complete
-            // with the same request id merges rather than duplicates.
-            upsertToolCall(
-              sessionId,
-              {
-                args: { choices, ...(multiSelect ? { multi_select: true } : {}), question },
-                name: 'clarify',
-                tool_id: requestId
-              },
-              'running',
-              event.type,
-              occurredAt
-            )
-
-            // The transcript only renders the active session, so a background
-            // clarify is otherwise invisible (the row just keeps spinning like
-            // it's working). Flag the session so the sidebar shows a persistent
-            // "needs input" indicator on its row — works for the active session
-            // too, and survives alt-tab / window blur (unlike a toast).
-            updateSessionState(sessionId, state => ({ ...state, needsInput: true }))
-
-            if (sessionId === activeSessionIdRef.current) {
-              requestScrollToBottom()
-            }
-          }
-
-          dispatchNativeNotification({
-            body: question,
-            kind: 'input',
-            sessionId,
-            title: translateNow('notifications.native.inputTitle')
-          })
-        }
-      } else if (event.type === 'mcp.setup.request') {
-        // setup_mcp tool (desktop GUI): the agent proposed an MCP server and
-        // the Python side is blocked on mcp.setup.respond. Park the request
-        // per-session (like clarify) and upsert a stable pending tool row so
-        // the inline consent card has somewhere to render even when the
-        // tool.start event was missed (stream reconnect / hydration race).
-        const requestId = typeof payload?.request_id === 'string' ? payload.request_id : ''
-        const server = typeof payload?.server === 'string' ? payload.server : ''
-        const rawAction = typeof payload?.action === 'string' ? payload.action : 'install'
-        const action = rawAction === 'enable' || rawAction === 'authorize' ? rawAction : 'install'
-        const reason = typeof payload?.reason === 'string' ? payload.reason : ''
-
-        if (requestId && server) {
-          setMcpSetupRequest({ action, reason, requestId, server, sessionId: sessionId ?? null })
-
-          if (sessionId) {
-            upsertToolCall(
-              sessionId,
-              { args: { action, reason, server }, name: 'setup_mcp', tool_id: requestId },
-              'running'
-            )
-            updateSessionState(sessionId, state => ({ ...state, needsInput: true }))
-          }
-
-          dispatchNativeNotification({
-            body: reason || server,
-            kind: 'input',
-            sessionId,
-            title: translateNow('notifications.native.inputTitle')
-          })
-        }
-      } else if (event.type === 'approval.request') {
-        // Dangerous-command / execute_code approval. The Python side is blocked
-        // in _await_gateway_decision() until approval.respond lands; without
-        // this the agent stalls until its 5-min timeout and the tool is BLOCKED.
-        // Park it per-session (like clarify) so a *background* profile's turn can
-        // raise it and wait — the sidebar flags "needs input" and the inline bar
-        // surfaces once the user focuses that chat.
-        const command = typeof payload?.command === 'string' ? payload.command : ''
-        const description = typeof payload?.description === 'string' ? payload.description : 'dangerous command'
-
-        void receiveApprovalRequest($gateway.get(), {
-          // false only when a tirith warning forbids it; backend omits the field otherwise.
-          allowPermanent: payload?.allow_permanent !== false,
-          choices: Array.isArray(payload?.choices)
-            ? payload.choices.filter(choice => typeof choice === 'string')
-            : undefined,
-          command,
-          description,
-          requestId: typeof payload?.request_id === 'string' ? payload.request_id : undefined,
-          sessionId: sessionId ?? null,
-          smartDenied: payload?.smart_denied === true
-        }).catch(() => undefined)
-
-        if (sessionId) {
-          updateSessionState(sessionId, state => ({ ...state, needsInput: true }))
-        }
-
-        dispatchNativeNotification({
-          actions: [
-            { id: 'approve', text: translateNow('notifications.native.approveAction') },
-            { id: 'reject', text: translateNow('notifications.native.rejectAction') }
-          ],
-          body: command || description,
-          kind: 'approval',
-          sessionId,
-          title: translateNow('notifications.native.approvalTitle')
-        })
-      } else if (event.type === 'sudo.request') {
-        // Sudo password capture (tools/terminal_tool.py). Blocked on
-        // sudo.respond {request_id, password}.
-        const requestId = typeof payload?.request_id === 'string' ? payload.request_id : ''
-
-        if (requestId) {
-          setSudoRequest({ requestId, sessionId: sessionId ?? null })
-
-          if (sessionId) {
-            updateSessionState(sessionId, state => ({ ...state, needsInput: true }))
-          }
-
-          dispatchNativeNotification({
-            body: translateNow('notifications.native.inputBody'),
-            kind: 'input',
-            sessionId,
-            title: translateNow('notifications.native.inputTitle')
-          })
-        }
-      } else if (event.type === 'secret.request') {
-        // Skill credential capture (tools/skills_tool.py). Blocked on
-        // secret.respond {request_id, value}.
-        const requestId = typeof payload?.request_id === 'string' ? payload.request_id : ''
-
-        if (requestId) {
-          const envVar = typeof payload?.env_var === 'string' ? payload.env_var : ''
-          const promptText = typeof payload?.prompt === 'string' ? payload.prompt : ''
-
-          setSecretRequest({
-            requestId,
-            envVar,
-            prompt: promptText,
-            sessionId: sessionId ?? null
-          })
-
-          if (sessionId) {
-            updateSessionState(sessionId, state => ({ ...state, needsInput: true }))
-          }
-
-          dispatchNativeNotification({
-            body: promptText || envVar || translateNow('notifications.native.inputBody'),
-            kind: 'input',
-            sessionId,
-            title: translateNow('notifications.native.inputTitle')
-          })
-        }
-      } else if (event.type === 'terminal.read.request') {
-        // read_terminal tool: serialize the renderer's xterm buffer and answer
-        // immediately (Python blocks on the respond). Empty text = no live pane.
-        const requestId = typeof payload?.request_id === 'string' ? payload.request_id : ''
-
-        if (requestId) {
-          const start = typeof payload?.start === 'number' ? payload.start : undefined
-          const count = typeof payload?.count === 'number' ? payload.count : undefined
-          const result = readActiveTerminal({ start, count })
-
-          void $gateway.get()?.request('terminal.read.respond', {
-            request_id: requestId,
-            text: result ? JSON.stringify(result) : ''
-          })
-        }
-      } else if (event.type === 'preview.read.request') {
-        // read_preview tool: serialize the active preview tab (a Browser
-        // webview's page text is async) and answer. Empty text = nothing open.
-        const requestId = typeof payload?.request_id === 'string' ? payload.request_id : ''
-
-        if (requestId) {
-          const start = typeof payload?.start === 'number' ? payload.start : undefined
-          const count = typeof payload?.count === 'number' ? payload.count : undefined
-
-          void readActivePreview({ count, start }).then(result => {
-            void $gateway.get()?.request('preview.read.respond', {
-              request_id: requestId,
-              text: result ? JSON.stringify(result) : ''
-            })
-          })
-        }
-      } else if (event.type === 'window.read.request') {
-        // read_window_below tool: main owns native window enumeration, so ask
-        // it over IPC and answer. Empty text = unavailable (no bridge, or
-        // enumeration unsupported on this system e.g. Wayland).
-        const requestId = typeof payload?.request_id === 'string' ? payload.request_id : ''
-
-        if (requestId) {
-          const read = window.hermesDesktop?.readWindowBelow
-
-          const answer = (result: unknown) =>
-            $gateway.get()?.request('window.read.respond', {
-              request_id: requestId,
-              text: result ? JSON.stringify(result) : ''
-            })
-
-          // .catch: ipcRenderer.invoke rejects on an older shell without the
-          // handler or a main-side throw — without an empty answer the tool
-          // would stall its full 30s timeout.
-          void Promise.resolve(read ? read() : null).then(answer, () => answer(null))
-        }
-      } else if (event.type === 'agent.terminal.output') {
-        // Live chunk from a background process → its read-only agent terminal tab.
-        writeAgentTerminalChunk(payload?.process_id ?? '', payload?.chunk ?? '')
-      } else if (event.type === 'terminal.close') {
-        // Agent closed its own read-only tab via the desktop-gated close_terminal tool.
-        // The process is untouched — this only drops the view.
-        closeAgentTerminalByProc(payload?.process_id ?? '')
-      } else if (event.type === 'tour.request') {
-        // tour tool: run one guided-tour action (highlight/step/discover) via
-        // driver.js — on the app's own DOM or inside the preview pane's guest
-        // page — and answer with the outcome. Dynamic import keeps driver.js
-        // and the preview injection payload off the boot path. Active session
-        // only: a background turn must never paint overlays on the user's
-        // screen (desktop AGENTS.md: offer, don't hijack).
-        const requestId = typeof payload?.request_id === 'string' ? payload.request_id : ''
-
-        if (requestId) {
-          const answer = (result: unknown) =>
-            $gateway.get()?.request('tour.respond', {
-              request_id: requestId,
-              text: result ? JSON.stringify(result) : ''
-            })
-
-          if (isActiveEvent) {
-            void import('@/lib/tour')
-              .then(({ runTour }) =>
-                runTour(
-                  {
-                    kind: (payload?.action ?? 'stop') as TourAction['kind'],
-                    selector: payload?.selector,
-                    side: payload?.side as TourStep['side'],
-                    startAt: payload?.step_index,
-                    steps: payload?.steps as TourStep[] | undefined,
-                    text: payload?.text,
-                    title: payload?.title
-                  },
-                  payload?.surface === 'preview' ? 'preview' : 'app'
-                )
-              )
-              .then(answer, error =>
-                answer({ error: error instanceof Error ? error.message : String(error), success: false })
-              )
-          } else {
-            void answer({
-              error: 'Tours only run in the session the user is looking at.',
-              success: false
-            })
-          }
-        }
-      } else if (event.type === 'pane.reveal') {
-        // Agent revealed a pane via the desktop-gated focus_pane tool, in
-        // response to an explicit user request. Active session only — a
-        // background turn must never move the user's focus (desktop AGENTS.md:
-        // offer, don't hijack).
-        if (isActiveEvent) {
-          revealDesktopPane(payload?.pane ?? '')
-        }
-      } else if (event.type === 'layout.apply') {
-        // Agent applied a layout preset via the desktop-gated apply_layout
-        // tool. Same contract as pane.reveal: active session only, and the
-        // preset resolves against the SAME layouts registry the picker reads,
-        // so core, plugin, and user presets are all addressable.
-        if (isActiveEvent) {
-          applyDesktopLayoutPreset(typeof payload?.preset === 'string' ? payload.preset : '')
-        }
-      } else if (event.type === 'message.reaction') {
-        // The agent reacted to a message via the desktop-gated
-        // react_to_message tool. Already persisted — this only paints it now
-        // instead of at the next resume. Fresh ChatMessage object per change:
-        // the runtime repository caches normalized ThreadMessages in a WeakMap
-        // keyed by ChatMessage identity.
-        const reactedRowId = payload?.row_id
-
-        if (typeof reactedRowId === 'number') {
-          const nextReactions = Array.isArray(payload?.reactions) ? payload.reactions : []
-          const reactedRole = payload?.role === 'assistant' ? 'assistant' : 'user'
-
-          setMessages(messages => {
-            // Preferred leg: the message already knows its durable row id
-            // (rehydrated transcript, or a live row that has round-tripped).
-            const byRowId = messages.find(message => message.rowId === reactedRowId)
-
-            if (byRowId) {
-              // Overlay survives the end-of-turn resume, which rebuilds from
-              // in-memory history that doesn't carry this mid-turn DB write.
-              recordAgentReaction(reactedRowId, nextReactions)
-
-              return messages.map(message =>
-                message.rowId === reactedRowId ? { ...message, reactions: nextReactions } : message
-              )
-            }
-
-            // Live leg: the targeted message is still optimistic (no rowId —
-            // it hasn't round-tripped through a resume). The agent's default
-            // target is the newest message of that role, so stamp the reaction
-            // AND the now-known row id onto it. Without this the event matches
-            // nothing and the reaction only appears after a reload.
-            const lastIndex = messages.findLastIndex(
-              message => message.role === reactedRole && message.rowId === undefined
-            )
-
-            if (lastIndex === -1) {
-              return messages
-            }
-
-            recordAgentReaction(reactedRowId, nextReactions)
-
-            return messages.map((message, index) =>
-              index === lastIndex ? { ...message, rowId: reactedRowId, reactions: nextReactions } : message
-            )
-          })
-        }
-      } else if (event.type === 'status.update') {
-        if (sessionId && payload?.kind === 'compacting') {
-          setSessionCompacting(sessionId, true)
-          compactedTurnRef.current.add(sessionId)
-        } else if (sessionId && payload?.kind === 'compacted') {
-          setSessionCompacting(sessionId, false)
-          compactedTurnRef.current.delete(sessionId)
-        } else if (sessionId && payload?.kind === 'process') {
-          // The gateway's notification poller announces background process
-          // completions / watch matches here — re-sync the status stack.
-          void refreshBackgroundProcesses(sessionId)
-        } else if (sessionId && payload?.kind === 'goal') {
-          applyGoalStatusText(sessionId, coerceGatewayText(payload?.text))
-        }
-      } else if (event.type === 'review.summary') {
-        // Self-improvement background review saved something to memory/skills
-        // and emitted a persistent summary (Python formats it as
-        // "💾 Self-improvement review: …"). The CLI prints this via
-        // prompt_toolkit and the Ink TUI renders it as a system line; the
-        // desktop has neither, so without this handler the skill/memory
-        // change happens silently. Surface it as a persistent system message
-        // in the transcript so the user is always informed — it must not be a
-        // transient toast that can be missed.
-        //
-        // Typed here with the `review:` marker (same convention as `steer:` /
-        // `slash:`) so SystemMessage can paint it as the memory-write row it
-        // is instead of sniffing the backend's prose. The leading 💾 goes with
-        // it — the row draws its own glyph.
-        const text = coerceGatewayText(payload?.text)
-          .trim()
-          .replace(/^[^\p{L}\p{N}]+/u, '')
-
-        if (text && sessionId) {
-          flushQueuedDeltas(sessionId)
-          updateSessionState(sessionId, state => ({
-            ...state,
-            messages: [
-              ...state.messages,
-              {
-                id: `review-summary-${Date.now()}`,
-                role: 'system',
-                parts: [textPart(`review:${text}`, occurredAt)],
-                timestamp: occurredAt
-              }
-            ]
-          }))
-        }
-      } else if (event.type === 'notification.show') {
-        // Driver-agnostic agent notice (credits usage/grant/depleted/restored
-        // from `agent/credits_tracker.py`). The Ink TUI renders these in its
-        // status bar; the desktop renders them as toasts. The notice key doubles
-        // as the toast id, so the escalating 50→75→90 credits line replaces in
-        // place instead of stacking. Account-wide signal — shown regardless of
-        // which session is focused.
-        const notice = event.payload as AgentNoticePayload | undefined
-
-        showAgentNotice(notice)
-
-        // The urgent pair (access paused / restored) also breaks through as a
-        // native OS notification when Hermes is backgrounded; dispatch is gated
-        // by the user's notification prefs + backgrounded check.
-        const native = nativeNoticeInput(notice, translateNow('notifications.native.creditsTitle'))
-
-        if (native) {
-          dispatchNativeNotification(native)
-        }
-
-        // A credits crossing moves the account balance. Settings → Billing polls
-        // `billing.state` every 30s; nudge it so the page reflects the crossing
-        // immediately instead of up to 30s late.
-        if (notice?.key?.startsWith('credits.')) {
-          void queryClient.invalidateQueries({ queryKey: ['billing', 'state'] })
-        }
-      } else if (event.type === 'notification.clear') {
-        // Key-matched dismissal (e.g. credits restored clears the depleted
-        // notice). notify() keys the toast by the notice key, so this maps
-        // straight to dismissNotification(key).
-        clearAgentNotice((event.payload as AgentNoticePayload | undefined)?.key)
-      } else if (event.type === 'error') {
-        const errorMessage = payload?.message || 'Hermes reported an error'
-        const looksLikeProviderSetup = isProviderSetupErrorMessage(errorMessage)
-
-        // A turn that errors out has also ended — drop any open blocking prompt
-        // for this session so an approval/sudo/secret overlay can't linger past
-        // the failed turn (same intent as the message.complete clear).
-        if (sessionId) {
-          clearAllPrompts(sessionId)
-          clearClarifyRequest(undefined, sessionId)
-          clearActiveSessionTodos(sessionId)
-          setSessionCompacting(sessionId, false)
-          compactedTurnRef.current.delete(sessionId)
-        }
-
-        if (isActiveEvent) {
-          setPetActivity({ reasoning: false, toolRunning: false })
-          flashPetActivity({ error: true })
-        }
-
-        dispatchNativeNotification({
-          body: errorMessage,
-          kind: 'turnError',
-          sessionId,
-          title: translateNow('notifications.native.turnErrorTitle')
-        })
-
-        if (looksLikeProviderSetup) {
-          requestDesktopOnboarding(errorMessage)
-        } else if (isDiskFullErrorMessage(errorMessage)) {
-          notifyError(new Error(errorMessage), translateNow('notifications.errors.diskFull'))
-        } else {
-          // Toast globally, not just when the failing thread is focused: a
-          // turn-ending error (e.g. out of funds) blocks every thread, so the
-          // inline error alone is too easy to miss. The stable id collapses the
-          // same error from multiple blocked threads into one toast.
-          notify({
-            id: `gateway-error:${errorMessage}`,
-            kind: 'error',
-            title: 'Hermes error',
-            message: errorMessage
-          })
-        }
-
-        if (sessionId) {
-          flushQueuedDeltas(sessionId)
-          failAssistantMessage(sessionId, errorMessage, occurredAt)
-        }
-
-        if (isActiveEvent) {
-          setTurnStartedAt(null)
-        }
-      }
-    },
-    [
-      appendAssistantDelta,
-      appendReasoningDelta,
-      activeSessionIdRef,
-      activeGatewayProfile,
-      compactedTurnRef,
-      completeAssistantMessage,
-      failAssistantMessage,
-      finalizeInterimAssistantMessage,
-      flushQueuedDeltas,
-      hydrateFromStoredSession,
-      lastCwdInfoSessionRef,
-      nativeSubagentSessionsRef,
-      queryClient,
-      scheduleConfigRefresh,
-      scheduleSessionsRefresh,
-      sessionInterrupted,
-      sessionStateByRuntimeIdRef,
-      updateSessionState,
-      upsertToolCall
-    ]
-  )
-}
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/desktop-bridge.ts b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/desktop-bridge.ts
new file mode 100644
index 0000000000..dbb0508510
--- /dev/null
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/desktop-bridge.ts
@@ -0,0 +1,217 @@
+import { readActivePreview } from '@/app/chat/right-rail/preview-reader'
+import { writeAgentTerminalChunk } from '@/app/right-sidebar/terminal/agent-terminal-stream'
+import { readActiveTerminal } from '@/app/right-sidebar/terminal/buffer'
+import { closeAgentTerminalByProc } from '@/app/right-sidebar/terminal/terminals'
+import type { TourAction, TourStep } from '@/lib/tour'
+import { $gateway } from '@/store/gateway'
+import { applyDesktopLayoutPreset, revealDesktopPane } from '@/store/pane-focus'
+import { recordAgentReaction } from '@/store/reactions-local'
+import { setMessages } from '@/store/session'
+
+import type { GatewayEventContext } from './types'
+
+/** Desktop-surface bridge events: read-back requests the agent blocks on
+ *  (terminal/preview/window), agent terminal streaming, pane reveal, and
+ *  message reactions. */
+export function handleDesktopBridgeEvent(ctx: GatewayEventContext): boolean {
+  const { event, payload, isActiveEvent } = ctx
+
+  if (event.type === 'terminal.read.request') {
+    // read_terminal tool: serialize the renderer's xterm buffer and answer
+    // immediately (Python blocks on the respond). Empty text = no live pane.
+    const requestId = typeof payload?.request_id === 'string' ? payload.request_id : ''
+
+    if (requestId) {
+      const start = typeof payload?.start === 'number' ? payload.start : undefined
+      const count = typeof payload?.count === 'number' ? payload.count : undefined
+      const result = readActiveTerminal({ start, count })
+
+      void $gateway.get()?.request('terminal.read.respond', {
+        request_id: requestId,
+        text: result ? JSON.stringify(result) : ''
+      })
+    }
+
+    return true
+  }
+
+  if (event.type === 'preview.read.request') {
+    // read_preview tool: serialize the active preview tab (a Browser
+    // webview's page text is async) and answer. Empty text = nothing open.
+    const requestId = typeof payload?.request_id === 'string' ? payload.request_id : ''
+
+    if (requestId) {
+      const start = typeof payload?.start === 'number' ? payload.start : undefined
+      const count = typeof payload?.count === 'number' ? payload.count : undefined
+
+      void readActivePreview({ count, start }).then(result => {
+        void $gateway.get()?.request('preview.read.respond', {
+          request_id: requestId,
+          text: result ? JSON.stringify(result) : ''
+        })
+      })
+    }
+
+    return true
+  }
+
+  if (event.type === 'window.read.request') {
+    // read_window_below tool: main owns native window enumeration, so ask
+    // it over IPC and answer. Empty text = unavailable (no bridge, or
+    // enumeration unsupported on this system e.g. Wayland).
+    const requestId = typeof payload?.request_id === 'string' ? payload.request_id : ''
+
+    if (requestId) {
+      const read = window.hermesDesktop?.readWindowBelow
+
+      const answer = (result: unknown) =>
+        $gateway.get()?.request('window.read.respond', {
+          request_id: requestId,
+          text: result ? JSON.stringify(result) : ''
+        })
+
+      // .catch: ipcRenderer.invoke rejects on an older shell without the
+      // handler or a main-side throw — without an empty answer the tool
+      // would stall its full 30s timeout.
+      void Promise.resolve(read ? read() : null).then(answer, () => answer(null))
+    }
+
+    return true
+  }
+
+  if (event.type === 'agent.terminal.output') {
+    // Live chunk from a background process → its read-only agent terminal tab.
+    writeAgentTerminalChunk(payload?.process_id ?? '', payload?.chunk ?? '')
+
+    return true
+  }
+
+  if (event.type === 'terminal.close') {
+    // Agent closed its own read-only tab via the desktop-gated close_terminal tool.
+    // The process is untouched — this only drops the view.
+    closeAgentTerminalByProc(payload?.process_id ?? '')
+
+    return true
+  }
+
+  if (event.type === 'tour.request') {
+    // tour tool: run one guided-tour action (highlight/step/discover) via
+    // driver.js — on the app's own DOM or inside the preview pane's guest
+    // page — and answer with the outcome. Dynamic import keeps driver.js
+    // and the preview injection payload off the boot path. Active session
+    // only: a background turn must never paint overlays on the user's
+    // screen (desktop AGENTS.md: offer, don't hijack).
+    const requestId = typeof payload?.request_id === 'string' ? payload.request_id : ''
+
+    if (requestId) {
+      const answer = (result: unknown) =>
+        $gateway.get()?.request('tour.respond', {
+          request_id: requestId,
+          text: result ? JSON.stringify(result) : ''
+        })
+
+      if (isActiveEvent) {
+        void import('@/lib/tour')
+          .then(({ runTour }) =>
+            runTour(
+              {
+                kind: (payload?.action ?? 'stop') as TourAction['kind'],
+                selector: payload?.selector,
+                side: payload?.side as TourStep['side'],
+                startAt: payload?.step_index,
+                steps: payload?.steps as TourStep[] | undefined,
+                text: payload?.text,
+                title: payload?.title
+              },
+              payload?.surface === 'preview' ? 'preview' : 'app'
+            )
+          )
+          .then(answer, error =>
+            answer({ error: error instanceof Error ? error.message : String(error), success: false })
+          )
+      } else {
+        void answer({
+          error: 'Tours only run in the session the user is looking at.',
+          success: false
+        })
+      }
+    }
+
+    return true
+  }
+
+  if (event.type === 'pane.reveal') {
+    // Agent revealed a pane via the desktop-gated focus_pane tool, in
+    // response to an explicit user request. Active session only — a
+    // background turn must never move the user's focus (desktop AGENTS.md:
+    // offer, don't hijack).
+    if (isActiveEvent) {
+      revealDesktopPane(payload?.pane ?? '')
+    }
+
+    return true
+  }
+
+  if (event.type === 'layout.apply') {
+    // Agent applied a layout preset via the desktop-gated apply_layout
+    // tool. Same contract as pane.reveal: active session only, and the
+    // preset resolves against the SAME layouts registry the picker reads,
+    // so core, plugin, and user presets are all addressable.
+    if (isActiveEvent) {
+      applyDesktopLayoutPreset(typeof payload?.preset === 'string' ? payload.preset : '')
+    }
+
+    return true
+  }
+
+  if (event.type === 'message.reaction') {
+    // The agent reacted to a message via the desktop-gated
+    // react_to_message tool. Already persisted — this only paints it now
+    // instead of at the next resume. Fresh ChatMessage object per change:
+    // the runtime repository caches normalized ThreadMessages in a WeakMap
+    // keyed by ChatMessage identity.
+    const reactedRowId = payload?.row_id
+
+    if (typeof reactedRowId === 'number') {
+      const nextReactions = Array.isArray(payload?.reactions) ? payload.reactions : []
+      const reactedRole = payload?.role === 'assistant' ? 'assistant' : 'user'
+
+      setMessages(messages => {
+        // Preferred leg: the message already knows its durable row id
+        // (rehydrated transcript, or a live row that has round-tripped).
+        const byRowId = messages.find(message => message.rowId === reactedRowId)
+
+        if (byRowId) {
+          // Overlay survives the end-of-turn resume, which rebuilds from
+          // in-memory history that doesn't carry this mid-turn DB write.
+          recordAgentReaction(reactedRowId, nextReactions)
+
+          return messages.map(message =>
+            message.rowId === reactedRowId ? { ...message, reactions: nextReactions } : message
+          )
+        }
+
+        // Live leg: the targeted message is still optimistic (no rowId —
+        // it hasn't round-tripped through a resume). The agent's default
+        // target is the newest message of that role, so stamp the reaction
+        // AND the now-known row id onto it. Without this the event matches
+        // nothing and the reaction only appears after a reload.
+        const lastIndex = messages.findLastIndex(message => message.role === reactedRole && message.rowId === undefined)
+
+        if (lastIndex === -1) {
+          return messages
+        }
+
+        recordAgentReaction(reactedRowId, nextReactions)
+
+        return messages.map((message, index) =>
+          index === lastIndex ? { ...message, rowId: reactedRowId, reactions: nextReactions } : message
+        )
+      })
+    }
+
+    return true
+  }
+
+  return false
+}
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/index.ts b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/index.ts
new file mode 100644
index 0000000000..693a03696e
--- /dev/null
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/index.ts
@@ -0,0 +1,264 @@
+import { registryBackendScopeKey } from '@hermes/shared'
+import { useCallback, useEffect, useRef } from 'react'
+
+import type { GatewayEventPayload } from '@/lib/chat-messages'
+import {
+  approvalReplaySessionId,
+  resolveGatewayEventSessionId,
+  UNSCOPED_STREAM_EVENT_TYPES
+} from '@/lib/gateway-events'
+import { setSessionCompacting } from '@/store/compaction'
+import { $gateway, activeGatewayConnectionId } from '@/store/gateway'
+import { $activeGatewayProfile, normalizeProfileKey } from '@/store/profile'
+import { replayPendingApproval } from '@/store/prompts'
+import { setSessionProviderWait } from '@/store/provider-wait'
+import { setSessionDraftingTool } from '@/store/tool-drafting'
+import type { RpcEvent } from '@/types/hermes'
+
+import { handleDesktopBridgeEvent } from './desktop-bridge'
+import { handleInputRequestEvent } from './input-requests'
+import { handleLifecycleEvent } from './lifecycle'
+import { handleMessageStreamEvent } from './message-stream'
+import { handleSessionInfoEvent } from './session-info'
+import { handleStatusEvent } from './status'
+import { handleToolEvent } from './tools'
+import type { GatewayEventContext, GatewayEventDeps, GatewayEventHandler } from './types'
+
+export type { GatewayEventDeps } from './types'
+
+/**
+ * Events that retire a "drafting a tool call" claim.
+ *
+ * `tool.generating` opens the claim and nothing closes it — a draft can be
+ * abandoned without ever reaching `tool.start`, so enumerating the ways one
+ * *ends* left the label on screen for the rest of the turn. Inverted: the
+ * claim only covers what the model is emitting right now, and any other output
+ * from the session proves it moved on. Same rule the TUI applies to its
+ * transient trail lines (`turnController.pruneTransient`).
+ */
+const DRAFT_SUPERSEDING_EVENT_TYPES = new Set([
+  'error',
+  'message.complete',
+  'message.delta',
+  'message.start',
+  'reasoning.delta',
+  'thinking.delta',
+  'tool.complete',
+  'tool.progress',
+  'tool.start'
+])
+
+const COMPACTION_RESUME_EVENT_TYPES = new Set([
+  'message.delta',
+  'message.interim',
+  'thinking.delta',
+  'reasoning.delta',
+  'reasoning.available',
+  'moa.reference',
+  'moa.aggregating',
+  'moa.progress',
+  'moa.phase',
+  'tool.start',
+  'tool.progress',
+  'tool.generating',
+  'tool.complete'
+])
+
+const PROVIDER_WAIT_SUPERSEDING_EVENT_TYPES = new Set([
+  'error',
+  'message.complete',
+  'message.delta',
+  'message.interim',
+  'message.start',
+  'reasoning.available',
+  'reasoning.delta',
+  'tool.complete',
+  'tool.generating',
+  'tool.progress',
+  'tool.start'
+])
+
+// Ordered family handlers; each consumes its own event types and reports
+// whether it did, so dispatch stops at the first taker.
+const HANDLERS: GatewayEventHandler[] = [
+  handleLifecycleEvent,
+  handleSessionInfoEvent,
+  handleMessageStreamEvent,
+  handleToolEvent,
+  handleInputRequestEvent,
+  handleDesktopBridgeEvent,
+  handleStatusEvent
+]
+
+/** The gateway-event dispatcher, extracted from useMessageStream. */
+export function useGatewayEventHandler(deps: GatewayEventDeps) {
+  const { activeSessionIdRef, compactedTurnRef, refreshHermesConfig, sessionStateByRuntimeIdRef } = deps
+
+  const unscopedStreamSessionIdRef = useRef<string | null>(null)
+
+  // session.info arrives in bursts (agent build ready + turn end + title /
+  // MCP / compress edges within the same second). Each used to fire its own
+  // refreshHermesConfig — two REST calls (config + defaults) per event, per
+  // turn, including for BACKGROUND sessions whose values the fetch can't even
+  // apply. Coalesce to one trailing fetch per burst; the caller gates on
+  // `apply` so background traffic doesn't schedule anything.
+  const configRefreshTimerRef = useRef<null | number>(null)
+
+  const scheduleConfigRefresh = useCallback(() => {
+    if (configRefreshTimerRef.current !== null) {
+      return
+    }
+
+    if (typeof window === 'undefined') {
+      void refreshHermesConfig()
+
+      return
+    }
+
+    configRefreshTimerRef.current = window.setTimeout(() => {
+      configRefreshTimerRef.current = null
+      void refreshHermesConfig()
+    }, 300)
+  }, [refreshHermesConfig])
+
+  useEffect(
+    () => () => {
+      if (configRefreshTimerRef.current !== null && typeof window !== 'undefined') {
+        window.clearTimeout(configRefreshTimerRef.current)
+        configRefreshTimerRef.current = null
+      }
+    },
+    []
+  )
+
+  return useCallback(
+    (event: RpcEvent) => {
+      const payload = event.payload as GatewayEventPayload | undefined
+
+      // "From the active profile" must mean "from the active SOURCE": every
+      // registered connection exposes a 'default' profile, so a bare profile
+      // comparison attributes gateway B's 'default' events to gateway A's
+      // 'default'. Compare the composite (connectionId, profile) scope with
+      // registryBackendScopeKey — untagged primary events keep the legacy
+      // bare-profile behavior byte-identical.
+      const fromActiveSource = (): boolean =>
+        (!event.profile || normalizeProfileKey(event.profile) === normalizeProfileKey($activeGatewayProfile.get())) &&
+        registryBackendScopeKey(event.connectionId ?? null, event.profile ?? null) ===
+          registryBackendScopeKey(activeGatewayConnectionId(), event.profile ?? null)
+
+      const occurredAt =
+        typeof payload?.timestamp === 'number' && Number.isFinite(payload.timestamp)
+          ? payload.timestamp
+          : Date.now() / 1000
+
+      const explicitSid = event.session_id || ''
+
+      const route = resolveGatewayEventSessionId({
+        activeSessionId: activeSessionIdRef.current,
+        eventType: event.type,
+        explicitSessionId: explicitSid,
+        unscopedStreamSessionId: unscopedStreamSessionIdRef.current
+      })
+
+      unscopedStreamSessionIdRef.current = route.nextUnscopedStreamSessionId
+
+      if (route.drop) {
+        return
+      }
+
+      const sessionId = route.sessionId
+
+      // Late stragglers: an unscoped stream event attributed via the
+      // active-session fallback (no pin) to a session that has no live turn
+      // belongs to a turn that already ended elsewhere. Dropping it keeps the
+      // previous session's tail events (a delayed `thinking.delta` or
+      // `status.update`) from landing in a freshly opened chat (#43142 family:
+      // busy/streaming UI inherited when switching sessions).
+      if (
+        sessionId &&
+        !explicitSid &&
+        !route.pinned &&
+        event.type &&
+        event.type !== 'message.start' &&
+        UNSCOPED_STREAM_EVENT_TYPES.has(event.type)
+      ) {
+        const state = sessionStateByRuntimeIdRef.current.get(sessionId)
+
+        const hasLiveTurn = Boolean(
+          state && (state.awaitingResponse || state.busy || state.streamId || state.sawAssistantPayload)
+        )
+
+        if (!hasLiveTurn) {
+          return
+        }
+      }
+
+      const isActiveEvent = !!sessionId && sessionId === activeSessionIdRef.current
+
+      const replaySessionId = approvalReplaySessionId(event.type, activeSessionIdRef.current, sessionId)
+
+      if (replaySessionId) {
+        void replayPendingApproval($gateway.get(), replaySessionId).catch(() => undefined)
+      }
+
+      // Mid-turn compaction does not emit another message.start. The first
+      // model output or tool event proves summarization has finished and the
+      // turn has resumed, so retire the phase label without waiting for the
+      // whole turn to complete.
+      if (sessionId && COMPACTION_RESUME_EVENT_TYPES.has(event.type) && compactedTurnRef.current.has(sessionId)) {
+        setSessionCompacting(sessionId, false)
+      }
+
+      if (sessionId && DRAFT_SUPERSEDING_EVENT_TYPES.has(event.type)) {
+        setSessionDraftingTool(sessionId, '')
+      }
+
+      if (sessionId && PROVIDER_WAIT_SUPERSEDING_EVENT_TYPES.has(event.type)) {
+        setSessionProviderWait(sessionId, '')
+      }
+
+      const ctx: GatewayEventContext = {
+        deps,
+        event,
+        payload,
+        sessionId,
+        explicitSid,
+        isActiveEvent,
+        occurredAt,
+        fromActiveSource,
+        scheduleConfigRefresh
+      }
+
+      for (const handler of HANDLERS) {
+        if (handler(ctx)) {
+          return
+        }
+      }
+    },
+    // The deps object is rebuilt by the caller each render, but every field it
+    // carries is stable (refs, useCallback-wrapped fns, queryClient), so
+    // depending on the individual fields keeps the handler identity stable.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [
+      deps.appendAssistantDelta,
+      deps.appendReasoningDelta,
+      deps.activeSessionIdRef,
+      deps.activeGatewayProfile,
+      deps.compactedTurnRef,
+      deps.completeAssistantMessage,
+      deps.failAssistantMessage,
+      deps.finalizeInterimAssistantMessage,
+      deps.flushQueuedDeltas,
+      deps.hydrateFromStoredSession,
+      deps.lastCwdInfoSessionRef,
+      deps.nativeSubagentSessionsRef,
+      deps.queryClient,
+      scheduleConfigRefresh,
+      deps.scheduleSessionsRefresh,
+      deps.sessionInterrupted,
+      deps.sessionStateByRuntimeIdRef,
+      deps.updateSessionState,
+      deps.upsertToolCall
+    ]
+  )
+}
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/input-requests.ts b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/input-requests.ts
new file mode 100644
index 0000000000..a227d11f25
--- /dev/null
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/input-requests.ts
@@ -0,0 +1,280 @@
+import { translateNow } from '@/i18n'
+import { normalizeChoices, normalizeQuestions, setClarifyRequest, warnDroppedChoices } from '@/store/clarify'
+import { $gateway } from '@/store/gateway'
+import { setMcpSetupRequest } from '@/store/mcp-setup'
+import { dispatchNativeNotification } from '@/store/native-notifications'
+import { receiveApprovalRequest, setSecretRequest, setSudoRequest } from '@/store/prompts'
+import { requestScrollToBottom } from '@/store/thread-scroll'
+
+import type { GatewayEventContext } from './types'
+
+/** The blocking-input family: clarify / MCP setup consent / approval / sudo /
+ *  secret requests. The Python side is blocked on the matching *.respond, so
+ *  each of these must be parked per-session and surfaced. */
+export function handleInputRequestEvent(ctx: GatewayEventContext): boolean {
+  const { deps, event, payload, sessionId, occurredAt } = ctx
+  const { activeSessionIdRef, updateSessionState, upsertToolCall } = deps
+
+  if (event.type === 'clarify.request') {
+    // Surface the clarify tool's overlay. The Python side is blocked on
+    // `clarify.respond`, so without this handler the agent would hang
+    // forever (see tools/clarify_tool.py + tui_gateway/server.py:_block).
+    //
+    // Store the request for whichever session raised it — even a background
+    // one. clarify.request is a one-shot event; if we dropped it for an
+    // unfocused session, that session would block on `clarify.respond`
+    // indefinitely and re-focusing it could never recover (the event is
+    // gone). Parking it per-session lets the user answer once they switch
+    // over; the inline ClarifyTool reads the active session's entry.
+    const requestId = typeof payload?.request_id === 'string' ? payload.request_id : ''
+    const question = typeof payload?.question === 'string' ? payload.question : ''
+    const rawChoices = payload?.choices
+    const choices = normalizeChoices(rawChoices)
+    const multiSelect = payload?.multi_select === true
+    // Batch (multi-question) clarify: `questions` replaces question/choices
+    // on the wire. `answers` rides along only on reconnect replay, carrying
+    // the per-question locks the server already accepted.
+    const questions = normalizeQuestions(payload?.questions)
+
+    const lockedAnswers =
+      typeof payload?.answers === 'object' && payload?.answers !== null
+        ? Object.fromEntries(
+            Object.entries(payload.answers as Record<string, unknown>).filter(
+              (entry): entry is [string, string] => typeof entry[1] === 'string'
+            )
+          )
+        : undefined
+
+    if (requestId && questions.length > 0) {
+      setClarifyRequest({
+        choices: null,
+        lockedAnswers,
+        multiSelect: false,
+        question: '',
+        questions,
+        requestId,
+        sessionId: sessionId ?? null
+      })
+
+      if (sessionId) {
+        // Same hydration-race guard as the single-question path below: the
+        // form mounts from the tool row, so upsert a stable one keyed by
+        // the request id in case tool.start was missed.
+        upsertToolCall(
+          sessionId,
+          {
+            args: {
+              questions: questions.map(q => ({
+                choices: q.choices ?? undefined,
+                multi_select: q.multiSelect || undefined,
+                question: q.question
+              }))
+            },
+            name: 'clarify',
+            tool_id: requestId
+          },
+          'running',
+          event.type,
+          occurredAt
+        )
+        updateSessionState(sessionId, state => ({ ...state, needsInput: true }))
+
+        if (sessionId === activeSessionIdRef.current) {
+          requestScrollToBottom()
+        }
+      }
+
+      dispatchNativeNotification({
+        body: questions.map(q => q.question).join(' · '),
+        kind: 'input',
+        sessionId,
+        title: translateNow('notifications.native.inputTitle')
+      })
+    } else if (requestId && question) {
+      if (rawChoices != null && choices.length === 0) {
+        warnDroppedChoices('gateway', question, rawChoices)
+      }
+
+      setClarifyRequest({
+        requestId,
+        question,
+        choices: choices.length > 0 ? choices : null,
+        multiSelect,
+        sessionId: sessionId ?? null
+      })
+
+      if (sessionId) {
+        // `clarify.request` is the blocking event the Python side waits on,
+        // while the inline UI normally mounts from the earlier `tool.start`
+        // row. If that row was missed (stream reconnect / hydration race) the
+        // sidebar still says "needs input" but there is nowhere to render the
+        // choices. Upsert a stable pending clarify tool row from the request
+        // itself so the prompt stays answerable; a real tool.start/complete
+        // with the same request id merges rather than duplicates.
+        upsertToolCall(
+          sessionId,
+          {
+            args: { choices, ...(multiSelect ? { multi_select: true } : {}), question },
+            name: 'clarify',
+            tool_id: requestId
+          },
+          'running',
+          event.type,
+          occurredAt
+        )
+
+        // The transcript only renders the active session, so a background
+        // clarify is otherwise invisible (the row just keeps spinning like
+        // it's working). Flag the session so the sidebar shows a persistent
+        // "needs input" indicator on its row — works for the active session
+        // too, and survives alt-tab / window blur (unlike a toast).
+        updateSessionState(sessionId, state => ({ ...state, needsInput: true }))
+
+        if (sessionId === activeSessionIdRef.current) {
+          requestScrollToBottom()
+        }
+      }
+
+      dispatchNativeNotification({
+        body: question,
+        kind: 'input',
+        sessionId,
+        title: translateNow('notifications.native.inputTitle')
+      })
+    }
+
+    return true
+  }
+
+  if (event.type === 'mcp.setup.request') {
+    // setup_mcp tool (desktop GUI): the agent proposed an MCP server and
+    // the Python side is blocked on mcp.setup.respond. Park the request
+    // per-session (like clarify) and upsert a stable pending tool row so
+    // the inline consent card has somewhere to render even when the
+    // tool.start event was missed (stream reconnect / hydration race).
+    const requestId = typeof payload?.request_id === 'string' ? payload.request_id : ''
+    const server = typeof payload?.server === 'string' ? payload.server : ''
+    const rawAction = typeof payload?.action === 'string' ? payload.action : 'install'
+    const action = rawAction === 'enable' || rawAction === 'authorize' ? rawAction : 'install'
+    const reason = typeof payload?.reason === 'string' ? payload.reason : ''
+
+    if (requestId && server) {
+      setMcpSetupRequest({ action, reason, requestId, server, sessionId: sessionId ?? null })
+
+      if (sessionId) {
+        upsertToolCall(
+          sessionId,
+          { args: { action, reason, server }, name: 'setup_mcp', tool_id: requestId },
+          'running'
+        )
+        updateSessionState(sessionId, state => ({ ...state, needsInput: true }))
+      }
+
+      dispatchNativeNotification({
+        body: reason || server,
+        kind: 'input',
+        sessionId,
+        title: translateNow('notifications.native.inputTitle')
+      })
+    }
+
+    return true
+  }
+
+  if (event.type === 'approval.request') {
+    // Dangerous-command / execute_code approval. The Python side is blocked
+    // in _await_gateway_decision() until approval.respond lands; without
+    // this the agent stalls until its 5-min timeout and the tool is BLOCKED.
+    // Park it per-session (like clarify) so a *background* profile's turn can
+    // raise it and wait — the sidebar flags "needs input" and the inline bar
+    // surfaces once the user focuses that chat.
+    const command = typeof payload?.command === 'string' ? payload.command : ''
+    const description = typeof payload?.description === 'string' ? payload.description : 'dangerous command'
+
+    void receiveApprovalRequest($gateway.get(), {
+      // false only when a tirith warning forbids it; backend omits the field otherwise.
+      allowPermanent: payload?.allow_permanent !== false,
+      choices: Array.isArray(payload?.choices)
+        ? payload.choices.filter(choice => typeof choice === 'string')
+        : undefined,
+      command,
+      description,
+      requestId: typeof payload?.request_id === 'string' ? payload.request_id : undefined,
+      sessionId: sessionId ?? null,
+      smartDenied: payload?.smart_denied === true
+    }).catch(() => undefined)
+
+    if (sessionId) {
+      updateSessionState(sessionId, state => ({ ...state, needsInput: true }))
+    }
+
+    dispatchNativeNotification({
+      actions: [
+        { id: 'approve', text: translateNow('notifications.native.approveAction') },
+        { id: 'reject', text: translateNow('notifications.native.rejectAction') }
+      ],
+      body: command || description,
+      kind: 'approval',
+      sessionId,
+      title: translateNow('notifications.native.approvalTitle')
+    })
+
+    return true
+  }
+
+  if (event.type === 'sudo.request') {
+    // Sudo password capture (tools/terminal_tool.py). Blocked on
+    // sudo.respond {request_id, password}.
+    const requestId = typeof payload?.request_id === 'string' ? payload.request_id : ''
+
+    if (requestId) {
+      setSudoRequest({ requestId, sessionId: sessionId ?? null })
+
+      if (sessionId) {
+        updateSessionState(sessionId, state => ({ ...state, needsInput: true }))
+      }
+
+      dispatchNativeNotification({
+        body: translateNow('notifications.native.inputBody'),
+        kind: 'input',
+        sessionId,
+        title: translateNow('notifications.native.inputTitle')
+      })
+    }
+
+    return true
+  }
+
+  if (event.type === 'secret.request') {
+    // Skill credential capture (tools/skills_tool.py). Blocked on
+    // secret.respond {request_id, value}.
+    const requestId = typeof payload?.request_id === 'string' ? payload.request_id : ''
+
+    if (requestId) {
+      const envVar = typeof payload?.env_var === 'string' ? payload.env_var : ''
+      const promptText = typeof payload?.prompt === 'string' ? payload.prompt : ''
+
+      setSecretRequest({
+        requestId,
+        envVar,
+        prompt: promptText,
+        sessionId: sessionId ?? null
+      })
+
+      if (sessionId) {
+        updateSessionState(sessionId, state => ({ ...state, needsInput: true }))
+      }
+
+      dispatchNativeNotification({
+        body: promptText || envVar || translateNow('notifications.native.inputBody'),
+        kind: 'input',
+        sessionId,
+        title: translateNow('notifications.native.inputTitle')
+      })
+    }
+
+    return true
+  }
+
+  return false
+}
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/lifecycle.ts b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/lifecycle.ts
new file mode 100644
index 0000000000..a5df27ced1
--- /dev/null
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/lifecycle.ts
@@ -0,0 +1,102 @@
+import type { HermesSkin } from '@hermes/shared/skin'
+
+import {
+  notifyCronChanged,
+  notifyPairingChanged,
+  notifyPetChanged,
+  notifyPlatformsChanged,
+  notifySessionsChanged,
+  type PetChangeMeta,
+  setChangeEventsAvailable
+} from '@/store/live-sync'
+import { dropSessionState, unbindTileRuntime } from '@/store/session-states'
+// Leaf import (not the `@/themes` barrel) to avoid pulling the ThemeProvider
+// module graph into the gateway event hot path.
+import { ingestBackendSkin } from '@/themes/backend-sync'
+
+import type { GatewayEventContext } from './types'
+
+/** gateway.ready / skin.changed / change-watcher broadcasts / session.reclaimed. */
+export function handleLifecycleEvent(ctx: GatewayEventContext): boolean {
+  const { deps, event, payload, fromActiveSource } = ctx
+
+  if (event.type === 'gateway.ready') {
+    // Seed the active skin into the desktop theme registry without applying,
+    // so a fresh connect never overrides the user's persisted desktop theme.
+    ingestBackendSkin((payload as { skin?: HermesSkin } | undefined)?.skin, { apply: false })
+    // Backends with the change watcher broadcast pet/cron/sessions change
+    // events; consumers demote their legacy polls to slow backstops.
+    setChangeEventsAvailable(Boolean((payload as { change_events?: boolean } | undefined)?.change_events))
+
+    return true
+  }
+
+  if (event.type === 'skin.changed') {
+    // A runtime skin switch (Hermes activating an authored skin, or `/skin`
+    // on another surface). Only the active source+profile's change repaints.
+    if (fromActiveSource()) {
+      ingestBackendSkin(payload as HermesSkin | undefined, { apply: true })
+    }
+
+    return true
+  }
+
+  if (
+    event.type === 'pet.changed' ||
+    event.type === 'cron.changed' ||
+    event.type === 'sessions.changed' ||
+    event.type === 'platforms.changed' ||
+    event.type === 'pairing.changed'
+  ) {
+    // Change-watcher broadcasts (server._broadcast_watched_changes): the
+    // backend's on-disk signature moved. Route to the live-sync ticks the
+    // former pollers now subscribe to. Only the active source+profile's
+    // changes apply — background profile sockets (and other connections'
+    // gateways) watch their own homes.
+    if (fromActiveSource()) {
+      if (event.type === 'pet.changed') {
+        notifyPetChanged(payload as PetChangeMeta | undefined)
+      } else if (event.type === 'cron.changed') {
+        notifyCronChanged()
+      } else if (event.type === 'platforms.changed') {
+        notifyPlatformsChanged()
+      } else if (event.type === 'pairing.changed') {
+        notifyPairingChanged()
+      } else {
+        notifySessionsChanged()
+      }
+    }
+
+    return true
+  }
+
+  if (event.type === 'session.reclaimed') {
+    // The backend reclaimed a live session we may still be holding (idle
+    // TTL, LRU cap, or the WS-orphan reap). Without this the runtime id
+    // stays cached until something fails against it, which reads as the
+    // session vanishing rather than being reclaimed. Drop the cached state
+    // now — the stored row is untouched, so the sidebar keeps the
+    // conversation and reopening it resumes from the DB.
+    const reclaimedRuntimeId = String((payload as { session_id?: string } | undefined)?.session_id ?? '')
+
+    if (reclaimedRuntimeId) {
+      dropSessionState(reclaimedRuntimeId)
+      // A tile bound to the reclaimed runtime would otherwise render an
+      // empty transcript forever: its view reads $sessionStates[runtime]
+      // (just dropped) and its resume effect is gated on !runtimeId, so a
+      // bound tile never re-resumes (#82620). Unbind it so the effect
+      // refires against the intact stored session — and purge the wiring
+      // cache's entry, or resumeTile's warm path would hand the dead
+      // runtime straight back instead of cold-resuming a live one.
+      unbindTileRuntime(reclaimedRuntimeId)
+      deps.sessionStateByRuntimeIdRef.current.delete(reclaimedRuntimeId)
+    }
+
+    // The row's ended_at moved, so refresh the lists that render it.
+    notifySessionsChanged()
+
+    return true
+  }
+
+  return false
+}
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/message-stream.ts b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/message-stream.ts
new file mode 100644
index 0000000000..5efba27561
--- /dev/null
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/message-stream.ts
@@ -0,0 +1,392 @@
+import type { BillingBlock } from '@hermes/shared'
+
+import { burstVibeHearts } from '@/components/chat/vibe-hearts'
+import { translateNow } from '@/i18n'
+import { coerceGatewayText, coerceThinkingText } from '@/lib/chat-runtime'
+import { playCompletionSound } from '@/lib/completion-sound'
+import { triggerHaptic } from '@/lib/haptics'
+import { billingCtaLabel, clearBillingBlock, runBillingRecovery, setBillingBlock } from '@/store/billing-block'
+import { clearClarifyRequest } from '@/store/clarify'
+import { setSessionCompacting } from '@/store/compaction'
+import { notify } from '@/store/notifications'
+import { flashPetActivity, markPetUnread, setPetActivity } from '@/store/pet'
+import { clearAllPrompts } from '@/store/prompts'
+import { providerWaitText, setSessionProviderWait } from '@/store/provider-wait'
+import { setCurrentUsage, setTurnStartedAt } from '@/store/session'
+import { pruneFinishedSessionSubagents } from '@/store/subagents'
+import { clearActiveSessionTodos } from '@/store/todos'
+
+import type { GatewayEventContext } from './types'
+
+function firstBillingLine(text: string): string {
+  return (text || '').split('\n')[0]?.trim() ?? ''
+}
+
+/**
+ * A turn failed on a billing wall (out of credits / payment required). The
+ * gateway forwards the structured descriptor built by `agent/billing_links.py`;
+ * we cache it per-session (drives the in-chat banner) AND raise one sticky,
+ * billing-specific toast — never the generic "Hermes error" — with a smart CTA
+ * (Nous → in-app Settings → Billing, other providers → their billing page).
+ */
+function surfaceBillingBlock(sessionId: string, raw: unknown): void {
+  if (!raw || typeof raw !== 'object') {
+    return
+  }
+
+  const block = raw as BillingBlock
+
+  if (typeof block.provider !== 'string') {
+    return
+  }
+
+  setBillingBlock(sessionId, block)
+
+  const ctaCopy = {
+    addCredits: translateNow('billingBlock.addCredits'),
+    openBilling: translateNow('billingBlock.openBilling')
+  }
+
+  notify({
+    // Collapse repeat walls from the same provider into one toast.
+    id: `billing-block:${block.provider}`,
+    kind: 'warning',
+    icon: 'credit-card',
+    title: block.is_nous
+      ? translateNow('billingBlock.titleNous')
+      : translateNow('billingBlock.titleProvider', block.provider_label),
+    message: firstBillingLine(block.message) || translateNow('billingBlock.fallbackMessage'),
+    // Sticky: a credit wall blocks every turn until resolved.
+    durationMs: 0,
+    action: { label: billingCtaLabel(block, ctaCopy), onClick: () => runBillingRecovery(block) }
+  })
+}
+
+/** The message/reasoning/MoA streaming family: message.start → deltas →
+ *  interim → complete, thinking/reasoning deltas, moa.* progress, reaction. */
+export function handleMessageStreamEvent(ctx: GatewayEventContext): boolean {
+  const { deps, event, payload, sessionId, isActiveEvent, occurredAt } = ctx
+
+  const {
+    appendAssistantDelta,
+    appendReasoningDelta,
+    compactedTurnRef,
+    completeAssistantMessage,
+    finalizeInterimAssistantMessage,
+    flushQueuedDeltas,
+    nativeSubagentSessionsRef,
+    sessionStateByRuntimeIdRef,
+    updateSessionState
+  } = deps
+
+  if (event.type === 'message.start') {
+    if (!sessionId) {
+      return true
+    }
+
+    flushQueuedDeltas(sessionId)
+    pruneFinishedSessionSubagents(sessionId)
+    setSessionCompacting(sessionId, false)
+    compactedTurnRef.current.delete(sessionId)
+    nativeSubagentSessionsRef.current.delete(sessionId)
+    // A fresh turn on this session optimistically clears its billing wall;
+    // if credits are still exhausted the next failure re-raises it.
+    clearBillingBlock(sessionId)
+
+    if (isActiveEvent) {
+      triggerHaptic('streamStart')
+    }
+
+    // Submit→accept latency: seedOptimistic armed the clock at Enter; this
+    // event is the backend accepting the turn. Debug-only visibility into
+    // how long the arm actually took (the "no progress box for seconds"
+    // complaint) — reads the pre-update cache, costs nothing when clean.
+    const seededAt = sessionStateByRuntimeIdRef.current.get(sessionId)?.turnStartedAt
+
+    if (typeof seededAt === 'number') {
+      console.debug('[turn-accept-latency]', { sessionId, ms: Date.now() - seededAt })
+    }
+
+    updateSessionState(sessionId, state => {
+      // If the user clicked Stop (cancelRun set interrupted=true), don't
+      // let a stale message.start from a chained turn (goal follow-up,
+      // completion drain) or an in-flight LLM response re-arm busy.
+      // The interrupt is user intent — the backend's cooperative cancel
+      // may not have propagated yet, so its events are stale. The turn's
+      // finally block will emit session.info with running=false to clear
+      // busy for real once the agent loop actually exits.
+      if (state.interrupted) {
+        return state
+      }
+
+      return {
+        ...state,
+        busy: true,
+        awaitingResponse: true,
+        sawAssistantPayload: false,
+        interrupted: false,
+        interimBoundaryPending: false,
+        // Backend accepted the turn — the no-payload settle gate below may
+        // now treat a running=false heartbeat as a real turn end.
+        turnLive: true,
+        // Keep the submit-time seed (submit.ts seedOptimistic) — resetting
+        // here would hide the submit→accept round trip from the timer.
+        // Backend-originated turns (queue drain elsewhere, goal follow-up)
+        // have no seed and arm here.
+        turnStartedAt: state.turnStartedAt ?? Date.now()
+      }
+    })
+
+    if (isActiveEvent) {
+      // Belt-and-suspenders mirror of the ACTIVE session's per-session
+      // clock (the load-bearing mirror is the view-sync flush in
+      // use-session-state-cache). Mirror the seeded value, not Date.now():
+      // resetting to accept-time here would visibly snap the timer back
+      // after the submit-time seed above already started it.
+      setTurnStartedAt(sessionStateByRuntimeIdRef.current.get(sessionId)?.turnStartedAt ?? Date.now())
+    }
+
+    return true
+  }
+
+  if (event.type === 'message.delta') {
+    if (sessionId) {
+      appendAssistantDelta(sessionId, coerceGatewayText(payload?.text), occurredAt)
+    }
+
+    return true
+  }
+
+  if (event.type === 'message.interim') {
+    // The agent emitted interim assistant commentary (text alongside tool
+    // calls, or the attempted final answer before a verify-on-stop nudge).
+    // Finalize it as its own sealed bubble so message.complete doesn't wipe
+    // it — the text was already streamed via message.delta and is visible.
+    if (sessionId) {
+      flushQueuedDeltas(sessionId)
+      const text = coerceGatewayText(payload?.text)
+
+      if (text) {
+        finalizeInterimAssistantMessage(sessionId, text, occurredAt)
+      }
+    }
+
+    return true
+  }
+
+  if (event.type === 'thinking.delta') {
+    // Most thinking.delta frames are kawaii spinner rewrites and stay out
+    // of the transcript. Explained provider waits are different: the core
+    // emits them after prolonged silence, so name that wait in the existing
+    // bottom-of-thread status row instead of leaving only an unlabeled timer.
+    if (sessionId) {
+      setSessionProviderWait(sessionId, providerWaitText(coerceGatewayText(payload?.text)))
+    }
+
+    return true
+  }
+
+  if (event.type === 'reaction') {
+    // Core-detected affection (ily / <3 / good bot) on the user's message.
+    // Play hearts only for the visible session so background turns stay quiet.
+    if (isActiveEvent && (payload?.kind ?? 'vibe') === 'vibe') {
+      burstVibeHearts()
+    }
+
+    return true
+  }
+
+  if (event.type === 'reasoning.delta') {
+    if (sessionId) {
+      appendReasoningDelta(sessionId, coerceThinkingText(payload?.text), false, occurredAt)
+    }
+
+    if (isActiveEvent) {
+      setPetActivity({ reasoning: true })
+    }
+
+    return true
+  }
+
+  if (event.type === 'reasoning.available') {
+    if (sessionId) {
+      appendReasoningDelta(sessionId, coerceThinkingText(payload?.text), true, occurredAt)
+    }
+
+    if (isActiveEvent) {
+      setPetActivity({ reasoning: true })
+    }
+
+    return true
+  }
+
+  if (event.type === 'moa.reference') {
+    // MoA reference-model output — surface as a labelled thinking chunk
+    // (tagged with the source model) before the aggregator's response, so
+    // the mixture-of-agents process is visible. Reuses the reasoning
+    // disclosure rather than introducing a parallel surface.
+    if (sessionId) {
+      const label = coerceGatewayText(payload?.label) || 'reference'
+      const idx = typeof payload?.index === 'number' ? payload.index : undefined
+      const cnt = typeof payload?.count === 'number' ? payload.count : undefined
+      const header = idx && cnt ? `◇ Reference ${idx}/${cnt} — ${label}` : `◇ Reference — ${label}`
+      const body = coerceThinkingText(payload?.text)
+      const text = `${header}\n${body}\n\n`
+
+      if (idx === undefined || idx <= 1) {
+        // First reference: clear any stale reasoning left over from
+        // before this turn's references start, same as before.
+        appendReasoningDelta(sessionId, text, true, occurredAt)
+      } else {
+        // Later references must accumulate, not replace — otherwise
+        // each new reference wipes out the ones already shown (#64658).
+        // Queue-then-flush (rather than the streamed/batched queue path)
+        // applies it immediately, since each reference arrives as one
+        // complete block rather than incremental tokens. reasoning.delta
+        // cannot be mid-flight here: MoAChatCompletions.reference_callback
+        // (agent/moa_loop.py) fires "moa.reference" once per reference's
+        // already-complete text, with no concurrent token stream for the
+        // reference-gathering phase, so there is no in-flight delta to
+        // collide with in the shared queue bucket.
+        appendReasoningDelta(sessionId, text, false, occurredAt)
+        flushQueuedDeltas(sessionId)
+      }
+    }
+
+    if (isActiveEvent) {
+      setPetActivity({ reasoning: true })
+    }
+
+    return true
+  }
+
+  if (event.type === 'moa.aggregating') {
+    // Status transition only; the aggregator's reply arrives via the normal
+    // message stream. No reasoning/transcript mutation here.
+    if (isActiveEvent) {
+      setPetActivity({ reasoning: true })
+    }
+
+    return true
+  }
+
+  if (event.type === 'moa.progress') {
+    // Live reference fan-out progress ("refs k/n") — surfaced in the same
+    // reasoning disclosure the references land in. These lines arrive
+    // BEFORE any moa.reference event (references are only emitted once the
+    // whole fan-out completes), and the first moa.reference replaces the
+    // block, so the progress trail is self-cleaning.
+    if (sessionId && typeof payload?.refs_done === 'number' && typeof payload?.refs_total === 'number') {
+      const label = coerceGatewayText(payload?.label)
+
+      const line = label
+        ? `◇ MoA refs ${payload.refs_done}/${payload.refs_total} — ${label}\n`
+        : `◇ MoA refs ${payload.refs_done}/${payload.refs_total}\n`
+
+      appendReasoningDelta(sessionId, line, payload.refs_done <= 1, occurredAt)
+      flushQueuedDeltas(sessionId)
+    }
+
+    if (isActiveEvent) {
+      setPetActivity({ reasoning: true })
+    }
+
+    return true
+  }
+
+  if (event.type === 'moa.phase') {
+    // Phase transition — currently only phase="aggregator" (fan-out done,
+    // aggregator acting). Append a one-line marker; the first
+    // moa.reference that follows replaces the whole block.
+    if (sessionId && payload?.phase === 'aggregator') {
+      appendReasoningDelta(sessionId, '◇ MoA aggregating…\n', false, occurredAt)
+      flushQueuedDeltas(sessionId)
+    }
+
+    if (isActiveEvent) {
+      setPetActivity({ reasoning: true })
+    }
+
+    return true
+  }
+
+  if (event.type === 'message.complete') {
+    if (!sessionId) {
+      return true
+    }
+
+    // Turn ended — drop any blocking prompt still open for THIS session
+    // (e.g. interrupted, or the approval already resolved). Scoped to the
+    // session so a background turn finishing can't wipe the active chat's
+    // prompt, and vice versa.
+    clearAllPrompts(sessionId)
+    clearClarifyRequest(undefined, sessionId)
+    // Turn ended without a final `todo` update — drop a still-unfinished
+    // list so "Tasks N/M" doesn't stay pinned above the composer with the
+    // last item stuck pending/in_progress. Finished lists keep their linger.
+    clearActiveSessionTodos(sessionId)
+    setSessionCompacting(sessionId, false)
+
+    flushQueuedDeltas(sessionId)
+
+    // Keyed by session so only one window beeps when several are open.
+    playCompletionSound(sessionId)
+
+    const finalText = coerceGatewayText(payload?.text) || coerceGatewayText(payload?.rendered)
+
+    // Terminal error frames (status "error") carry the failure in
+    // structured fields: `error` is the message, and `partial` marks
+    // `text` as streamed output to keep rather than the error string.
+    const failure =
+      payload?.status === 'error'
+        ? {
+            error: coerceGatewayText(payload.error).trim() || finalText || 'Hermes reported an error',
+            partial: Boolean(payload.partial)
+          }
+        : undefined
+
+    completeAssistantMessage(sessionId, finalText, payload?.response_previewed, failure, occurredAt)
+
+    // Structured billing wall forwarded by the gateway (out of credits /
+    // payment required) — cache it + raise a billing-specific toast.
+    if (payload?.billing) {
+      surfaceBillingBlock(sessionId, payload.billing)
+    }
+
+    if (isActiveEvent) {
+      setTurnStartedAt(null)
+
+      // Pet beat: a finished turn always celebrates — go straight to the
+      // jump, never linger on the run/reason pose. One atom update (clears
+      // toolRunning/reasoning AND sets celebrate together) so no stray "run"
+      // frame leaks to the sprite — including the popped-out overlay, which
+      // mirrors each activity change. The jump runs ~2 loops, then settles.
+      flashPetActivity({ celebrate: true, reasoning: false, toolRunning: false }, 2200)
+
+      // Light up the pet's mail icon if the user wasn't looking when the turn
+      // finished — a glanceable "new message" hint on the popped-out overlay.
+      // Cleared when they open the app via the mail icon or refocus the window.
+      if (typeof document !== 'undefined' && !document.hasFocus()) {
+        markPetUnread()
+      }
+    }
+
+    if (payload?.usage) {
+      // Per-session twin FIRST (the statusbar reads it for focused tiles);
+      // the primary-only global mirrors the ACTIVE session — ungated it
+      // let a background tile's turn overwrite the primary's count.
+      updateSessionState(sessionId, state => ({
+        ...state,
+        usage: { calls: 0, input: 0, output: 0, total: 0, ...state.usage, ...payload.usage }
+      }))
+
+      if (isActiveEvent) {
+        setCurrentUsage(current => ({ ...current, ...payload.usage }))
+      }
+    }
+
+    return true
+  }
+
+  return false
+}
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/session-info.ts b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/session-info.ts
new file mode 100644
index 0000000000..ef66a3b22a
--- /dev/null
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/session-info.ts
@@ -0,0 +1,385 @@
+import { normalizePersonalityValue } from '@/lib/chat-runtime'
+import { modelOptionsQueryKey } from '@/lib/model-options'
+import { reconcileApprovalModeForProfile } from '@/store/approval-mode'
+import { requestDesktopOnboardingForCredentialWarning } from '@/store/onboarding'
+import { followActiveSessionCwd } from '@/store/projects'
+import {
+  $currentCwd,
+  $currentModel,
+  $currentProvider,
+  $selectedStoredSessionId,
+  $sessions,
+  sessionMatchesStoredId,
+  setCurrentBranch,
+  setCurrentCwdTransient,
+  setCurrentFastMode,
+  setCurrentPersonality,
+  setCurrentReasoningEffort,
+  setCurrentServiceTier,
+  setCurrentUsage,
+  setSessions,
+  setTerminalBackend,
+  setWorkspaceCwdOwner,
+  setYoloActive
+} from '@/store/session'
+import { reportInstallMethodWarning } from '@/store/updates'
+
+import { finalizeInterruptedMessages } from '../../use-prompt-actions/rewind'
+import { hasSessionInfoStatePatch, PRE_TURN_LIVE_SETTLE_GRACE_MS, sessionInfoStatePatch } from '../utils'
+
+import type { GatewayEventContext } from './types'
+
+/**
+ * Whether a `session.info` payload's `stored_session_id` may be treated as the
+ * selected conversation's, so its cwd can be claimed for it (#71254).
+ *
+ * Absent is not the same as different: the backend omits the id on a
+ * not-yet-built (`lazy`) session, and refusing there would leave the workspace
+ * marked un-owned for the rest of the conversation. Matching goes through the
+ * lineage (`sessionMatchesStoredId`) so a compression-rotated tip and the root
+ * a pinned-row selection may hold still read as one conversation.
+ */
+function sessionInfoDescribesSelectedSession(storedSessionId: string | undefined): boolean {
+  const infoStoredSessionId = storedSessionId?.trim() || null
+  const selected = $selectedStoredSessionId.get() ?? null
+
+  if (!infoStoredSessionId) {
+    return true
+  }
+
+  // A named session cannot describe a fresh draft. Treating a null selection as
+  // a wildcard let a background tile's `session.info` rehome the draft to the
+  // tile's workspace.
+  if (!selected) {
+    return false
+  }
+
+  if (infoStoredSessionId === selected) {
+    return true
+  }
+
+  // Either id may be the live tip or the lineage root, so ask whether ONE row
+  // answers to both rather than assuming which side rotated.
+  return $sessions
+    .get()
+    .some(session => sessionMatchesStoredId(session, infoStoredSessionId) && sessionMatchesStoredId(session, selected))
+}
+
+/** session.info / session.usage / session.title. */
+export function handleSessionInfoEvent(ctx: GatewayEventContext): boolean {
+  const { deps, event, payload, sessionId, explicitSid, isActiveEvent, occurredAt, fromActiveSource } = ctx
+
+  const {
+    activeGatewayProfile,
+    activeSessionIdRef,
+    hydrateFromStoredSession,
+    lastCwdInfoSessionRef,
+    queryClient,
+    scheduleSessionsRefresh,
+    sessionStateByRuntimeIdRef,
+    updateSessionState
+  } = deps
+
+  if (event.type === 'session.info') {
+    // Apply session-scoped fields when the event targets the active
+    // session, OR when it's a global broadcast and we have no session.
+    const apply = explicitSid ? isActiveEvent : !activeSessionIdRef.current
+    const statePatch = sessionInfoStatePatch(payload)
+    const hasStatePatch = hasSessionInfoStatePatch(statePatch)
+    const modelChanged = typeof payload?.model === 'string'
+    const providerChanged = typeof payload?.provider === 'string'
+    const runningChanged = typeof payload?.running === 'boolean'
+    // The backend stamps model/provider (as strings) on EVERY session.info,
+    // so the presence flags above are true on every heartbeat/turn edge —
+    // fine for the cheap atom writes below (nanostores skips identical
+    // values), but they also drove queryClient.invalidateQueries, refetching
+    // the model-options provider catalog once or twice per turn for a model
+    // that never changed. Only a genuine VALUE change (vs the session's own
+    // cached runtime state, captured before the state patch below applies;
+    // composer atoms as the fallback for an uncached session) invalidates.
+    const knownState = sessionId ? sessionStateByRuntimeIdRef.current.get(sessionId) : undefined
+    const modelValueChanged = modelChanged && payload!.model !== (knownState?.model ?? $currentModel.get())
+
+    const providerValueChanged =
+      providerChanged && payload!.provider !== (knownState?.provider ?? $currentProvider.get())
+
+    // Config is profile-scoped, but session.info also arrives for background
+    // sessions. Only an active-session event from the currently active
+    // gateway may reconcile the foreground cache. Requiring the renderer's
+    // source tag prevents an event queued before a profile swap from being
+    // attributed to the newly active profile.
+    if (isActiveEvent && typeof payload?.approval_mode === 'string' && event.profile && fromActiveSource()) {
+      reconcileApprovalModeForProfile(event.profile, payload.approval_mode)
+    }
+
+    if (apply) {
+      // Do not call setCurrentModel / setCurrentProvider here. Composer
+      // model/provider is sticky UI state (localStorage + manual picks).
+      // Periodic session.info heartbeats often carry the profile default
+      // (or a stale session model) and would silently revert the dropdown.
+      // Active-session model/provider still flows through the session state
+      // cache via updateSessionState → syncRuntimeMetadataToView below.
+
+      if (typeof payload?.cwd === 'string' && sessionInfoDescribesSelectedSession(payload.stored_session_id)) {
+        // The active session's agent can relocate itself (new repo/worktree
+        // via the terminal). When the SAME active session's cwd actually
+        // moves, follow it — refresh the project tree + scope so the sidebar
+        // tracks the live thread. A fresh selection (different session id)
+        // is a switch, not a move, so it refreshes data without yanking scope.
+        const cwdMoved = payload.cwd !== $currentCwd.get()
+        const sameSession = !!sessionId && sessionId === lastCwdInfoSessionRef.current
+
+        lastCwdInfoSessionRef.current = sessionId
+        setCurrentCwdTransient(payload.cwd)
+
+        // The backend just confirmed the selected conversation's real
+        // workspace, so it owns the path we wrote. Without the claim the
+        // marker keeps naming whoever held it before — including the
+        // released state a detached resume leaves behind — and the primary
+        // workspace-derived surfaces stay hidden against a folder the
+        // backend has confirmed (#71254).
+        setWorkspaceCwdOwner($selectedStoredSessionId.get())
+
+        if (cwdMoved && sameSession) {
+          void followActiveSessionCwd(payload.cwd)
+        }
+      }
+
+      if (typeof payload?.branch === 'string') {
+        setCurrentBranch(payload.branch)
+      }
+
+      if (typeof payload?.terminal_backend === 'string') {
+        setTerminalBackend(payload.terminal_backend)
+      }
+
+      if (typeof payload?.personality === 'string') {
+        setCurrentPersonality(normalizePersonalityValue(payload.personality))
+      }
+
+      if (typeof payload?.reasoning_effort === 'string') {
+        setCurrentReasoningEffort(payload.reasoning_effort)
+      }
+
+      if (typeof payload?.service_tier === 'string') {
+        setCurrentServiceTier(payload.service_tier)
+      }
+
+      if (typeof payload?.fast === 'boolean') {
+        setCurrentFastMode(payload.fast)
+      }
+
+      if (typeof payload?.yolo === 'boolean') {
+        setYoloActive(payload.yolo)
+      }
+    }
+
+    if (sessionId && hasStatePatch) {
+      updateSessionState(
+        sessionId,
+        state => ({
+          ...state,
+          ...statePatch,
+          branch: statePatch.branch ?? state.branch,
+          cwd: statePatch.cwd ?? state.cwd
+        }),
+        payload?.stored_session_id || undefined
+      )
+    }
+
+    // The running→busy transition must reach EVERY session, not just the
+    // active one. The `apply` gate above correctly scopes view-only side
+    // effects (setCurrentCwd, etc.) to the focused chat,
+    // but the per-session busy state is what drives the sidebar working
+    // indicator — a background session's turn start/finish must update
+    // its dot without the user opening it. updateSessionState only
+    // mutates the per-runtime cache entry, and syncSessionStateToView
+    // guards the view publish to the active session, so this is safe.
+    if (runningChanged && sessionId) {
+      // Set when THIS event released a turn that ended without ever
+      // producing an assistant payload, so the catch-up side effects below
+      // run on that edge only. The updater is invoked exactly once,
+      // synchronously, by updateSessionState.
+      let recoveredWithoutPayload = false
+
+      const nextState = updateSessionState(
+        sessionId,
+        state => {
+          const busy = Boolean(payload!.running)
+
+          if (state.busy === busy && (busy || !state.awaitingResponse)) {
+            return state
+          }
+
+          if (busy) {
+            // Don't re-arm busy from a stale session.info if the user
+            // just clicked Stop (interrupted=true). The backend's
+            // cooperative interrupt may not have propagated yet, so
+            // running is still true in the heartbeat. The turn's
+            // finally block will emit running=false to clear busy.
+            if (state.interrupted) {
+              return state
+            }
+
+            // Prefer the gateway-reported turn_started_at so the timer
+            // survives session switches and session.info heartbeats.
+            const gatewayTurnStartedAt =
+              typeof payload!.turn_started_at === 'number' && payload!.turn_started_at > 0
+                ? payload!.turn_started_at * 1000
+                : null
+
+            return {
+              ...state,
+              busy,
+              // running=true from the backend is turn-live proof, same as
+              // message.start (e.g. resuming an already-running session
+              // that never replays its start event).
+              turnLive: true,
+              turnStartedAt: state.turnStartedAt ?? gatewayTurnStartedAt ?? Date.now()
+            }
+          }
+
+          // The turn has not started backend-side yet. submit arms
+          // busy/awaitingResponse optimistically, so a running=false
+          // heartbeat that lands in the gap before the turn spins up is a
+          // pre-start report, not a finished turn — settling on it would
+          // drop the spinner and re-open the send guard mid-flight.
+          // turnLive is stamped only once the backend reports the turn
+          // live (message.start, the running=true edge, or a resumed
+          // in-flight turn) and is cleared by every settle, so false
+          // here is exactly "no turn has been reported running yet".
+          // (turnStartedAt can't discriminate — it is optimistically
+          // seeded at submit so the visible timer starts at Enter.)
+          //
+          // BOUNDED (#86795): an armed turn that never goes live — a
+          // restore/edit whose rewind was refused after the optimistic
+          // arm, a submit response lost to a gateway bounce, a terminal
+          // error event that never arrived — would otherwise hold this
+          // gate forever. busy then latches until app restart:
+          // isTargetSessionBusy refuses every send, the composer queues
+          // each message, and the queue drain (gated on busy→false) never
+          // fires. turnStartedAt is seeded at the optimistic arm, so its
+          // age bounds the hold; past the grace window (or with no clock
+          // at all) the gateway's running=false is authoritative and the
+          // settle below releases the session.
+          const armedAt = state.turnStartedAt
+
+          const withinPreStartGrace =
+            typeof armedAt === 'number' && Date.now() - armedAt < PRE_TURN_LIVE_SETTLE_GRACE_MS
+
+          if (state.awaitingResponse && !state.sawAssistantPayload && !state.turnLive && withinPreStartGrace) {
+            return state
+          }
+
+          // Past that gate the turn DID start and the backend now reports it
+          // finished. When no assistant payload ever arrived (gateway crash
+          // mid-stream, provider error before the first delta, agent-build
+          // failure) message.complete never fires, so this is the only event
+          // that can release the session. Bailing here instead left
+          // awaitingResponse/busy latched until app restart (#46517): the
+          // per-session busy flag is authoritative for isTargetSessionBusy,
+          // so submitPrompt and the slash dispatcher silently returned false
+          // and the session accepted no further input.
+          recoveredWithoutPayload = state.awaitingResponse && !state.sawAssistantPayload
+
+          return {
+            ...state,
+            awaitingResponse: false,
+            busy,
+            // The turn is over but its streaming bubble may still say
+            // pending — running=false from the agent loop's finally block
+            // is the ONLY settle signal when message.complete never
+            // arrives (turn crash, reconnect gap). Left pending, that
+            // bubble shows a thinking indicator forever, stranded
+            // mid-transcript once the next user message lands after it.
+            // finalizeInterruptedMessages un-pends kept text and drops
+            // empty placeholders; on the normal path message.complete
+            // already settled everything and this is a no-op.
+            messages: finalizeInterruptedMessages(state.messages, state.streamId, occurredAt),
+            pendingBranchGroup: null,
+            streamId: null,
+            turnStartedAt: null,
+            turnLive: false
+          }
+        },
+        payload?.stored_session_id || undefined
+      )
+
+      if (recoveredWithoutPayload) {
+        // Stays unscoped, like the settle above: a background session's
+        // sidebar row has to drop its working dot without the user opening
+        // it. This fires on the recovery edge only — once awaitingResponse
+        // is false the `state.busy === busy` guard above short-circuits
+        // every later heartbeat — so it costs one coalesced refresh per
+        // broken turn, not one per tick.
+        scheduleSessionsRefresh()
+
+        // The transcript catch-up IS scoped. The stream died, but the turn
+        // itself may have completed and been persisted, so refetch stored
+        // history for the session actually on screen; a background session
+        // reads its history when the user opens it, and hydrating every one
+        // of them here would fan a REST call out per idle session.
+        if (isActiveEvent) {
+          void hydrateFromStoredSession(3, nextState.storedSessionId, sessionId)
+        }
+      }
+    }
+
+    if (payload?.usage && (!explicitSid || isActiveEvent)) {
+      setCurrentUsage(current => ({ ...current, ...payload.usage }))
+    }
+
+    requestDesktopOnboardingForCredentialWarning(payload?.credential_warning)
+
+    if (apply) {
+      reportInstallMethodWarning(payload?.install_warning)
+      // Config refetch is only meaningful for the foreground context —
+      // everything refreshHermesConfig applies is either active-session
+      // guarded or a composer/global pref. Background sessions' heartbeats
+      // used to trigger it too (two REST calls each, every turn).
+      ctx.scheduleConfigRefresh()
+    }
+
+    if (modelValueChanged || providerValueChanged) {
+      void queryClient.invalidateQueries({
+        queryKey: explicitSid && sessionId ? modelOptionsQueryKey(activeGatewayProfile, sessionId) : ['model-options']
+      })
+    }
+
+    return true
+  }
+
+  if (event.type === 'session.usage') {
+    // Live usage tick emitted while a turn is mid-flight (see tui_gateway
+    // _start_usage_ticker) so the status-bar context window tracks growth
+    // during the turn instead of only jumping at message.complete.
+    if (payload?.usage && sessionId) {
+      // Per-session twin first: a focused secondary tile reads this cache,
+      // while the primary-only global mirrors the active session.
+      updateSessionState(sessionId, state => ({
+        ...state,
+        usage: { calls: 0, input: 0, output: 0, total: 0, ...state.usage, ...payload.usage }
+      }))
+
+      if (isActiveEvent) {
+        setCurrentUsage(current => ({ ...current, ...payload.usage }))
+      }
+    }
+
+    return true
+  }
+
+  if (event.type === 'session.title') {
+    // Live auto-title push (titler runs async, after the turn's refresh).
+    const storedId = typeof payload?.session_id === 'string' ? payload.session_id : ''
+    const nextTitle = typeof payload?.title === 'string' ? payload.title.trim() : ''
+
+    if (storedId && nextTitle) {
+      setSessions(prev => prev.map(s => (sessionMatchesStoredId(s, storedId) ? { ...s, title: nextTitle } : s)))
+    }
+
+    return true
+  }
+
+  return false
+}
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/status.ts b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/status.ts
new file mode 100644
index 0000000000..37f56cbc68
--- /dev/null
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/status.ts
@@ -0,0 +1,177 @@
+import { translateNow } from '@/i18n'
+import { textPart } from '@/lib/chat-messages'
+import { coerceGatewayText } from '@/lib/chat-runtime'
+import { isProviderSetupErrorMessage } from '@/lib/provider-setup-errors'
+import { type AgentNoticePayload, clearAgentNotice, nativeNoticeInput, showAgentNotice } from '@/store/agent-notices'
+import { clearClarifyRequest } from '@/store/clarify'
+import { setSessionCompacting } from '@/store/compaction'
+import { refreshBackgroundProcesses } from '@/store/composer-status'
+import { applyGoalStatusText } from '@/store/goals'
+import { dispatchNativeNotification } from '@/store/native-notifications'
+import { isDiskFullErrorMessage, notify, notifyError } from '@/store/notifications'
+import { requestDesktopOnboarding } from '@/store/onboarding'
+import { flashPetActivity, setPetActivity } from '@/store/pet'
+import { clearAllPrompts } from '@/store/prompts'
+import { setTurnStartedAt } from '@/store/session'
+import { clearActiveSessionTodos } from '@/store/todos'
+
+import type { GatewayEventContext } from './types'
+
+/** status.update / review.summary / notification.show / notification.clear /
+ *  error — the status-and-notice tail of the dispatcher. */
+export function handleStatusEvent(ctx: GatewayEventContext): boolean {
+  const { deps, event, payload, sessionId, isActiveEvent, occurredAt } = ctx
+  const { compactedTurnRef, failAssistantMessage, flushQueuedDeltas, queryClient, updateSessionState } = deps
+
+  if (event.type === 'status.update') {
+    if (sessionId && payload?.kind === 'compacting') {
+      setSessionCompacting(sessionId, true)
+      compactedTurnRef.current.add(sessionId)
+    } else if (sessionId && payload?.kind === 'compacted') {
+      setSessionCompacting(sessionId, false)
+      compactedTurnRef.current.delete(sessionId)
+    } else if (sessionId && payload?.kind === 'process') {
+      // The gateway's notification poller announces background process
+      // completions / watch matches here — re-sync the status stack.
+      void refreshBackgroundProcesses(sessionId)
+    } else if (sessionId && payload?.kind === 'goal') {
+      applyGoalStatusText(sessionId, coerceGatewayText(payload?.text))
+    }
+
+    return true
+  }
+
+  if (event.type === 'review.summary') {
+    // Self-improvement background review saved something to memory/skills
+    // and emitted a persistent summary (Python formats it as
+    // "💾 Self-improvement review: …"). The CLI prints this via
+    // prompt_toolkit and the Ink TUI renders it as a system line; the
+    // desktop has neither, so without this handler the skill/memory
+    // change happens silently. Surface it as a persistent system message
+    // in the transcript so the user is always informed — it must not be a
+    // transient toast that can be missed.
+    //
+    // Typed here with the `review:` marker (same convention as `steer:` /
+    // `slash:`) so SystemMessage can paint it as the memory-write row it
+    // is instead of sniffing the backend's prose. The leading 💾 goes with
+    // it — the row draws its own glyph.
+    const text = coerceGatewayText(payload?.text)
+      .trim()
+      .replace(/^[^\p{L}\p{N}]+/u, '')
+
+    if (text && sessionId) {
+      flushQueuedDeltas(sessionId)
+      updateSessionState(sessionId, state => ({
+        ...state,
+        messages: [
+          ...state.messages,
+          {
+            id: `review-summary-${Date.now()}`,
+            role: 'system',
+            parts: [textPart(`review:${text}`, occurredAt)],
+            timestamp: occurredAt
+          }
+        ]
+      }))
+    }
+
+    return true
+  }
+
+  if (event.type === 'notification.show') {
+    // Driver-agnostic agent notice (credits usage/grant/depleted/restored
+    // from `agent/credits_tracker.py`). The Ink TUI renders these in its
+    // status bar; the desktop renders them as toasts. The notice key doubles
+    // as the toast id, so the escalating 50→75→90 credits line replaces in
+    // place instead of stacking. Account-wide signal — shown regardless of
+    // which session is focused.
+    const notice = event.payload as AgentNoticePayload | undefined
+
+    showAgentNotice(notice)
+
+    // The urgent pair (access paused / restored) also breaks through as a
+    // native OS notification when Hermes is backgrounded; dispatch is gated
+    // by the user's notification prefs + backgrounded check.
+    const native = nativeNoticeInput(notice, translateNow('notifications.native.creditsTitle'))
+
+    if (native) {
+      dispatchNativeNotification(native)
+    }
+
+    // A credits crossing moves the account balance. Settings → Billing polls
+    // `billing.state` every 30s; nudge it so the page reflects the crossing
+    // immediately instead of up to 30s late.
+    if (notice?.key?.startsWith('credits.')) {
+      void queryClient.invalidateQueries({ queryKey: ['billing', 'state'] })
+    }
+
+    return true
+  }
+
+  if (event.type === 'notification.clear') {
+    // Key-matched dismissal (e.g. credits restored clears the depleted
+    // notice). notify() keys the toast by the notice key, so this maps
+    // straight to dismissNotification(key).
+    clearAgentNotice((event.payload as AgentNoticePayload | undefined)?.key)
+
+    return true
+  }
+
+  if (event.type === 'error') {
+    const errorMessage = payload?.message || 'Hermes reported an error'
+    const looksLikeProviderSetup = isProviderSetupErrorMessage(errorMessage)
+
+    // A turn that errors out has also ended — drop any open blocking prompt
+    // for this session so an approval/sudo/secret overlay can't linger past
+    // the failed turn (same intent as the message.complete clear).
+    if (sessionId) {
+      clearAllPrompts(sessionId)
+      clearClarifyRequest(undefined, sessionId)
+      clearActiveSessionTodos(sessionId)
+      setSessionCompacting(sessionId, false)
+      compactedTurnRef.current.delete(sessionId)
+    }
+
+    if (isActiveEvent) {
+      setPetActivity({ reasoning: false, toolRunning: false })
+      flashPetActivity({ error: true })
+    }
+
+    dispatchNativeNotification({
+      body: errorMessage,
+      kind: 'turnError',
+      sessionId,
+      title: translateNow('notifications.native.turnErrorTitle')
+    })
+
+    if (looksLikeProviderSetup) {
+      requestDesktopOnboarding(errorMessage)
+    } else if (isDiskFullErrorMessage(errorMessage)) {
+      notifyError(new Error(errorMessage), translateNow('notifications.errors.diskFull'))
+    } else {
+      // Toast globally, not just when the failing thread is focused: a
+      // turn-ending error (e.g. out of funds) blocks every thread, so the
+      // inline error alone is too easy to miss. The stable id collapses the
+      // same error from multiple blocked threads into one toast.
+      notify({
+        id: `gateway-error:${errorMessage}`,
+        kind: 'error',
+        title: 'Hermes error',
+        message: errorMessage
+      })
+    }
+
+    if (sessionId) {
+      flushQueuedDeltas(sessionId)
+      failAssistantMessage(sessionId, errorMessage, occurredAt)
+    }
+
+    if (isActiveEvent) {
+      setTurnStartedAt(null)
+    }
+
+    return true
+  }
+
+  return false
+}
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/tools.ts b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/tools.ts
new file mode 100644
index 0000000000..19cbeb003f
--- /dev/null
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/tools.ts
@@ -0,0 +1,141 @@
+import { invalidateSlashCompletions } from '@/lib/slash-completion-cache'
+import { refreshBackgroundProcesses } from '@/store/composer-status'
+import { flashPetActivity, setPetActivity } from '@/store/pet'
+import { pruneDelegateFallbackSubagents, upsertSubagent } from '@/store/subagents'
+import { reportMcpToolResult } from '@/store/suggestion-providers/repair'
+import { invalidateSkillSuggestionIndex } from '@/store/suggestion-providers/skill'
+import { recordToolDiff } from '@/store/tool-diffs'
+import { setSessionDraftingTool } from '@/store/tool-drafting'
+import { notifyWorkspaceChanged, toolChangedPath, toolMayMutateFiles } from '@/store/workspace-events'
+
+import { SUBAGENT_EVENT_TYPES, toTodoPayload } from '../utils'
+
+import type { GatewayEventContext } from './types'
+
+/** tool.generating / tool.start / tool.progress / tool.complete / subagent.*. */
+export function handleToolEvent(ctx: GatewayEventContext): boolean {
+  const { deps, event, payload, sessionId, isActiveEvent, occurredAt } = ctx
+  const { flushQueuedDeltas, nativeSubagentSessionsRef, sessionInterrupted, updateSessionState, upsertToolCall } = deps
+
+  if (event.type === 'tool.generating') {
+    // Announced while the model is still emitting the call's JSON, so it
+    // carries a name and nothing else — no id, no args. Materializing a row
+    // from it strands an argless placeholder whenever the bubble is sealed
+    // before the real `tool.start` arrives, because the two can no longer be
+    // reconciled across the boundary. It's a status, so say it as one.
+    // A stopped turn can still emit a frame or two before the backend
+    // notices, and naming a tool we will never run leaves the label up
+    // until something else retires it. `mutateStream` drops late tool rows
+    // on the same condition; the status line has to agree with it.
+    if (!sessionId || sessionInterrupted(sessionId)) {
+      return true
+    }
+
+    setSessionDraftingTool(sessionId, typeof payload?.name === 'string' ? payload.name : '')
+
+    if (isActiveEvent) {
+      setPetActivity({ reasoning: false, toolRunning: true })
+    }
+
+    return true
+  }
+
+  if (event.type === 'tool.start' || event.type === 'tool.progress') {
+    if (!sessionId) {
+      return true
+    }
+
+    flushQueuedDeltas(sessionId)
+    upsertToolCall(sessionId, toTodoPayload(payload) ?? payload, 'running', event.type, occurredAt)
+
+    if (isActiveEvent) {
+      setPetActivity({ reasoning: false, toolRunning: true })
+    }
+
+    return true
+  }
+
+  if (event.type === 'tool.complete') {
+    if (sessionId) {
+      flushQueuedDeltas(sessionId)
+      upsertToolCall(sessionId, toTodoPayload(payload) ?? payload, 'complete', event.type, occurredAt)
+
+      if (isActiveEvent) {
+        setPetActivity({ toolRunning: false })
+
+        // A tool can fail without ending the turn when the agent recovers
+        // and continues. Surface that failure as a short pet beat too;
+        // otherwise only turn-level errors ever reach the failed state.
+        if (payload?.error) {
+          flashPetActivity({ error: true })
+        }
+      }
+
+      // A pending clarify blocks the turn, so the first tool.complete after
+      // one is the clarify resolving — drop the "needs input" flag here so
+      // the sidebar indicator clears as soon as it's answered, not only at
+      // message.complete.
+      updateSessionState(sessionId, state => (state.needsInput ? { ...state, needsInput: false } : state))
+
+      // terminal/process tool calls are the only things that spawn or reap
+      // background processes — sync the composer status stack right after.
+      if (!sessionInterrupted(sessionId) && (payload?.name === 'terminal' || payload?.name === 'process')) {
+        void refreshBackgroundProcesses(sessionId)
+      }
+    }
+
+    // The agent just created/deleted/renamed a skill, which adds or removes
+    // its `/name` command. Drop the composer's cached `/` list so the new
+    // skill is offerable now rather than after the hour-long TTL — and the
+    // skill-suggestion provider's index with it.
+    if (payload?.name === 'skill_manage') {
+      invalidateSlashCompletions()
+      invalidateSkillSuggestionIndex()
+    }
+
+    // MCP tool outcomes feed the connection-repair suggestion provider:
+    // an auth/connection-shaped failure offers a reconnect pill; a later
+    // success against the same server withdraws it.
+    if (sessionId && typeof payload?.name === 'string' && payload.name.startsWith('mcp__')) {
+      reportMcpToolResult(
+        sessionId,
+        payload.name,
+        Boolean(payload.error),
+        [payload.error, payload.result].filter(part => typeof part === 'string').join(' ')
+      )
+    }
+
+    if (typeof payload?.inline_diff === 'string' && payload.inline_diff.trim()) {
+      recordToolDiff(payload.tool_id || payload.name || '', payload.inline_diff)
+    }
+
+    // A file-mutating tool just finished — nudge the git-mirroring surfaces
+    // (coding rail, review pane, file tree) to refresh. Event-driven, not
+    // polled: fires exactly when the agent touches the tree.
+    if (payload && toolMayMutateFiles(payload)) {
+      notifyWorkspaceChanged(toolChangedPath(payload))
+    }
+
+    return true
+  }
+
+  if (SUBAGENT_EVENT_TYPES.has(event.type)) {
+    if (sessionId && payload && !sessionInterrupted(sessionId)) {
+      if (!nativeSubagentSessionsRef.current.has(sessionId)) {
+        pruneDelegateFallbackSubagents(sessionId)
+      }
+
+      nativeSubagentSessionsRef.current.add(sessionId)
+      upsertSubagent(
+        sessionId,
+        payload as Record<string, unknown>,
+        event.type === 'subagent.spawn_requested' || event.type === 'subagent.start',
+        event.type
+      )
+    }
+
+    return true
+  }
+
+  return false
+}
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/types.ts b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/types.ts
new file mode 100644
index 0000000000..551d1a0d51
--- /dev/null
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/types.ts
@@ -0,0 +1,72 @@
+import type { QueryClient } from '@tanstack/react-query'
+import type { MutableRefObject } from 'react'
+
+import type { GatewayEventPayload } from '@/lib/chat-messages'
+import type { RpcEvent } from '@/types/hermes'
+
+import type { ClientSessionState } from '../../../../types'
+
+export interface GatewayEventDeps {
+  activeGatewayProfile: string
+  activeSessionIdRef: MutableRefObject<string | null>
+  compactedTurnRef: MutableRefObject<Set<string>>
+  lastCwdInfoSessionRef: MutableRefObject<string | null>
+  nativeSubagentSessionsRef: MutableRefObject<Set<string>>
+  appendAssistantDelta: (sessionId: string, delta: string, occurredAt?: number) => void
+  appendReasoningDelta: (sessionId: string, delta: string, replace?: boolean, occurredAt?: number) => void
+  completeAssistantMessage: (
+    sessionId: string,
+    text: string,
+    responsePreviewed?: boolean,
+    failure?: { error: string; partial: boolean },
+    occurredAt?: number
+  ) => void
+  failAssistantMessage: (sessionId: string, errorMessage: string, occurredAt?: number) => void
+  flushQueuedDeltas: (sessionId?: string) => void
+  finalizeInterimAssistantMessage: (sessionId: string, text: string, occurredAt?: number) => void
+  hydrateFromStoredSession: (
+    attempts?: number,
+    storedSessionId?: string | null,
+    runtimeSessionId?: string | null
+  ) => Promise<void>
+  queryClient: QueryClient
+  refreshHermesConfig: () => Promise<void>
+  scheduleSessionsRefresh: () => void
+  sessionInterrupted: (sessionId: string) => boolean
+  sessionStateByRuntimeIdRef: MutableRefObject<Map<string, ClientSessionState>>
+  updateSessionState: (
+    sessionId: string,
+    updater: (state: ClientSessionState) => ClientSessionState,
+    storedSessionId?: string | null
+  ) => ClientSessionState
+  upsertToolCall: (
+    sessionId: string,
+    payload: GatewayEventPayload | undefined,
+    phase: 'running' | 'complete',
+    sourceEventType?: string,
+    occurredAt?: number
+  ) => void
+}
+
+/** Everything a per-family handler needs about the event being dispatched —
+ *  the routing preamble in index.ts computes it once per event. */
+export interface GatewayEventContext {
+  deps: GatewayEventDeps
+  event: RpcEvent
+  payload: GatewayEventPayload | undefined
+  /** Routed session id (explicit, pinned unscoped stream, or active fallback). */
+  sessionId: null | string
+  /** The raw `session_id` on the event ('' when unscoped). */
+  explicitSid: string
+  /** The routed session is the one on screen. */
+  isActiveEvent: boolean
+  /** Event timestamp in epoch seconds (payload timestamp or receipt time). */
+  occurredAt: number
+  /** The event came from the active (connection, profile) source. */
+  fromActiveSource: () => boolean
+  /** Coalesced trailing refreshHermesConfig (one per session.info burst). */
+  scheduleConfigRefresh: () => void
+}
+
+/** A family handler consumes matching event types and reports whether it did. */
+export type GatewayEventHandler = (ctx: GatewayEventContext) => boolean

From 149ef3ed2b735001c5d5649de1023a72ba62b812 Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 19 Aug 2026 03:34:49 -0500
Subject: [PATCH 11/48] refactor(desktop): split lib/chat-messages.ts into
 concern modules

Types, part builders, tool parts, hydration and reconciliation, behind a
barrel that keeps the @/lib/chat-messages path.

The folder was added without removing chat-messages.ts, so resolution
preferred the file and all its importers kept hitting the monolith while
the new modules sat dead. Deleting it surfaced a missing preset field on
GatewayEventPayload that layout.apply needs, hidden until the folder
actually resolved, and a completeOpenStreamParts helper copied into two
modules when only one calls it.
---
 apps/desktop/src/lib/chat-messages.ts         | 1537 -----------------
 .../src/lib/chat-messages/hydration.ts        |  324 ++++
 apps/desktop/src/lib/chat-messages/index.ts   |   18 +
 apps/desktop/src/lib/chat-messages/parts.ts   |  284 +++
 .../src/lib/chat-messages/reconciliation.ts   |  195 +++
 .../src/lib/chat-messages/tool-parts.ts       |  579 +++++++
 apps/desktop/src/lib/chat-messages/types.ts   |  158 ++
 7 files changed, 1558 insertions(+), 1537 deletions(-)
 delete mode 100644 apps/desktop/src/lib/chat-messages.ts
 create mode 100644 apps/desktop/src/lib/chat-messages/hydration.ts
 create mode 100644 apps/desktop/src/lib/chat-messages/index.ts
 create mode 100644 apps/desktop/src/lib/chat-messages/parts.ts
 create mode 100644 apps/desktop/src/lib/chat-messages/reconciliation.ts
 create mode 100644 apps/desktop/src/lib/chat-messages/tool-parts.ts
 create mode 100644 apps/desktop/src/lib/chat-messages/types.ts

diff --git a/apps/desktop/src/lib/chat-messages.ts b/apps/desktop/src/lib/chat-messages.ts
deleted file mode 100644
index 8602a54ecb..0000000000
--- a/apps/desktop/src/lib/chat-messages.ts
+++ /dev/null
@@ -1,1537 +0,0 @@
-import type { ThreadMessageLike } from '@assistant-ui/react'
-import { type BillingBlock, skillInvocationText } from '@hermes/shared'
-
-import { extractImageRefs } from '@/lib/embedded-images'
-import { dedupeGeneratedImageEchoesInParts } from '@/lib/generated-images'
-import { mediaDisplayLabel, mediaMarkdownHref } from '@/lib/media'
-import { normalize } from '@/lib/text'
-import { parseTodos } from '@/lib/todos'
-import type { MessageReaction, SessionMessage, UsageStats } from '@/types/hermes'
-
-export interface TimelinePartMetadata {
-  /** Unix seconds when this visible activity segment began. Fractional values
-   * preserve the millisecond precision available on live gateway events. */
-  timestamp?: number
-  /** Unix seconds when this segment stopped or handed off to the next one. */
-  completedAt?: number
-}
-
-export type ChatMessagePart = Exclude<ThreadMessageLike['content'], string>[number] & TimelinePartMetadata
-
-export type ChatMessage = {
-  id: string
-  role: SessionMessage['role']
-  parts: ChatMessagePart[]
-  timestamp?: number
-  completedAt?: number
-  pending?: boolean
-  error?: string
-  branchGroupId?: string
-  hidden?: boolean
-  /** Sealed mid-turn commentary (`message.interim`) — rendered without the
-   *  action footer so only the turn's final reply carries copy/refresh, and
-   *  the live view matches rehydration (which merges the turn into one bubble). */
-  interim?: boolean
-  /** Whole-turn wall-clock seconds (message.start → message.complete),
-   *  stamped by the desktop when it watched the turn run. Absent for
-   *  messages hydrated from history — the backend doesn't persist it. */
-  durationS?: number
-  /** Composer attachment ref strings (`@file:...`, `@image:...`) sent with this user message. */
-  attachmentRefs?: string[]
-  /** Durable backend `messages.id`. Absent until the row is persisted. */
-  rowId?: number
-  /** Emoji reactions on this message — one per author (see MessageReaction). */
-  reactions?: MessageReaction[]
-}
-
-export type GatewayEventPayload = {
-  /** Unix seconds supplied by tests/newer gateways; the desktop falls back to
-   * its local receipt clock when older gateways omit it. */
-  timestamp?: number
-  text?: string
-  rendered?: string
-  status?: string
-  message?: string
-  id?: string
-  name?: string
-  tool_id?: string
-  tool_call_id?: string
-  args?: unknown
-  arguments?: unknown
-  context?: string
-  input?: unknown
-  preview?: string
-  result?: unknown
-  summary?: string
-  error?: string | boolean
-  inline_diff?: string
-  duration_s?: number
-  todos?: unknown
-  model?: string
-  provider?: string
-  reasoning_effort?: string
-  service_tier?: string
-  fast?: boolean
-  approval_mode?: string
-  yolo?: boolean
-  running?: boolean
-  turn_started_at?: number | null
-  cwd?: string
-  branch?: string
-  terminal_backend?: string
-  credential_warning?: string
-  install_warning?: string
-  personality?: string
-  usage?: Partial<UsageStats>
-  // agent.terminal.output — live chunk for a read-only agent terminal tab
-  process_id?: string
-  chunk?: string
-  // clarify.request
-  request_id?: string
-  question?: string
-  choices?: string[] | null
-  multi_select?: boolean
-  // clarify.request batch form: questions replaces question/choices, and
-  // answers (qid → locked answer) rides along on reconnect replay only.
-  questions?: unknown
-  answers?: Record<string, unknown>
-  // mcp.setup.request (setup_mcp tool — inline MCP consent card)
-  server?: string
-  action?: string
-  reason?: string
-  // approval.request (dangerous command / execute_code) — session-keyed
-  command?: string
-  description?: string
-  // False when a tirith content-security warning forbids a permanent allow.
-  allow_permanent?: boolean
-  smart_denied?: boolean
-  // secret.request (skill credential capture)
-  env_var?: string
-  prompt?: string
-  // terminal.read.request / preview.read.request (GUI agent reading the
-  // in-app terminal pane or the browser/preview pane)
-  start?: number
-  count?: number
-  // status.update (kind=process → background process completion/watch-match)
-  kind?: string
-  // pane.reveal (agent focusing a desktop pane via the focus_pane tool)
-  pane?: string
-  // layout.apply (agent applying a layout preset via the apply_layout tool)
-  preset?: string
-  // tour.request (tour tool — agent-guided driver.js walkthrough). `action`
-  // and `steps` name the tour verb and step list; `surface` picks the app's
-  // own DOM vs the preview pane's guest page.
-  surface?: string
-  selector?: string
-  side?: string
-  steps?: unknown
-  step_index?: number
-  // message.reaction (agent reacting via the react_to_message tool) — the
-  // durable messages.id, that row's full reaction list after the write, and
-  // the row's role so a live (not-yet-round-tripped) message can be matched.
-  row_id?: number
-  reactions?: MessageReaction[]
-  role?: string
-  // session.title (live auto-title push) — stored session id + generated title
-  session_id?: string
-  title?: string
-  // session.info — the stored (durable) session id for this runtime session.
-  // Lets the desktop app map runtime→stored for background sessions it hasn't
-  // opened, so the sidebar working indicator updates without opening the chat.
-  stored_session_id?: string
-  // moa.reference / moa.aggregating (Mixture of Agents per-model relay)
-  label?: string
-  index?: number
-  aggregator?: string
-  // moa.progress / moa.phase (Mixture of Agents fan-out progress relay)
-  refs_done?: number
-  refs_total?: number
-  phase?: string
-  // message.complete — signals the final text was already previewed via
-  // interim_assistant_callback, so the UI can settle instead of duplicating.
-  response_previewed?: boolean
-  // message.complete with status "error" — `text` is streamed partial output
-  // (keep it visible), not the error string.
-  partial?: boolean
-  // message.complete with status "error" — the failed turn was retained
-  // backend-side and will replay through session.resume's inflight payload.
-  recoverable?: boolean
-  // Structured billing wall forwarded on message.complete when a turn fails
-  // with FailoverReason.billing (shape mirrors @hermes/shared BillingBlock).
-  billing?: BillingBlock
-  failure_reason?: string
-}
-
-export function textPart(text: string, timestamp?: number): ChatMessagePart {
-  return { type: 'text', text, ...(timestamp !== undefined ? { timestamp } : {}) }
-}
-
-export function reasoningPart(text: string, timestamp?: number): ChatMessagePart {
-  return { type: 'reasoning', text, ...(timestamp !== undefined ? { timestamp } : {}) }
-}
-
-const MEDIA_LINE_RE = /(^|\n)[\t ]*[`"']?MEDIA:\s*(?<line>`[^`\n]+`|"[^"\n]+"|'[^'\n]+'|\S+)[`"']?[\t ]*(\n|$)/g
-
-const MEDIA_TAG_RE = /[`"']?MEDIA:\s*(?<inline>`[^`\n]+`|"[^"\n]+"|'[^'\n]+'|\S+)[`"']?/g
-
-function unquoteMediaPath(value: string): string {
-  const trimmed = value.trim()
-  const quote = trimmed[0]
-
-  return quote && quote === trimmed.at(-1) && ['"', "'", '`'].includes(quote) ? trimmed.slice(1, -1) : trimmed
-}
-
-function mediaLink(value: string): string {
-  const path = unquoteMediaPath(value)
-
-  return `[${mediaDisplayLabel(path)}](${mediaMarkdownHref(path)})`
-}
-
-export function renderMediaTags(text: string): string {
-  return text
-    .replace(
-      MEDIA_LINE_RE,
-      (_match, lead: string, value: string, trailer: string) => `${lead}${mediaLink(value)}${trailer}`
-    )
-    .replace(MEDIA_TAG_RE, (_match, value: string) => mediaLink(value))
-    .replace(/[ \t]+\n/g, '\n')
-    .replace(/\n{3,}/g, '\n\n')
-}
-
-export function assistantTextPart(text: string, timestamp?: number): ChatMessagePart {
-  return textPart(renderMediaTags(text), timestamp)
-}
-
-export function chatMessageText(message: ChatMessage): string {
-  return message.parts
-    .filter((part): part is Extract<ChatMessagePart, { type: 'text' }> => part.type === 'text')
-    .map(part => part.text)
-    .join('')
-}
-
-export interface UnspokenTurnSpeech {
-  /** First unspoken assistant bubble — stable for the turn, the live speech session binds to it. */
-  id: string
-  /** Whether the newest assistant bubble is still streaming. */
-  pending: boolean
-  /** All unspoken assistant text in message order, bubbles joined on a blank line. */
-  text: string
-}
-
-/**
- * Collect every unspoken assistant bubble after `lastSpokenId`, in order.
- *
- * A turn with tool calls produces several assistant bubbles — narration
- * ("Let me check…") sealed as interims, then the final answer as a fresh
- * bubble. Voice conversation speaks a turn through ONE live session bound to
- * one response id, so it needs all of that text as a single growing string;
- * selecting only one bubble silently drops everything after it. The blank-line
- * join is a sentence boundary for the server's cutter, so a sealed bubble's
- * tail is flushed as soon as the next bubble starts.
- */
-export function collectUnspokenTurnSpeech(
-  messages: ChatMessage[],
-  lastSpokenId: string | null
-): UnspokenTurnSpeech | null {
-  const spokenIndex = lastSpokenId ? messages.findLastIndex(m => m.id === lastSpokenId) : -1
-
-  let id: string | null = null
-  let pending = false
-  const parts: string[] = []
-
-  for (const message of messages.slice(spokenIndex + 1)) {
-    if (message.role !== 'assistant' || message.hidden) {
-      continue
-    }
-
-    pending = Boolean(message.pending)
-    const text = chatMessageText(message).trim()
-
-    if (!text) {
-      continue
-    }
-
-    id ??= message.id
-    parts.push(text)
-  }
-
-  if (!id) {
-    return null
-  }
-
-  return { id, pending, text: parts.join('\n\n') }
-}
-
-const normalizeWs = (value: string) => value.replace(/\s+/g, ' ').trim()
-
-/**
- * Drop earlier text parts that a later text part repeats verbatim (after
- * whitespace normalization). Providers that continue a turn after a tool
- * call sometimes re-send the previous assistant text as the next message's
- * prefix (tool_calls row, then a stop row with identical prose) — the turn
- * merge then holds the same paragraph twice and everything in it renders
- * twice, most visibly ::preview frames. The LAST occurrence is the
- * authoritative one; keep it.
- */
-export function dedupeRepeatedTextInParts(parts: ChatMessagePart[]): ChatMessagePart[] {
-  const lastByText = new Map<string, number>()
-
-  parts.forEach((part, index) => {
-    if (part.type === 'text') {
-      const key = normalizeWs(part.text)
-
-      if (key) {
-        lastByText.set(key, index)
-      }
-    }
-  })
-
-  const dropped = parts.filter((part, index) => {
-    if (part.type !== 'text') {
-      return true
-    }
-
-    const key = normalizeWs(part.text)
-
-    return !key || lastByText.get(key) === index
-  })
-
-  return dropped.length === parts.length ? parts : dropped
-}
-
-/**
- * Merge the final assistant text into a message's parts.
- *
- * - Removes all existing `text` parts (they were streamed deltas, now superseded
- *   by the authoritative final response).
- * - Keeps `reasoning` parts, but drops one that the final text fully covers
- *   (reasoning ⊆ final) — the final restates it. A short final ("Done.") must
- *   NOT swallow a longer reasoning block that merely starts with it (#61447).
- * - Keeps all other part types (tool-call, image, etc.).
- * - Appends the final text as a new text part.
- */
-export function mergeFinalAssistantText(
-  parts: ChatMessagePart[],
-  finalText: string,
-  fallbackTimestamp?: number
-): ChatMessagePart[] {
-  const dedupeReference = normalizeWs(finalText)
-
-  const streamedText = normalizeWs(
-    parts
-      .filter((part): part is Extract<ChatMessagePart, { type: 'text' }> => part.type === 'text')
-      .map(part => part.text)
-      .join('')
-  )
-
-  // An authoritative final that is exactly the concatenation of streamed text
-  // confirms the content without erasing text↔reasoning activity boundaries.
-  if (streamedText && streamedText === dedupeReference) {
-    return parts
-  }
-
-  const previousText = parts.findLast(part => part.type === 'text')
-
-  const kept = parts.filter(part => {
-    if (part.type === 'text') {
-      // Sealed text parts were already finalized into their own bubbles —
-      // this filter only runs on the LAST streaming bubble, so there are no
-      // sealed parts here. All text parts are streamed deltas that get
-      // replaced by the authoritative final text.
-      return false
-    }
-
-    if (part.type !== 'reasoning' || !dedupeReference) {
-      return true
-    }
-
-    // Reasoning is a restatement only when the final FULLY covers it.
-    // The reverse direction is not considered — a short final must not
-    // swallow a longer reasoning block (#61447).
-    const r = normalizeWs(part.text)
-
-    return !(r && dedupeReference.startsWith(r))
-  })
-
-  if (!finalText) {
-    return kept
-  }
-
-  const finalPart = assistantTextPart(finalText, previousText?.timestamp ?? fallbackTimestamp)
-
-  if (previousText?.completedAt !== undefined) {
-    finalPart.completedAt = previousText.completedAt
-  }
-
-  return [...kept, finalPart]
-}
-
-const ATTACHED_CONTEXT_MARKER_RE = /(?:^|\n)--- Attached Context ---\s*\n/
-const CONTEXT_WARNINGS_MARKER_RE = /(?:^|\n)--- Context Warnings ---[\s\S]*$/
-const CONTEXT_REF_RE = /@(file|folder|url|image|tool|terminal):(?:"[^"\n]+"|'[^'\n]+'|`[^`\n]+`|\S+)/g
-
-function textFromUnknown(value: unknown, depth = 0): string {
-  if (typeof value === 'string') {
-    return value
-  }
-
-  if (value === null || value === undefined) {
-    return ''
-  }
-
-  if (depth > 2) {
-    return ''
-  }
-
-  if (Array.isArray(value)) {
-    return value.map(item => textFromUnknown(item, depth + 1)).join('')
-  }
-
-  if (typeof value === 'object') {
-    const row = value as Record<string, unknown>
-    const textValue = row.text ?? row.output_text ?? row.content ?? row.message
-    const nestedText = textFromUnknown(textValue, depth + 1)
-
-    if (nestedText) {
-      return nestedText
-    }
-
-    try {
-      return JSON.stringify(value)
-    } catch {
-      return ''
-    }
-  }
-
-  return String(value)
-}
-
-function displayContentForMessage(role: SessionMessage['role'], content: unknown): string {
-  const textContent = textFromUnknown(content)
-
-  if (role !== 'user') {
-    return textContent
-  }
-
-  // A `/skill` turn is stored expanded (the whole skill body). Current
-  // gateways project it to the invocation before it ever reaches us; this is
-  // the fallback for an older backend that still ships the raw payload.
-  const invocation = skillInvocationText(textContent)
-
-  if (invocation) {
-    return invocation
-  }
-
-  const marker = textContent.match(ATTACHED_CONTEXT_MARKER_RE)
-
-  if (!marker || marker.index === undefined) {
-    return textContent.replace(CONTEXT_WARNINGS_MARKER_RE, '').trim()
-  }
-
-  const visibleText = textContent.slice(0, marker.index).replace(CONTEXT_WARNINGS_MARKER_RE, '').trim()
-  const attachedContext = textContent.slice(marker.index + marker[0].length)
-  const refs = [...new Set(Array.from(attachedContext.matchAll(CONTEXT_REF_RE)).map(match => match[0]))]
-
-  // The prose keeps the `@file:` token the user typed, so it already chips in
-  // place. Only hoist a ref the prose is missing — a turn persisted by an older
-  // backend that stripped the tokens. Re-listing an inline ref would chip twice.
-  const missing = refs.filter(ref => !visibleText.includes(ref))
-
-  return [missing.join('\n'), visibleText].filter(Boolean).join('\n\n') || visibleText
-}
-
-function transcriptContent(displayKind: SessionMessage['display_kind'], content: string): string | null {
-  return displayKind === 'hidden' ? null : content
-}
-
-// A remote backend older than this app serves display_metadata as raw JSON text,
-// and `in` throws on a primitive — which used to fail the whole session resume.
-function parseDisplayMetadata(metadata: SessionMessage['display_metadata']): null | Record<string, unknown> {
-  let parsed: unknown = metadata
-
-  if (typeof parsed === 'string') {
-    try {
-      parsed = JSON.parse(parsed)
-    } catch {
-      return null
-    }
-  }
-
-  return parsed && typeof parsed === 'object' ? (parsed as Record<string, unknown>) : null
-}
-
-function timelineTaskCount(metadata: SessionMessage['display_metadata']): number | undefined {
-  const count = parseDisplayMetadata(metadata)?.task_count
-
-  return typeof count === 'number' ? count : undefined
-}
-
-export function messageReactions(metadata: SessionMessage['display_metadata']): MessageReaction[] {
-  const reactions = parseDisplayMetadata(metadata)?.reactions
-
-  if (!Array.isArray(reactions)) {
-    return []
-  }
-
-  return reactions.filter(
-    (r): r is MessageReaction => Boolean(r) && typeof r === 'object' && typeof (r as MessageReaction).emoji === 'string'
-  )
-}
-
-function timelineDisplayContent(message: SessionMessage, content: string): string {
-  if (message.display_kind === 'model_switch') {
-    return 'model changed'
-  }
-
-  if (message.display_kind === 'auto_continue') {
-    return 'resumed interrupted turn'
-  }
-
-  if (message.display_kind === 'personality_switch') {
-    return 'personality changed'
-  }
-
-  if (message.display_kind === 'async_delegation_complete') {
-    const count = timelineTaskCount(message.display_metadata)
-
-    return count === undefined
-      ? 'background agent work finished'
-      : `${count} background agent${count === 1 ? '' : 's'} finished`
-  }
-
-  return content
-}
-
-const STREAM_PART: Record<'reasoning' | 'text', (text: string, timestamp?: number) => ChatMessagePart> = {
-  reasoning: reasoningPart,
-  text: textPart
-}
-
-function completeOpenStreamParts(parts: ChatMessagePart[], completedAt: number): ChatMessagePart[] {
-  return parts.map(part =>
-    (part.type === 'text' || part.type === 'reasoning') && part.completedAt === undefined
-      ? ({ ...part, completedAt } as ChatMessagePart)
-      : part
-  )
-}
-
-/** Seal every still-open visible activity when the assistant turn stops. */
-export function completeOpenTimelineParts(parts: ChatMessagePart[], completedAt: number): ChatMessagePart[] {
-  return parts.map(part =>
-    part.timestamp !== undefined && part.completedAt === undefined
-      ? ({ ...part, completedAt } as ChatMessagePart)
-      : part
-  )
-}
-
-// Coalesce only adjacent deltas of the same channel. Switching between text
-// and reasoning is a real timeline boundary and must remain visible even when
-// both channels arrive inside one batched renderer flush.
-function appendStreamPart(
-  parts: ChatMessagePart[],
-  type: 'reasoning' | 'text',
-  delta: string,
-  timestamp?: number
-): { index: number; parts: ChatMessagePart[] } {
-  const next = [...parts]
-
-  const tailIndex = next.length - 1
-  const tail = next[tailIndex]
-
-  if (tail?.type === type && tail.completedAt === undefined) {
-    next[tailIndex] = { ...tail, text: `${tail.text}${delta}` } as ChatMessagePart
-
-    return { index: tailIndex, parts: next }
-  }
-
-  if (
-    timestamp !== undefined &&
-    (tail?.type === 'text' || tail?.type === 'reasoning') &&
-    tail.completedAt === undefined
-  ) {
-    next[tailIndex] = { ...tail, completedAt: timestamp } as ChatMessagePart
-  }
-
-  next.push(STREAM_PART[type](delta, timestamp))
-
-  return { index: next.length - 1, parts: next }
-}
-
-export function appendTextPart(parts: ChatMessagePart[], delta: string, timestamp?: number): ChatMessagePart[] {
-  return appendStreamPart(parts, 'text', delta, timestamp).parts
-}
-
-export function appendReasoningPart(parts: ChatMessagePart[], delta: string, timestamp?: number): ChatMessagePart[] {
-  return appendStreamPart(parts, 'reasoning', delta, timestamp).parts
-}
-
-export function appendAssistantTextPart(
-  parts: ChatMessagePart[],
-  delta: string,
-  timestamp?: number
-): ChatMessagePart[] {
-  const { index, parts: next } = appendStreamPart(parts, 'text', delta, timestamp)
-  const part = next[index]
-
-  if (part?.type !== 'text') {
-    return next
-  }
-
-  const mayContainMedia =
-    delta.includes('MEDIA:') || delta.includes('DIA:') || delta.includes('EDIA:') || delta.includes('IA:')
-
-  if (mayContainMedia || part.text.includes('MEDIA:')) {
-    const rendered = renderMediaTags(part.text)
-
-    if (rendered !== part.text) {
-      next[index] = { ...part, text: rendered }
-    }
-  }
-
-  return next
-}
-
-export function hasToolPart(message: ChatMessage): boolean {
-  return message.parts.some(part => part.type === 'tool-call')
-}
-
-function toolId(payload: GatewayEventPayload | undefined): string {
-  return payload?.tool_id || payload?.tool_call_id || payload?.id || ''
-}
-
-let liveToolCounter = 0
-
-function nextLiveToolId(name: string): string {
-  liveToolCounter += 1
-
-  return `live-tool:${name}:${liveToolCounter}`
-}
-
-function firstStringField(record: Record<string, unknown>, keys: readonly string[]): string {
-  for (const key of keys) {
-    const value = record[key]
-
-    if (typeof value === 'string' && value.trim()) {
-      return value.trim()
-    }
-  }
-
-  return ''
-}
-
-function normalizeToolMatchValue(value: string): string {
-  return normalize(value)
-}
-
-function collectToolMatchValues(query: string, context: string, preview: string): string[] {
-  return [...new Set([query, context, preview].map(normalizeToolMatchValue).filter(Boolean))]
-}
-
-function toolPayloadMatchValues(payload: GatewayEventPayload | undefined): string[] {
-  const payloadArgs = liveToolArgs(payload)
-
-  // `question` is clarify's identifying arg: a synthetic row hydrated from
-  // `clarify.request` (a fresh request id) must correlate with the `tool.start`
-  // row (the model's tool_call_id) so the two ids don't produce a duplicate
-  // clarify card — same correlation ClarifyToolPending uses for request↔args.
-  // `server` is setup_mcp's identifying arg, for the identical reason.
-  const query =
-    firstStringField(payloadArgs, ['search_term', 'query', 'question', 'server', 'command', 'code', 'path']) ||
-    batchClarifyMatchValue(payloadArgs.questions)
-
-  const context = typeof payload?.context === 'string' ? payload.context.trim() : ''
-  const preview = typeof payload?.preview === 'string' ? payload.preview.trim() : ''
-
-  return collectToolMatchValues(query, context, preview)
-}
-
-/**
- * The batch-clarify counterpart of the `question` correlation key: a batch
- * payload has no top-level `question`, only `questions[]`, so without this
- * the request row and the tool.start row never match and the card mounts
- * twice. The joined per-question texts identify the batch the same way one
- * question text identifies a single prompt. The `\u0000` separator cannot
- * appear in real question text, so a batch key can never collide with a
- * single-question key.
- */
-function batchClarifyMatchValue(questions: unknown): string {
-  if (!Array.isArray(questions)) {
-    return ''
-  }
-
-  const texts = questions
-    .map(entry => {
-      if (!entry || typeof entry !== 'object') {
-        return ''
-      }
-
-      const question = (entry as Record<string, unknown>).question
-
-      return typeof question === 'string' ? question.trim() : ''
-    })
-    .filter(Boolean)
-
-  return texts.length > 0 ? texts.join('\u0000') : ''
-}
-
-function toolPartMatchValues(part: ChatMessagePart): string[] {
-  if (part.type !== 'tool-call' || !part.args || typeof part.args !== 'object') {
-    return []
-  }
-
-  const args = part.args as Record<string, unknown>
-
-  const query =
-    firstStringField(args, ['search_term', 'query', 'question', 'server', 'command', 'code', 'path']) ||
-    batchClarifyMatchValue(args.questions)
-
-  const context = typeof args.context === 'string' ? args.context.trim() : ''
-  const preview = typeof args.preview === 'string' ? args.preview.trim() : ''
-
-  return collectToolMatchValues(query, context, preview)
-}
-
-function hasToolMatchOverlap(left: string[], right: string[]): boolean {
-  if (!left.length || !right.length) {
-    return false
-  }
-
-  const rightSet = new Set(right)
-
-  return left.some(value => rightSet.has(value))
-}
-
-function findToolPartIndex(
-  parts: ChatMessagePart[],
-  name: string,
-  stableId: string,
-  payload: GatewayEventPayload | undefined,
-  phase: 'running' | 'complete'
-): number {
-  const matchValues = toolPayloadMatchValues(payload)
-  const overlaps = (index: number) => hasToolMatchOverlap(matchValues, toolPartMatchValues(parts[index]))
-
-  if (stableId) {
-    const stableIndex = parts.findIndex(part => part.type === 'tool-call' && part.toolCallId === stableId)
-
-    if (stableIndex >= 0) {
-      return stableIndex
-    }
-
-    // Some live streams start without an id, then complete with one. Fall
-    // through to pending same-name/context matching so the completion updates
-    // the synthetic live row instead of appending a duplicate completed row.
-    if (phase === 'running' && !matchValues.length) {
-      return -1
-    }
-  }
-
-  const pendingIndices = parts
-    .map((part, index) => ({ part, index }))
-    .filter(({ part }) => part.type === 'tool-call' && part.toolName === name && part.result === undefined)
-    .map(({ index }) => index)
-
-  if (pendingIndices.length === 0) {
-    return -1
-  }
-
-  if (matchValues.length) {
-    const contextualIndex = pendingIndices.find(overlaps)
-
-    if (contextualIndex !== undefined) {
-      return contextualIndex
-    }
-  }
-
-  if (pendingIndices.length === 1) {
-    const [singlePendingIndex] = pendingIndices
-
-    if (phase === 'running' && matchValues.length && !overlaps(singlePendingIndex)) {
-      return stableId ? singlePendingIndex : -1
-    }
-
-    return singlePendingIndex
-  }
-
-  // Completion events without stable IDs frequently arrive after multiple
-  // same-name starts (parallel tool calls). Resolve them oldest-first so we
-  // don't collapse an entire burst into a single row.
-  if (phase === 'complete') {
-    return pendingIndices[0]
-  }
-
-  if (stableId) {
-    return pendingIndices[0]
-  }
-
-  // For progress/running events with no stable id, update the most-recent
-  // pending same-name tool instead of creating a phantom extra row.
-  return pendingIndices.at(-1) ?? -1
-}
-
-// Carry todo state across sparse progress payloads: if this todo event lacks
-// a `todos` field, fall back to whatever we previously stored on the part.
-function carryTodos(payload: GatewayEventPayload | undefined, ...prev: unknown[]): { todos: unknown } | undefined {
-  if (payload && Object.hasOwn(payload, 'todos')) {
-    const next = parseTodos(payload.todos)
-
-    return next === null ? undefined : { todos: next }
-  }
-
-  if (payload?.name !== 'todo') {
-    return undefined
-  }
-
-  for (const p of prev) {
-    const carried = parseTodos(recordFromUnknown(p)?.todos)
-
-    if (carried !== null) {
-      return { todos: carried }
-    }
-  }
-
-  return undefined
-}
-
-function toolArgs(payload: GatewayEventPayload | undefined, prevArgs?: unknown): Record<string, unknown> {
-  const prev = parseMaybeJsonObject(prevArgs)
-  const eventArgs = liveToolArgs(payload)
-
-  return {
-    ...prev,
-    ...eventArgs,
-    ...(payload?.context ? { context: payload.context } : {}),
-    ...(payload?.preview ? { preview: payload.preview } : {}),
-    ...carryTodos(payload, prevArgs)
-  }
-}
-
-function toolResult(
-  payload: GatewayEventPayload | undefined,
-  prevResult?: unknown,
-  prevArgs?: unknown
-): Record<string, unknown> {
-  const parsedResult = parseMaybeJsonObject(payload?.result)
-
-  return {
-    ...parsedResult,
-    ...(payload?.inline_diff ? { inline_diff: payload.inline_diff } : {}),
-    ...(payload?.summary ? { summary: payload.summary } : {}),
-    ...(payload?.message ? { message: payload.message } : {}),
-    ...(payload?.preview ? { preview: payload.preview } : {}),
-    ...(payload?.duration_s !== undefined ? { duration_s: payload.duration_s } : {}),
-    ...carryTodos(payload, prevResult, prevArgs),
-    ...(payload?.error ? { error: payload.error } : {})
-  }
-}
-
-export function upsertToolPart(
-  parts: ChatMessagePart[],
-  payload: GatewayEventPayload | undefined,
-  phase: 'running' | 'complete',
-  occurredAt = Date.now() / 1000
-): ChatMessagePart[] {
-  const stableId = toolId(payload)
-  const name = payload?.name || 'tool'
-  // A completion can be the first tool event observed after reconnect, so it
-  // also constitutes a text/reasoning -> tool boundary when no start arrived.
-  const next = completeOpenStreamParts(parts, occurredAt)
-
-  const index = findToolPartIndex(next, name, stableId, payload, phase)
-
-  const prev = index >= 0 ? next[index] : null
-  const prevArgs = prev && 'args' in prev ? prev.args : undefined
-  const prevResult = prev && 'result' in prev ? prev.result : undefined
-  const args = toolArgs(payload, prevArgs)
-
-  const id =
-    stableId ||
-    (prev && 'toolCallId' in prev && typeof prev.toolCallId === 'string' ? prev.toolCallId : '') ||
-    nextLiveToolId(name)
-
-  const base = {
-    type: 'tool-call' as const,
-    toolCallId: id,
-    toolName: name,
-    args: args as never,
-    argsText: JSON.stringify(args),
-    timestamp: prev?.timestamp ?? occurredAt,
-    ...(phase === 'complete' && {
-      completedAt: occurredAt,
-      result: toolResult(payload, prevResult, prevArgs),
-      isError: Boolean(payload?.error)
-    })
-  } satisfies ChatMessagePart
-
-  if (index === -1) {
-    return [...next, base]
-  }
-
-  next[index] = { ...next[index], ...base }
-
-  return next
-}
-
-/**
- * Turn-settle reconciliation: close every tool-call part that never received
- * its completion event. A `tool.complete` lost to a degraded websocket
- * (reconnect, profile swap, hidden window) leaves the part without a `result`,
- * which renders as a permanently spinning tool row even though the turn itself
- * completed. A settled session cannot have tools still running, so an open
- * part at settle time is a lost event, not live work. Pending messages are
- * left alone, and no-op calls return the input array unchanged.
- */
-export function sealOpenToolParts(messages: ChatMessage[]): ChatMessage[] {
-  let changed = false
-
-  const next = messages.map(message => {
-    if (message.role !== 'assistant' || message.pending) {
-      return message
-    }
-
-    let partChanged = false
-
-    const parts = message.parts.map(part => {
-      if (part.type !== 'tool-call' || Object.hasOwn(part, 'result')) {
-        return part
-      }
-
-      partChanged = true
-
-      return { ...part, result: {} }
-    })
-
-    if (!partChanged) {
-      return message
-    }
-
-    changed = true
-
-    return { ...message, parts }
-  })
-
-  return changed ? next : messages
-}
-
-function recordFromUnknown(value: unknown): Record<string, unknown> | null {
-  return value && typeof value === 'object' ? (value as Record<string, unknown>) : null
-}
-
-function parseMaybeJsonObject(value: unknown): Record<string, unknown> {
-  if (value && typeof value === 'object' && !Array.isArray(value)) {
-    return value as Record<string, unknown>
-  }
-
-  if (typeof value !== 'string' || !value.trim()) {
-    return {}
-  }
-
-  try {
-    const parsed = JSON.parse(value)
-
-    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : {}
-  } catch {
-    return {}
-  }
-}
-
-function firstNonEmptyObject(...values: unknown[]): Record<string, unknown> {
-  for (const value of values) {
-    const parsed = parseMaybeJsonObject(value)
-
-    if (Object.keys(parsed).length > 0) {
-      return parsed
-    }
-  }
-
-  return {}
-}
-
-function liveToolArgs(payload: GatewayEventPayload | undefined): Record<string, unknown> {
-  const direct = firstNonEmptyObject(payload?.args, payload?.arguments)
-  const input = firstNonEmptyObject(payload?.input)
-  const fn = recordFromUnknown(input.function)
-
-  const nested = firstNonEmptyObject(
-    input.args,
-    input.arguments,
-    input.parameters,
-    input.input,
-    fn?.arguments,
-    fn?.args,
-    fn?.parameters
-  )
-
-  return {
-    ...input,
-    ...nested,
-    ...direct
-  }
-}
-
-function parseStoredToolResult(content: unknown): unknown {
-  if (content && typeof content === 'object') {
-    return content
-  }
-
-  const textContent = textFromUnknown(content)
-
-  if (!textContent.trim()) {
-    return ''
-  }
-
-  try {
-    return JSON.parse(textContent)
-  } catch {
-    return textContent
-  }
-}
-
-function toolPartFromStoredCall(call: unknown, fallbackIndex: number, timestamp?: number): ChatMessagePart {
-  const row = recordFromUnknown(call) ?? {}
-  const fn = recordFromUnknown(row.function)
-  const id = String(row.id || row.tool_call_id || `stored-tool-${fallbackIndex}`)
-
-  const toolName = String(
-    row.name || row.tool_name || fn?.name || (recordFromUnknown(row.input)?.name as string | undefined) || 'tool'
-  )
-
-  const args = firstNonEmptyObject(fn?.arguments, row.arguments, row.args, row.input)
-
-  return {
-    type: 'tool-call',
-    toolCallId: id,
-    toolName,
-    args: args as never,
-    argsText: Object.keys(args).length ? JSON.stringify(args) : '',
-    ...(timestamp !== undefined ? { timestamp } : {})
-  }
-}
-
-function applyStoredToolResult(messages: ChatMessage[], toolMessage: SessionMessage): boolean {
-  const toolCallId = toolMessage.tool_call_id || undefined
-  const toolName = toolMessage.tool_name || toolMessage.name || 'tool'
-  const content = toolMessage.content || toolMessage.text || toolMessage.context || toolMessage.name
-
-  for (let i = messages.length - 1; i >= 0; i -= 1) {
-    const message = messages[i]
-
-    if (message.role !== 'assistant') {
-      continue
-    }
-
-    const partIndex = message.parts.findIndex(
-      part =>
-        part.type === 'tool-call' &&
-        ((toolCallId && part.toolCallId === toolCallId) || (!toolCallId && part.toolName === toolName))
-    )
-
-    if (partIndex < 0) {
-      continue
-    }
-
-    const parts = [...message.parts]
-    const existing = parts[partIndex]
-    parts[partIndex] = {
-      ...existing,
-      completedAt: toolMessage.timestamp,
-      result: parseStoredToolResult(content),
-      isError: false
-    } as ChatMessagePart
-    messages[i] = { ...message, parts }
-
-    return true
-  }
-
-  return false
-}
-
-function applyStoredToolResultToParts(parts: ChatMessagePart[], toolMessage: SessionMessage): ChatMessagePart[] | null {
-  const toolCallId = toolMessage.tool_call_id || undefined
-  const toolName = toolMessage.tool_name || toolMessage.name || 'tool'
-  const content = toolMessage.content || toolMessage.text || toolMessage.context || toolMessage.name
-
-  const partIndex = parts.findIndex(
-    part =>
-      part.type === 'tool-call' &&
-      ((toolCallId && part.toolCallId === toolCallId) || (!toolCallId && part.toolName === toolName))
-  )
-
-  if (partIndex < 0) {
-    return null
-  }
-
-  const next = [...parts]
-  const existing = next[partIndex]
-  next[partIndex] = {
-    ...existing,
-    completedAt: toolMessage.timestamp,
-    result: parseStoredToolResult(content),
-    isError: false
-  } as ChatMessagePart
-
-  return next
-}
-
-function storedToolMessagePart(toolMessage: SessionMessage, fallbackIndex: number): ChatMessagePart {
-  const name = toolMessage.tool_name || toolMessage.name || 'tool'
-  const context = textFromUnknown(toolMessage.context || toolMessage.text || toolMessage.content || '')
-  // Prefer the full arguments when the gateway projection carries them:
-  // `context` is an 80-char display preview, and the expanded tool row
-  // rebuilds the real command from args. Keep `context` alongside as the
-  // title-side placeholder.
-  const storedArgs = parseMaybeJsonObject(toolMessage.args)
-  const args = { ...storedArgs, ...(context ? { context } : {}) }
-
-  return {
-    type: 'tool-call',
-    toolCallId: toolMessage.tool_call_id || `stored-tool-message-${fallbackIndex}`,
-    toolName: name,
-    args: args as never,
-    argsText: Object.keys(args).length ? JSON.stringify(args) : '',
-    timestamp: toolMessage.timestamp,
-    completedAt: toolMessage.timestamp,
-    result: context ? { context } : {},
-    isError: false
-  }
-}
-
-function withUniqueToolCallIds(messages: ChatMessage[]): ChatMessage[] {
-  const seen = new Set<string>()
-
-  return messages.map(message => {
-    let changed = false
-
-    const parts = message.parts.map((part, index) => {
-      if (part.type !== 'tool-call') {
-        return part
-      }
-
-      const id = part.toolCallId || `${message.id}-tool-${index}`
-
-      if (!seen.has(id)) {
-        seen.add(id)
-
-        if (part.toolCallId) {
-          return part
-        }
-
-        changed = true
-
-        return { ...part, toolCallId: id } as ChatMessagePart
-      }
-
-      changed = true
-      const uniqueId = `${id}-${message.id}-${index}`
-      seen.add(uniqueId)
-
-      return { ...part, toolCallId: uniqueId } as ChatMessagePart
-    })
-
-    return changed ? { ...message, parts } : message
-  })
-}
-
-export function toChatMessages(messages: SessionMessage[]): ChatMessage[] {
-  const result: ChatMessage[] = []
-  let pendingToolParts: ChatMessagePart[] = []
-  let pendingToolTimestamp: number | undefined
-  let activeAssistantIndex: null | number = null
-
-  const clearPendingTools = () => {
-    pendingToolParts = []
-    pendingToolTimestamp = undefined
-  }
-
-  const earliestTimestamp = (...values: (number | undefined)[]) => {
-    const timestamps = values.filter((value): value is number => value !== undefined)
-
-    return timestamps.length ? Math.min(...timestamps) : undefined
-  }
-
-  const appendPartsToActiveAssistant = (parts: ChatMessagePart[], timestamp?: number): boolean => {
-    if (activeAssistantIndex === null) {
-      return false
-    }
-
-    const active = result[activeAssistantIndex]
-
-    if (!active || active.role !== 'assistant') {
-      activeAssistantIndex = null
-
-      return false
-    }
-
-    active.parts = [...active.parts, ...parts]
-    active.timestamp = earliestTimestamp(active.timestamp, timestamp, ...parts.map(part => part.timestamp))
-
-    return true
-  }
-
-  const flushPendingTools = (index: number) => {
-    if (!pendingToolParts.length) {
-      return
-    }
-
-    if (!appendPartsToActiveAssistant(pendingToolParts, pendingToolTimestamp)) {
-      result.push({
-        id: `${pendingToolTimestamp || Date.now()}-${index}-tools`,
-        role: 'assistant',
-        parts: pendingToolParts,
-        timestamp: pendingToolTimestamp
-      })
-      activeAssistantIndex = result.length - 1
-    }
-
-    clearPendingTools()
-  }
-
-  messages.forEach((message, index) => {
-    if (message.role === 'tool') {
-      const updatedPendingToolParts = applyStoredToolResultToParts(pendingToolParts, message)
-
-      if (updatedPendingToolParts) {
-        pendingToolParts = updatedPendingToolParts
-
-        return
-      }
-
-      if (applyStoredToolResult(result, message)) {
-        return
-      }
-
-      pendingToolParts = [...pendingToolParts, storedToolMessagePart(message, index)]
-      pendingToolTimestamp ??= message.timestamp
-
-      return
-    }
-
-    const content = message.content || message.text || message.context || message.name
-
-    const rawDisplayContent = transcriptContent(
-      message.display_kind,
-      timelineDisplayContent(message, displayContentForMessage(message.role, content))
-    )
-
-    const displayRole =
-      message.display_kind === 'model_switch' ||
-      message.display_kind === 'async_delegation_complete' ||
-      message.display_kind === 'auto_continue' ||
-      message.display_kind === 'personality_switch'
-        ? 'system'
-        : message.role
-
-    // Persisted user turns carry `@image:<path>` directive lines inline in
-    // the text (see tui_gateway/server.py's persist-time rewrite). The
-    // read-only bubble clamps its body to ~2 lines, and a large inline image
-    // thumbnail pushes any caption text below the clamp's visible area — so
-    // pull image refs out into `attachmentRefs` (same shape the local
-    // optimistic composer already uses) and render them via the dedicated
-    // attachments row below the bubble instead.
-    const imageRefExtraction = displayRole === 'user' && rawDisplayContent ? extractImageRefs(rawDisplayContent) : null
-    const displayContent = imageRefExtraction ? imageRefExtraction.cleanedText : rawDisplayContent
-    const extractedAttachmentRefs = imageRefExtraction?.refs.length ? imageRefExtraction.refs : undefined
-
-    const parts: ChatMessagePart[] = []
-
-    const reasoning =
-      message.reasoning ||
-      message.reasoning_content ||
-      (typeof message.reasoning_details === 'string' ? message.reasoning_details : '')
-
-    if (reasoning && message.role === 'assistant') {
-      parts.push(reasoningPart(reasoning, message.timestamp))
-    }
-
-    if (displayContent) {
-      parts.push(
-        displayRole === 'assistant'
-          ? assistantTextPart(displayContent, message.timestamp)
-          : textPart(displayContent, message.timestamp)
-      )
-    }
-
-    if (message.role === 'assistant' && Array.isArray(message.tool_calls)) {
-      parts.push(
-        ...message.tool_calls.map((call, callIndex) => toolPartFromStoredCall(call, callIndex, message.timestamp))
-      )
-    }
-
-    if (!parts.length && !extractedAttachmentRefs?.length) {
-      if (message.role !== 'assistant') {
-        flushPendingTools(index)
-        activeAssistantIndex = null
-      }
-
-      return
-    }
-
-    const isToolOnlyAssistant =
-      message.role === 'assistant' && parts.length > 0 && parts.every(part => part.type === 'tool-call')
-
-    if (isToolOnlyAssistant) {
-      pendingToolParts = [...pendingToolParts, ...parts]
-      pendingToolTimestamp ??= message.timestamp
-
-      return
-    }
-
-    if (message.role === 'assistant') {
-      if (pendingToolParts.length) {
-        if (!appendPartsToActiveAssistant(pendingToolParts, message.timestamp ?? pendingToolTimestamp)) {
-          parts.unshift(...pendingToolParts)
-        }
-
-        clearPendingTools()
-      }
-
-      const activeAssistant =
-        activeAssistantIndex !== null && result[activeAssistantIndex]?.role === 'assistant'
-          ? result[activeAssistantIndex]
-          : null
-
-      const currentHasToolCall = parts.some(part => part.type === 'tool-call')
-      const activeHasToolCall = Boolean(activeAssistant?.parts.some(part => part.type === 'tool-call'))
-
-      if (activeAssistant && (currentHasToolCall || activeHasToolCall)) {
-        activeAssistant.parts = [...activeAssistant.parts, ...parts]
-        activeAssistant.timestamp = earliestTimestamp(
-          activeAssistant.timestamp,
-          message.timestamp,
-          ...parts.map(part => part.timestamp)
-        )
-
-        return
-      }
-    } else {
-      flushPendingTools(index)
-    }
-
-    const reactions = messageReactions(message.display_metadata)
-    // Gateway resume names the durable row id `row_id`; the REST transcript
-    // prefetch ships the same messages.id as a numeric `id`. Either one lets
-    // reactions address this exact row later.
-    const rowId = message.row_id ?? (typeof message.id === 'number' ? message.id : undefined)
-
-    result.push({
-      id: `${message.timestamp || Date.now()}-${index}-${displayRole}`,
-      role: displayRole,
-      parts,
-      timestamp: earliestTimestamp(message.timestamp, ...parts.map(part => part.timestamp)),
-      ...(rowId !== undefined ? { rowId } : {}),
-      ...(reactions.length ? { reactions } : {}),
-      ...(extractedAttachmentRefs ? { attachmentRefs: extractedAttachmentRefs } : {})
-    })
-
-    activeAssistantIndex = message.role === 'assistant' ? result.length - 1 : null
-  })
-  flushPendingTools(messages.length)
-
-  const withoutGeneratedImageEchoes = result.map(message =>
-    message.role === 'assistant'
-      ? { ...message, parts: dedupeRepeatedTextInParts(dedupeGeneratedImageEchoesInParts(message.parts)) }
-      : message
-  )
-
-  return withUniqueToolCallIds(
-    withoutGeneratedImageEchoes.filter(
-      m => chatMessageText(m).trim() || m.parts.some(part => part.type !== 'text') || m.attachmentRefs?.length
-    )
-  )
-}
-
-const validTimelineBoundary = (value: unknown): value is number =>
-  typeof value === 'number' && Number.isFinite(value) && value > 0
-
-const earliestBoundary = (...values: (number | undefined)[]) => {
-  const valid = values.filter(validTimelineBoundary)
-
-  return valid.length ? Math.min(...valid) : undefined
-}
-
-const latestBoundary = (...values: (number | undefined)[]) => {
-  const valid = values.filter(validTimelineBoundary)
-
-  return valid.length ? Math.max(...valid) : undefined
-}
-
-const normalizedTimelineText = (message: ChatMessage) => chatMessageText(message).replace(/\s+/g, ' ').trim()
-
-const assistantTimelineMatch = (stored: ChatMessage, local: ChatMessage) => {
-  if (stored.id === local.id) {
-    return true
-  }
-
-  const localToolIds = new Set(
-    local.parts
-      .filter(part => part.type === 'tool-call')
-      .map(part => (part.type === 'tool-call' ? part.toolCallId : ''))
-  )
-
-  const toolMatch = stored.parts.some(part => part.type === 'tool-call' && localToolIds.has(part.toolCallId))
-
-  if (toolMatch) {
-    return true
-  }
-
-  const storedText = normalizedTimelineText(stored)
-
-  return Boolean(storedText) && storedText === normalizedTimelineText(local)
-}
-
-const timelinePartMatch = (stored: ChatMessagePart, local: ChatMessagePart) => {
-  if (stored.type !== local.type) {
-    return false
-  }
-
-  if (stored.type === 'tool-call' && local.type === 'tool-call') {
-    return stored.toolCallId === local.toolCallId
-  }
-
-  if ((stored.type === 'text' || stored.type === 'reasoning') && local.type === stored.type) {
-    return stored.text.replace(/\s+/g, ' ').trim() === local.text.replace(/\s+/g, ' ').trim()
-  }
-
-  return false
-}
-
-/** Keep richer live timing when durable hydration has only one timestamp per row. */
-export function reconcileLocalAssistantTimeline(
-  nextMessages: ChatMessage[],
-  currentMessages: ChatMessage[]
-): ChatMessage[] {
-  const localAssistants = currentMessages.filter(message => message.role === 'assistant' && !message.hidden)
-  const matches = new Map<number, ChatMessage>()
-  let localCursor = localAssistants.length - 1
-
-  for (let nextIndex = nextMessages.length - 1; nextIndex >= 0; nextIndex -= 1) {
-    const message = nextMessages[nextIndex]
-
-    if (message.role !== 'assistant' || message.hidden) {
-      continue
-    }
-
-    for (let localIndex = localCursor; localIndex >= 0; localIndex -= 1) {
-      const local = localAssistants[localIndex]
-
-      if (assistantTimelineMatch(message, local)) {
-        matches.set(nextIndex, local)
-        localCursor = localIndex - 1
-
-        break
-      }
-    }
-  }
-
-  return nextMessages.map((message, messageIndex) => {
-    const local = matches.get(messageIndex)
-
-    if (!local) {
-      return message
-    }
-
-    const unusedLocalParts = new Set(local.parts.map((_, index) => index))
-
-    const parts = message.parts.map(part => {
-      const localIndex = local.parts.findIndex(
-        (candidate, index) => unusedLocalParts.has(index) && timelinePartMatch(part, candidate)
-      )
-
-      if (localIndex === -1) {
-        return part
-      }
-
-      unusedLocalParts.delete(localIndex)
-      const localPart = local.parts[localIndex]
-
-      return {
-        ...part,
-        completedAt: latestBoundary(part.completedAt, localPart.completedAt),
-        timestamp: earliestBoundary(part.timestamp, localPart.timestamp)
-      } as ChatMessagePart
-    })
-
-    return {
-      ...message,
-      completedAt: latestBoundary(message.completedAt, local.completedAt, ...parts.map(part => part.completedAt)),
-      parts,
-      timestamp: earliestBoundary(message.timestamp, local.timestamp, ...parts.map(part => part.timestamp))
-    }
-  })
-}
-
-export function preserveLocalAssistantErrors(
-  nextMessages: ChatMessage[],
-  currentMessages: ChatMessage[]
-): ChatMessage[] {
-  nextMessages = reconcileLocalAssistantTimeline(nextMessages, currentMessages)
-  const localById = new Map(currentMessages.map(message => [message.id, message]))
-
-  const mergedNextMessages = nextMessages.map(message => {
-    if (message.role !== 'assistant' || message.error || message.hidden) {
-      return message
-    }
-
-    const local = localById.get(message.id)
-
-    if (!local || local.role !== 'assistant' || !local.error || local.hidden) {
-      return message
-    }
-
-    return {
-      ...message,
-      error: local.error,
-      pending: false
-    }
-  })
-
-  const existingIds = new Set(mergedNextMessages.map(message => message.id))
-  const preserveIds = new Set<string>()
-  const normalize = (value: string) => value.replace(/\s+/g, ' ').trim()
-  const tailUserInNext = [...mergedNextMessages].reverse().find(message => message.role === 'user' && !message.hidden)
-  const tailUserText = tailUserInNext ? normalize(chatMessageText(tailUserInNext)) : ''
-  const tailUserRefs = tailUserInNext ? (tailUserInNext.attachmentRefs ?? []).join('\n') : ''
-
-  const matchesTailUserInNext = (candidate: ChatMessage) =>
-    Boolean(tailUserInNext) &&
-    normalize(chatMessageText(candidate)) === tailUserText &&
-    (candidate.attachmentRefs ?? []).join('\n') === tailUserRefs
-
-  for (let index = 0; index < currentMessages.length; index += 1) {
-    const message = currentMessages[index]
-
-    if (message.role !== 'assistant' || !message.error || message.hidden || existingIds.has(message.id)) {
-      continue
-    }
-
-    preserveIds.add(message.id)
-
-    for (let probe = index - 1; probe >= 0; probe -= 1) {
-      const candidate = currentMessages[probe]
-
-      if (candidate.hidden) {
-        continue
-      }
-
-      if (candidate.role === 'user' && !existingIds.has(candidate.id) && !matchesTailUserInNext(candidate)) {
-        preserveIds.add(candidate.id)
-      }
-
-      break
-    }
-  }
-
-  if (preserveIds.size === 0) {
-    return mergedNextMessages
-  }
-
-  const preserved = currentMessages
-    .filter(message => preserveIds.has(message.id))
-    .map(message => ({ ...message, pending: false }))
-
-  return [...mergedNextMessages, ...preserved]
-}
-
-export function branchGroupForUser(userMessage: ChatMessage): string {
-  return `branch:${userMessage.id}`
-}
diff --git a/apps/desktop/src/lib/chat-messages/hydration.ts b/apps/desktop/src/lib/chat-messages/hydration.ts
new file mode 100644
index 0000000000..13fef62d32
--- /dev/null
+++ b/apps/desktop/src/lib/chat-messages/hydration.ts
@@ -0,0 +1,324 @@
+import { skillInvocationText } from '@hermes/shared'
+
+import { extractImageRefs } from '@/lib/embedded-images'
+import { dedupeGeneratedImageEchoesInParts } from '@/lib/generated-images'
+import type { MessageReaction, SessionMessage } from '@/types/hermes'
+
+import { assistantTextPart, chatMessageText, dedupeRepeatedTextInParts, reasoningPart, textPart } from './parts'
+import {
+  applyStoredToolResult,
+  applyStoredToolResultToParts,
+  storedToolMessagePart,
+  textFromUnknown,
+  toolPartFromStoredCall,
+  withUniqueToolCallIds
+} from './tool-parts'
+import type { ChatMessage, ChatMessagePart } from './types'
+
+const ATTACHED_CONTEXT_MARKER_RE = /(?:^|\n)--- Attached Context ---\s*\n/
+const CONTEXT_WARNINGS_MARKER_RE = /(?:^|\n)--- Context Warnings ---[\s\S]*$/
+const CONTEXT_REF_RE = /@(file|folder|url|image|tool|terminal):(?:"[^"\n]+"|'[^'\n]+'|`[^`\n]+`|\S+)/g
+
+function displayContentForMessage(role: SessionMessage['role'], content: unknown): string {
+  const textContent = textFromUnknown(content)
+
+  if (role !== 'user') {
+    return textContent
+  }
+
+  // A `/skill` turn is stored expanded (the whole skill body). Current
+  // gateways project it to the invocation before it ever reaches us; this is
+  // the fallback for an older backend that still ships the raw payload.
+  const invocation = skillInvocationText(textContent)
+
+  if (invocation) {
+    return invocation
+  }
+
+  const marker = textContent.match(ATTACHED_CONTEXT_MARKER_RE)
+
+  if (!marker || marker.index === undefined) {
+    return textContent.replace(CONTEXT_WARNINGS_MARKER_RE, '').trim()
+  }
+
+  const visibleText = textContent.slice(0, marker.index).replace(CONTEXT_WARNINGS_MARKER_RE, '').trim()
+  const attachedContext = textContent.slice(marker.index + marker[0].length)
+  const refs = [...new Set(Array.from(attachedContext.matchAll(CONTEXT_REF_RE)).map(match => match[0]))]
+
+  // The prose keeps the `@file:` token the user typed, so it already chips in
+  // place. Only hoist a ref the prose is missing — a turn persisted by an older
+  // backend that stripped the tokens. Re-listing an inline ref would chip twice.
+  const missing = refs.filter(ref => !visibleText.includes(ref))
+
+  return [missing.join('\n'), visibleText].filter(Boolean).join('\n\n') || visibleText
+}
+
+function transcriptContent(displayKind: SessionMessage['display_kind'], content: string): string | null {
+  return displayKind === 'hidden' ? null : content
+}
+
+// A remote backend older than this app serves display_metadata as raw JSON text,
+// and `in` throws on a primitive — which used to fail the whole session resume.
+function parseDisplayMetadata(metadata: SessionMessage['display_metadata']): null | Record<string, unknown> {
+  let parsed: unknown = metadata
+
+  if (typeof parsed === 'string') {
+    try {
+      parsed = JSON.parse(parsed)
+    } catch {
+      return null
+    }
+  }
+
+  return parsed && typeof parsed === 'object' ? (parsed as Record<string, unknown>) : null
+}
+
+function timelineTaskCount(metadata: SessionMessage['display_metadata']): number | undefined {
+  const count = parseDisplayMetadata(metadata)?.task_count
+
+  return typeof count === 'number' ? count : undefined
+}
+
+function messageReactions(metadata: SessionMessage['display_metadata']): MessageReaction[] {
+  const reactions = parseDisplayMetadata(metadata)?.reactions
+
+  if (!Array.isArray(reactions)) {
+    return []
+  }
+
+  return reactions.filter(
+    (r): r is MessageReaction => Boolean(r) && typeof r === 'object' && typeof (r as MessageReaction).emoji === 'string'
+  )
+}
+
+function timelineDisplayContent(message: SessionMessage, content: string): string {
+  if (message.display_kind === 'model_switch') {
+    return 'model changed'
+  }
+
+  if (message.display_kind === 'auto_continue') {
+    return 'resumed interrupted turn'
+  }
+
+  if (message.display_kind === 'personality_switch') {
+    return 'personality changed'
+  }
+
+  if (message.display_kind === 'async_delegation_complete') {
+    const count = timelineTaskCount(message.display_metadata)
+
+    return count === undefined
+      ? 'background agent work finished'
+      : `${count} background agent${count === 1 ? '' : 's'} finished`
+  }
+
+  return content
+}
+
+export function toChatMessages(messages: SessionMessage[]): ChatMessage[] {
+  const result: ChatMessage[] = []
+  let pendingToolParts: ChatMessagePart[] = []
+  let pendingToolTimestamp: number | undefined
+  let activeAssistantIndex: null | number = null
+
+  const clearPendingTools = () => {
+    pendingToolParts = []
+    pendingToolTimestamp = undefined
+  }
+
+  const earliestTimestamp = (...values: (number | undefined)[]) => {
+    const timestamps = values.filter((value): value is number => value !== undefined)
+
+    return timestamps.length ? Math.min(...timestamps) : undefined
+  }
+
+  const appendPartsToActiveAssistant = (parts: ChatMessagePart[], timestamp?: number): boolean => {
+    if (activeAssistantIndex === null) {
+      return false
+    }
+
+    const active = result[activeAssistantIndex]
+
+    if (!active || active.role !== 'assistant') {
+      activeAssistantIndex = null
+
+      return false
+    }
+
+    active.parts = [...active.parts, ...parts]
+    active.timestamp = earliestTimestamp(active.timestamp, timestamp, ...parts.map(part => part.timestamp))
+
+    return true
+  }
+
+  const flushPendingTools = (index: number) => {
+    if (!pendingToolParts.length) {
+      return
+    }
+
+    if (!appendPartsToActiveAssistant(pendingToolParts, pendingToolTimestamp)) {
+      result.push({
+        id: `${pendingToolTimestamp || Date.now()}-${index}-tools`,
+        role: 'assistant',
+        parts: pendingToolParts,
+        timestamp: pendingToolTimestamp
+      })
+      activeAssistantIndex = result.length - 1
+    }
+
+    clearPendingTools()
+  }
+
+  messages.forEach((message, index) => {
+    if (message.role === 'tool') {
+      const updatedPendingToolParts = applyStoredToolResultToParts(pendingToolParts, message)
+
+      if (updatedPendingToolParts) {
+        pendingToolParts = updatedPendingToolParts
+
+        return
+      }
+
+      if (applyStoredToolResult(result, message)) {
+        return
+      }
+
+      pendingToolParts = [...pendingToolParts, storedToolMessagePart(message, index)]
+      pendingToolTimestamp ??= message.timestamp
+
+      return
+    }
+
+    const content = message.content || message.text || message.context || message.name
+
+    const rawDisplayContent = transcriptContent(
+      message.display_kind,
+      timelineDisplayContent(message, displayContentForMessage(message.role, content))
+    )
+
+    const displayRole =
+      message.display_kind === 'model_switch' ||
+      message.display_kind === 'async_delegation_complete' ||
+      message.display_kind === 'auto_continue' ||
+      message.display_kind === 'personality_switch'
+        ? 'system'
+        : message.role
+
+    // Persisted user turns carry `@image:<path>` directive lines inline in
+    // the text (see tui_gateway/server.py's persist-time rewrite). The
+    // read-only bubble clamps its body to ~2 lines, and a large inline image
+    // thumbnail pushes any caption text below the clamp's visible area — so
+    // pull image refs out into `attachmentRefs` (same shape the local
+    // optimistic composer already uses) and render them via the dedicated
+    // attachments row below the bubble instead.
+    const imageRefExtraction = displayRole === 'user' && rawDisplayContent ? extractImageRefs(rawDisplayContent) : null
+    const displayContent = imageRefExtraction ? imageRefExtraction.cleanedText : rawDisplayContent
+    const extractedAttachmentRefs = imageRefExtraction?.refs.length ? imageRefExtraction.refs : undefined
+
+    const parts: ChatMessagePart[] = []
+
+    const reasoning =
+      message.reasoning ||
+      message.reasoning_content ||
+      (typeof message.reasoning_details === 'string' ? message.reasoning_details : '')
+
+    if (reasoning && message.role === 'assistant') {
+      parts.push(reasoningPart(reasoning, message.timestamp))
+    }
+
+    if (displayContent) {
+      parts.push(
+        displayRole === 'assistant'
+          ? assistantTextPart(displayContent, message.timestamp)
+          : textPart(displayContent, message.timestamp)
+      )
+    }
+
+    if (message.role === 'assistant' && Array.isArray(message.tool_calls)) {
+      parts.push(
+        ...message.tool_calls.map((call, callIndex) => toolPartFromStoredCall(call, callIndex, message.timestamp))
+      )
+    }
+
+    if (!parts.length && !extractedAttachmentRefs?.length) {
+      if (message.role !== 'assistant') {
+        flushPendingTools(index)
+        activeAssistantIndex = null
+      }
+
+      return
+    }
+
+    const isToolOnlyAssistant =
+      message.role === 'assistant' && parts.length > 0 && parts.every(part => part.type === 'tool-call')
+
+    if (isToolOnlyAssistant) {
+      pendingToolParts = [...pendingToolParts, ...parts]
+      pendingToolTimestamp ??= message.timestamp
+
+      return
+    }
+
+    if (message.role === 'assistant') {
+      if (pendingToolParts.length) {
+        if (!appendPartsToActiveAssistant(pendingToolParts, message.timestamp ?? pendingToolTimestamp)) {
+          parts.unshift(...pendingToolParts)
+        }
+
+        clearPendingTools()
+      }
+
+      const activeAssistant =
+        activeAssistantIndex !== null && result[activeAssistantIndex]?.role === 'assistant'
+          ? result[activeAssistantIndex]
+          : null
+
+      const currentHasToolCall = parts.some(part => part.type === 'tool-call')
+      const activeHasToolCall = Boolean(activeAssistant?.parts.some(part => part.type === 'tool-call'))
+
+      if (activeAssistant && (currentHasToolCall || activeHasToolCall)) {
+        activeAssistant.parts = [...activeAssistant.parts, ...parts]
+        activeAssistant.timestamp = earliestTimestamp(
+          activeAssistant.timestamp,
+          message.timestamp,
+          ...parts.map(part => part.timestamp)
+        )
+
+        return
+      }
+    } else {
+      flushPendingTools(index)
+    }
+
+    const reactions = messageReactions(message.display_metadata)
+    // Gateway resume names the durable row id `row_id`; the REST transcript
+    // prefetch ships the same messages.id as a numeric `id`. Either one lets
+    // reactions address this exact row later.
+    const rowId = message.row_id ?? (typeof message.id === 'number' ? message.id : undefined)
+
+    result.push({
+      id: `${message.timestamp || Date.now()}-${index}-${displayRole}`,
+      role: displayRole,
+      parts,
+      timestamp: earliestTimestamp(message.timestamp, ...parts.map(part => part.timestamp)),
+      ...(rowId !== undefined ? { rowId } : {}),
+      ...(reactions.length ? { reactions } : {}),
+      ...(extractedAttachmentRefs ? { attachmentRefs: extractedAttachmentRefs } : {})
+    })
+
+    activeAssistantIndex = message.role === 'assistant' ? result.length - 1 : null
+  })
+  flushPendingTools(messages.length)
+
+  const withoutGeneratedImageEchoes = result.map(message =>
+    message.role === 'assistant'
+      ? { ...message, parts: dedupeRepeatedTextInParts(dedupeGeneratedImageEchoesInParts(message.parts)) }
+      : message
+  )
+
+  return withUniqueToolCallIds(
+    withoutGeneratedImageEchoes.filter(
+      m => chatMessageText(m).trim() || m.parts.some(part => part.type !== 'text') || m.attachmentRefs?.length
+    )
+  )
+}
diff --git a/apps/desktop/src/lib/chat-messages/index.ts b/apps/desktop/src/lib/chat-messages/index.ts
new file mode 100644
index 0000000000..259a607a04
--- /dev/null
+++ b/apps/desktop/src/lib/chat-messages/index.ts
@@ -0,0 +1,18 @@
+export { toChatMessages } from './hydration'
+export {
+  appendAssistantTextPart,
+  appendReasoningPart,
+  assistantTextPart,
+  chatMessageText,
+  collectUnspokenTurnSpeech,
+  completeOpenTimelineParts,
+  dedupeRepeatedTextInParts,
+  mergeFinalAssistantText,
+  reasoningPart,
+  renderMediaTags,
+  textPart
+} from './parts'
+export type { UnspokenTurnSpeech } from './parts'
+export { branchGroupForUser, preserveLocalAssistantErrors } from './reconciliation'
+export { sealOpenToolParts, upsertToolPart } from './tool-parts'
+export type { ChatMessage, ChatMessagePart, GatewayEventPayload, TimelinePartMetadata } from './types'
diff --git a/apps/desktop/src/lib/chat-messages/parts.ts b/apps/desktop/src/lib/chat-messages/parts.ts
new file mode 100644
index 0000000000..158f85779c
--- /dev/null
+++ b/apps/desktop/src/lib/chat-messages/parts.ts
@@ -0,0 +1,284 @@
+import { mediaDisplayLabel, mediaMarkdownHref } from '@/lib/media'
+
+import type { ChatMessage, ChatMessagePart } from './types'
+
+export function textPart(text: string, timestamp?: number): ChatMessagePart {
+  return { type: 'text', text, ...(timestamp !== undefined ? { timestamp } : {}) }
+}
+
+export function reasoningPart(text: string, timestamp?: number): ChatMessagePart {
+  return { type: 'reasoning', text, ...(timestamp !== undefined ? { timestamp } : {}) }
+}
+
+const MEDIA_LINE_RE = /(^|\n)[\t ]*[`"']?MEDIA:\s*(?<line>`[^`\n]+`|"[^"\n]+"|'[^'\n]+'|\S+)[`"']?[\t ]*(\n|$)/g
+
+const MEDIA_TAG_RE = /[`"']?MEDIA:\s*(?<inline>`[^`\n]+`|"[^"\n]+"|'[^'\n]+'|\S+)[`"']?/g
+
+function unquoteMediaPath(value: string): string {
+  const trimmed = value.trim()
+  const quote = trimmed[0]
+
+  return quote && quote === trimmed.at(-1) && ['"', "'", '`'].includes(quote) ? trimmed.slice(1, -1) : trimmed
+}
+
+function mediaLink(value: string): string {
+  const path = unquoteMediaPath(value)
+
+  return `[${mediaDisplayLabel(path)}](${mediaMarkdownHref(path)})`
+}
+
+export function renderMediaTags(text: string): string {
+  return text
+    .replace(
+      MEDIA_LINE_RE,
+      (_match, lead: string, value: string, trailer: string) => `${lead}${mediaLink(value)}${trailer}`
+    )
+    .replace(MEDIA_TAG_RE, (_match, value: string) => mediaLink(value))
+    .replace(/[ \t]+\n/g, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+}
+
+export function assistantTextPart(text: string, timestamp?: number): ChatMessagePart {
+  return textPart(renderMediaTags(text), timestamp)
+}
+
+export function chatMessageText(message: ChatMessage): string {
+  return message.parts
+    .filter((part): part is Extract<ChatMessagePart, { type: 'text' }> => part.type === 'text')
+    .map(part => part.text)
+    .join('')
+}
+
+export interface UnspokenTurnSpeech {
+  /** First unspoken assistant bubble — stable for the turn, the live speech session binds to it. */
+  id: string
+  /** Whether the newest assistant bubble is still streaming. */
+  pending: boolean
+  /** All unspoken assistant text in message order, bubbles joined on a blank line. */
+  text: string
+}
+
+/**
+ * Collect every unspoken assistant bubble after `lastSpokenId`, in order.
+ *
+ * A turn with tool calls produces several assistant bubbles — narration
+ * ("Let me check…") sealed as interims, then the final answer as a fresh
+ * bubble. Voice conversation speaks a turn through ONE live session bound to
+ * one response id, so it needs all of that text as a single growing string;
+ * selecting only one bubble silently drops everything after it. The blank-line
+ * join is a sentence boundary for the server's cutter, so a sealed bubble's
+ * tail is flushed as soon as the next bubble starts.
+ */
+export function collectUnspokenTurnSpeech(
+  messages: ChatMessage[],
+  lastSpokenId: string | null
+): UnspokenTurnSpeech | null {
+  const spokenIndex = lastSpokenId ? messages.findLastIndex(m => m.id === lastSpokenId) : -1
+
+  let id: string | null = null
+  let pending = false
+  const parts: string[] = []
+
+  for (const message of messages.slice(spokenIndex + 1)) {
+    if (message.role !== 'assistant' || message.hidden) {
+      continue
+    }
+
+    pending = Boolean(message.pending)
+    const text = chatMessageText(message).trim()
+
+    if (!text) {
+      continue
+    }
+
+    id ??= message.id
+    parts.push(text)
+  }
+
+  if (!id) {
+    return null
+  }
+
+  return { id, pending, text: parts.join('\n\n') }
+}
+
+const normalizeWs = (value: string) => value.replace(/\s+/g, ' ').trim()
+
+/**
+ * Drop earlier text parts that a later text part repeats verbatim (after
+ * whitespace normalization). Providers that continue a turn after a tool
+ * call sometimes re-send the previous assistant text as the next message's
+ * prefix (tool_calls row, then a stop row with identical prose) — the turn
+ * merge then holds the same paragraph twice and everything in it renders
+ * twice, most visibly ::preview frames. The LAST occurrence is the
+ * authoritative one; keep it.
+ */
+export function dedupeRepeatedTextInParts(parts: ChatMessagePart[]): ChatMessagePart[] {
+  const lastByText = new Map<string, number>()
+
+  parts.forEach((part, index) => {
+    if (part.type === 'text') {
+      const key = normalizeWs(part.text)
+
+      if (key) {
+        lastByText.set(key, index)
+      }
+    }
+  })
+
+  const dropped = parts.filter((part, index) => {
+    if (part.type !== 'text') {
+      return true
+    }
+
+    const key = normalizeWs(part.text)
+
+    return !key || lastByText.get(key) === index
+  })
+
+  return dropped.length === parts.length ? parts : dropped
+}
+
+/**
+ * Merge the final assistant text into a message's parts.
+ *
+ * - Removes all existing `text` parts (they were streamed deltas, now superseded
+ *   by the authoritative final response).
+ * - Keeps `reasoning` parts, but drops one that the final text fully covers
+ *   (reasoning ⊆ final) — the final restates it. A short final ("Done.") must
+ *   NOT swallow a longer reasoning block that merely starts with it (#61447).
+ * - Keeps all other part types (tool-call, image, etc.).
+ * - Appends the final text as a new text part.
+ */
+export function mergeFinalAssistantText(
+  parts: ChatMessagePart[],
+  finalText: string,
+  fallbackTimestamp?: number
+): ChatMessagePart[] {
+  const dedupeReference = normalizeWs(finalText)
+
+  const streamedText = normalizeWs(
+    parts
+      .filter((part): part is Extract<ChatMessagePart, { type: 'text' }> => part.type === 'text')
+      .map(part => part.text)
+      .join('')
+  )
+
+  // An authoritative final that is exactly the concatenation of streamed text
+  // confirms the content without erasing text↔reasoning activity boundaries.
+  if (streamedText && streamedText === dedupeReference) {
+    return parts
+  }
+
+  const previousText = parts.findLast(part => part.type === 'text')
+
+  const kept = parts.filter(part => {
+    if (part.type === 'text') {
+      // Sealed text parts were already finalized into their own bubbles —
+      // this filter only runs on the LAST streaming bubble, so there are no
+      // sealed parts here. All text parts are streamed deltas that get
+      // replaced by the authoritative final text.
+      return false
+    }
+
+    if (part.type !== 'reasoning' || !dedupeReference) {
+      return true
+    }
+
+    // Reasoning is a restatement only when the final FULLY covers it.
+    // The reverse direction is not considered — a short final must not
+    // swallow a longer reasoning block (#61447).
+    const r = normalizeWs(part.text)
+
+    return !(r && dedupeReference.startsWith(r))
+  })
+
+  if (!finalText) {
+    return kept
+  }
+
+  const finalPart = assistantTextPart(finalText, previousText?.timestamp ?? fallbackTimestamp)
+
+  if (previousText?.completedAt !== undefined) {
+    finalPart.completedAt = previousText.completedAt
+  }
+
+  return [...kept, finalPart]
+}
+
+/** Seal every still-open visible activity when the assistant turn stops. */
+export function completeOpenTimelineParts(parts: ChatMessagePart[], completedAt: number): ChatMessagePart[] {
+  return parts.map(part =>
+    part.timestamp !== undefined && part.completedAt === undefined
+      ? ({ ...part, completedAt } as ChatMessagePart)
+      : part
+  )
+}
+
+// Coalesce only adjacent deltas of the same channel. Switching between text
+// and reasoning is a real timeline boundary and must remain visible even when
+// both channels arrive inside one batched renderer flush.
+function appendStreamPart(
+  parts: ChatMessagePart[],
+  type: 'reasoning' | 'text',
+  delta: string,
+  timestamp?: number
+): { index: number; parts: ChatMessagePart[] } {
+  const next = [...parts]
+
+  const tailIndex = next.length - 1
+  const tail = next[tailIndex]
+
+  if (tail?.type === type && tail.completedAt === undefined) {
+    next[tailIndex] = { ...tail, text: `${tail.text}${delta}` } as ChatMessagePart
+
+    return { index: tailIndex, parts: next }
+  }
+
+  if (
+    timestamp !== undefined &&
+    (tail?.type === 'text' || tail?.type === 'reasoning') &&
+    tail.completedAt === undefined
+  ) {
+    next[tailIndex] = { ...tail, completedAt: timestamp } as ChatMessagePart
+  }
+
+  const STREAM_PART: Record<'reasoning' | 'text', (text: string, timestamp?: number) => ChatMessagePart> = {
+    reasoning: reasoningPart,
+    text: textPart
+  }
+
+  next.push(STREAM_PART[type](delta, timestamp))
+
+  return { index: next.length - 1, parts: next }
+}
+
+export function appendReasoningPart(parts: ChatMessagePart[], delta: string, timestamp?: number): ChatMessagePart[] {
+  return appendStreamPart(parts, 'reasoning', delta, timestamp).parts
+}
+
+export function appendAssistantTextPart(
+  parts: ChatMessagePart[],
+  delta: string,
+  timestamp?: number
+): ChatMessagePart[] {
+  const { index, parts: next } = appendStreamPart(parts, 'text', delta, timestamp)
+  const part = next[index]
+
+  if (part?.type !== 'text') {
+    return next
+  }
+
+  const mayContainMedia =
+    delta.includes('MEDIA:') || delta.includes('DIA:') || delta.includes('EDIA:') || delta.includes('IA:')
+
+  if (mayContainMedia || part.text.includes('MEDIA:')) {
+    const rendered = renderMediaTags(part.text)
+
+    if (rendered !== part.text) {
+      next[index] = { ...part, text: rendered }
+    }
+  }
+
+  return next
+}
diff --git a/apps/desktop/src/lib/chat-messages/reconciliation.ts b/apps/desktop/src/lib/chat-messages/reconciliation.ts
new file mode 100644
index 0000000000..7d14446af2
--- /dev/null
+++ b/apps/desktop/src/lib/chat-messages/reconciliation.ts
@@ -0,0 +1,195 @@
+import { chatMessageText } from './parts'
+import type { ChatMessage, ChatMessagePart } from './types'
+
+const validTimelineBoundary = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isFinite(value) && value > 0
+
+const earliestBoundary = (...values: (number | undefined)[]) => {
+  const valid = values.filter(validTimelineBoundary)
+
+  return valid.length ? Math.min(...valid) : undefined
+}
+
+const latestBoundary = (...values: (number | undefined)[]) => {
+  const valid = values.filter(validTimelineBoundary)
+
+  return valid.length ? Math.max(...valid) : undefined
+}
+
+const normalizedTimelineText = (message: ChatMessage) => chatMessageText(message).replace(/\s+/g, ' ').trim()
+
+const assistantTimelineMatch = (stored: ChatMessage, local: ChatMessage) => {
+  if (stored.id === local.id) {
+    return true
+  }
+
+  const localToolIds = new Set(
+    local.parts
+      .filter(part => part.type === 'tool-call')
+      .map(part => (part.type === 'tool-call' ? part.toolCallId : ''))
+  )
+
+  const toolMatch = stored.parts.some(part => part.type === 'tool-call' && localToolIds.has(part.toolCallId))
+
+  if (toolMatch) {
+    return true
+  }
+
+  const storedText = normalizedTimelineText(stored)
+
+  return Boolean(storedText) && storedText === normalizedTimelineText(local)
+}
+
+const timelinePartMatch = (stored: ChatMessagePart, local: ChatMessagePart) => {
+  if (stored.type !== local.type) {
+    return false
+  }
+
+  if (stored.type === 'tool-call' && local.type === 'tool-call') {
+    return stored.toolCallId === local.toolCallId
+  }
+
+  if ((stored.type === 'text' || stored.type === 'reasoning') && local.type === stored.type) {
+    return stored.text.replace(/\s+/g, ' ').trim() === local.text.replace(/\s+/g, ' ').trim()
+  }
+
+  return false
+}
+
+/** Keep richer live timing when durable hydration has only one timestamp per row. */
+function reconcileLocalAssistantTimeline(nextMessages: ChatMessage[], currentMessages: ChatMessage[]): ChatMessage[] {
+  const localAssistants = currentMessages.filter(message => message.role === 'assistant' && !message.hidden)
+  const matches = new Map<number, ChatMessage>()
+  let localCursor = localAssistants.length - 1
+
+  for (let nextIndex = nextMessages.length - 1; nextIndex >= 0; nextIndex -= 1) {
+    const message = nextMessages[nextIndex]
+
+    if (message.role !== 'assistant' || message.hidden) {
+      continue
+    }
+
+    for (let localIndex = localCursor; localIndex >= 0; localIndex -= 1) {
+      const local = localAssistants[localIndex]
+
+      if (assistantTimelineMatch(message, local)) {
+        matches.set(nextIndex, local)
+        localCursor = localIndex - 1
+
+        break
+      }
+    }
+  }
+
+  return nextMessages.map((message, messageIndex) => {
+    const local = matches.get(messageIndex)
+
+    if (!local) {
+      return message
+    }
+
+    const unusedLocalParts = new Set(local.parts.map((_, index) => index))
+
+    const parts = message.parts.map(part => {
+      const localIndex = local.parts.findIndex(
+        (candidate, index) => unusedLocalParts.has(index) && timelinePartMatch(part, candidate)
+      )
+
+      if (localIndex === -1) {
+        return part
+      }
+
+      unusedLocalParts.delete(localIndex)
+      const localPart = local.parts[localIndex]
+
+      return {
+        ...part,
+        completedAt: latestBoundary(part.completedAt, localPart.completedAt),
+        timestamp: earliestBoundary(part.timestamp, localPart.timestamp)
+      } as ChatMessagePart
+    })
+
+    return {
+      ...message,
+      completedAt: latestBoundary(message.completedAt, local.completedAt, ...parts.map(part => part.completedAt)),
+      parts,
+      timestamp: earliestBoundary(message.timestamp, local.timestamp, ...parts.map(part => part.timestamp))
+    }
+  })
+}
+
+export function preserveLocalAssistantErrors(
+  nextMessages: ChatMessage[],
+  currentMessages: ChatMessage[]
+): ChatMessage[] {
+  nextMessages = reconcileLocalAssistantTimeline(nextMessages, currentMessages)
+  const localById = new Map(currentMessages.map(message => [message.id, message]))
+
+  const mergedNextMessages = nextMessages.map(message => {
+    if (message.role !== 'assistant' || message.error || message.hidden) {
+      return message
+    }
+
+    const local = localById.get(message.id)
+
+    if (!local || local.role !== 'assistant' || !local.error || local.hidden) {
+      return message
+    }
+
+    return {
+      ...message,
+      error: local.error,
+      pending: false
+    }
+  })
+
+  const existingIds = new Set(mergedNextMessages.map(message => message.id))
+  const preserveIds = new Set<string>()
+  const normalize = (value: string) => value.replace(/\s+/g, ' ').trim()
+  const tailUserInNext = [...mergedNextMessages].reverse().find(message => message.role === 'user' && !message.hidden)
+  const tailUserText = tailUserInNext ? normalize(chatMessageText(tailUserInNext)) : ''
+  const tailUserRefs = tailUserInNext ? (tailUserInNext.attachmentRefs ?? []).join('\n') : ''
+
+  const matchesTailUserInNext = (candidate: ChatMessage) =>
+    Boolean(tailUserInNext) &&
+    normalize(chatMessageText(candidate)) === tailUserText &&
+    (candidate.attachmentRefs ?? []).join('\n') === tailUserRefs
+
+  for (let index = 0; index < currentMessages.length; index += 1) {
+    const message = currentMessages[index]
+
+    if (message.role !== 'assistant' || !message.error || message.hidden || existingIds.has(message.id)) {
+      continue
+    }
+
+    preserveIds.add(message.id)
+
+    for (let probe = index - 1; probe >= 0; probe -= 1) {
+      const candidate = currentMessages[probe]
+
+      if (candidate.hidden) {
+        continue
+      }
+
+      if (candidate.role === 'user' && !existingIds.has(candidate.id) && !matchesTailUserInNext(candidate)) {
+        preserveIds.add(candidate.id)
+      }
+
+      break
+    }
+  }
+
+  if (preserveIds.size === 0) {
+    return mergedNextMessages
+  }
+
+  const preserved = currentMessages
+    .filter(message => preserveIds.has(message.id))
+    .map(message => ({ ...message, pending: false }))
+
+  return [...mergedNextMessages, ...preserved]
+}
+
+export function branchGroupForUser(userMessage: ChatMessage): string {
+  return `branch:${userMessage.id}`
+}
diff --git a/apps/desktop/src/lib/chat-messages/tool-parts.ts b/apps/desktop/src/lib/chat-messages/tool-parts.ts
new file mode 100644
index 0000000000..6399e09cab
--- /dev/null
+++ b/apps/desktop/src/lib/chat-messages/tool-parts.ts
@@ -0,0 +1,579 @@
+import { firstStringField, normalize } from '@/lib/text'
+import { parseTodos } from '@/lib/todos'
+import type { SessionMessage } from '@/types/hermes'
+
+import type { ChatMessage, ChatMessagePart, GatewayEventPayload } from './types'
+
+function toolId(payload: GatewayEventPayload | undefined): string {
+  return payload?.tool_id || payload?.tool_call_id || payload?.id || ''
+}
+
+let liveToolCounter = 0
+
+function nextLiveToolId(name: string): string {
+  liveToolCounter += 1
+
+  return `live-tool:${name}:${liveToolCounter}`
+}
+
+function normalizeToolMatchValue(value: string): string {
+  return normalize(value)
+}
+
+function collectToolMatchValues(query: string, context: string, preview: string): string[] {
+  return [...new Set([query, context, preview].map(normalizeToolMatchValue).filter(Boolean))]
+}
+
+function recordFromUnknown(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' ? (value as Record<string, unknown>) : null
+}
+
+function parseMaybeJsonObject(value: unknown): Record<string, unknown> {
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    return value as Record<string, unknown>
+  }
+
+  if (typeof value !== 'string' || !value.trim()) {
+    return {}
+  }
+
+  try {
+    const parsed = JSON.parse(value)
+
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : {}
+  } catch {
+    return {}
+  }
+}
+
+function firstNonEmptyObject(...values: unknown[]): Record<string, unknown> {
+  for (const value of values) {
+    const parsed = parseMaybeJsonObject(value)
+
+    if (Object.keys(parsed).length > 0) {
+      return parsed
+    }
+  }
+
+  return {}
+}
+
+function liveToolArgs(payload: GatewayEventPayload | undefined): Record<string, unknown> {
+  const direct = firstNonEmptyObject(payload?.args, payload?.arguments)
+  const input = firstNonEmptyObject(payload?.input)
+  const fn = recordFromUnknown(input.function)
+
+  const nested = firstNonEmptyObject(
+    input.args,
+    input.arguments,
+    input.parameters,
+    input.input,
+    fn?.arguments,
+    fn?.args,
+    fn?.parameters
+  )
+
+  return {
+    ...input,
+    ...nested,
+    ...direct
+  }
+}
+
+function toolPayloadMatchValues(payload: GatewayEventPayload | undefined): string[] {
+  const payloadArgs = liveToolArgs(payload)
+
+  // `question` is clarify's identifying arg: a synthetic row hydrated from
+  // `clarify.request` (a fresh request id) must correlate with the `tool.start`
+  // row (the model's tool_call_id) so the two ids don't produce a duplicate
+  // clarify card — same correlation ClarifyToolPending uses for request↔args.
+  // `server` is setup_mcp's identifying arg, for the identical reason.
+  const query =
+    firstStringField(payloadArgs, ['search_term', 'query', 'question', 'server', 'command', 'code', 'path']) ||
+    batchClarifyMatchValue(payloadArgs.questions)
+
+  const context = typeof payload?.context === 'string' ? payload.context.trim() : ''
+  const preview = typeof payload?.preview === 'string' ? payload.preview.trim() : ''
+
+  return collectToolMatchValues(query, context, preview)
+}
+
+/**
+ * The batch-clarify counterpart of the `question` correlation key: a batch
+ * payload has no top-level `question`, only `questions[]`, so without this
+ * the request row and the tool.start row never match and the card mounts
+ * twice. The joined per-question texts identify the batch the same way one
+ * question text identifies a single prompt. The `\u0000` separator cannot
+ * appear in real question text, so a batch key can never collide with a
+ * single-question key.
+ */
+function batchClarifyMatchValue(questions: unknown): string {
+  if (!Array.isArray(questions)) {
+    return ''
+  }
+
+  const texts = questions
+    .map(entry => {
+      if (!entry || typeof entry !== 'object') {
+        return ''
+      }
+
+      const question = (entry as Record<string, unknown>).question
+
+      return typeof question === 'string' ? question.trim() : ''
+    })
+    .filter(Boolean)
+
+  return texts.length > 0 ? texts.join('\u0000') : ''
+}
+
+function toolPartMatchValues(part: ChatMessagePart): string[] {
+  if (part.type !== 'tool-call' || !part.args || typeof part.args !== 'object') {
+    return []
+  }
+
+  const args = part.args as Record<string, unknown>
+
+  const query =
+    firstStringField(args, ['search_term', 'query', 'question', 'server', 'command', 'code', 'path']) ||
+    batchClarifyMatchValue(args.questions)
+
+  const context = typeof args.context === 'string' ? args.context.trim() : ''
+  const preview = typeof args.preview === 'string' ? args.preview.trim() : ''
+
+  return collectToolMatchValues(query, context, preview)
+}
+
+function hasToolMatchOverlap(left: string[], right: string[]): boolean {
+  if (!left.length || !right.length) {
+    return false
+  }
+
+  const rightSet = new Set(right)
+
+  return left.some(value => rightSet.has(value))
+}
+
+function findToolPartIndex(
+  parts: ChatMessagePart[],
+  name: string,
+  stableId: string,
+  payload: GatewayEventPayload | undefined,
+  phase: 'running' | 'complete'
+): number {
+  const matchValues = toolPayloadMatchValues(payload)
+  const overlaps = (index: number) => hasToolMatchOverlap(matchValues, toolPartMatchValues(parts[index]))
+
+  if (stableId) {
+    const stableIndex = parts.findIndex(part => part.type === 'tool-call' && part.toolCallId === stableId)
+
+    if (stableIndex >= 0) {
+      return stableIndex
+    }
+
+    // Some live streams start without an id, then complete with one. Fall
+    // through to pending same-name/context matching so the completion updates
+    // the synthetic live row instead of appending a duplicate completed row.
+    if (phase === 'running' && !matchValues.length) {
+      return -1
+    }
+  }
+
+  const pendingIndices = parts
+    .map((part, index) => ({ part, index }))
+    .filter(({ part }) => part.type === 'tool-call' && part.toolName === name && part.result === undefined)
+    .map(({ index }) => index)
+
+  if (pendingIndices.length === 0) {
+    return -1
+  }
+
+  if (matchValues.length) {
+    const contextualIndex = pendingIndices.find(overlaps)
+
+    if (contextualIndex !== undefined) {
+      return contextualIndex
+    }
+  }
+
+  if (pendingIndices.length === 1) {
+    const [singlePendingIndex] = pendingIndices
+
+    if (phase === 'running' && matchValues.length && !overlaps(singlePendingIndex)) {
+      return stableId ? singlePendingIndex : -1
+    }
+
+    return singlePendingIndex
+  }
+
+  // Completion events without stable IDs frequently arrive after multiple
+  // same-name starts (parallel tool calls). Resolve them oldest-first so we
+  // don't collapse an entire burst into a single row.
+  if (phase === 'complete') {
+    return pendingIndices[0]
+  }
+
+  if (stableId) {
+    return pendingIndices[0]
+  }
+
+  // For progress/running events with no stable id, update the most-recent
+  // pending same-name tool instead of creating a phantom extra row.
+  return pendingIndices.at(-1) ?? -1
+}
+
+// Carry todo state across sparse progress payloads: if this todo event lacks
+// a `todos` field, fall back to whatever we previously stored on the part.
+function carryTodos(payload: GatewayEventPayload | undefined, ...prev: unknown[]): { todos: unknown } | undefined {
+  if (payload && Object.hasOwn(payload, 'todos')) {
+    const next = parseTodos(payload.todos)
+
+    return next === null ? undefined : { todos: next }
+  }
+
+  if (payload?.name !== 'todo') {
+    return undefined
+  }
+
+  for (const p of prev) {
+    const carried = parseTodos(recordFromUnknown(p)?.todos)
+
+    if (carried !== null) {
+      return { todos: carried }
+    }
+  }
+
+  return undefined
+}
+
+function toolArgs(payload: GatewayEventPayload | undefined, prevArgs?: unknown): Record<string, unknown> {
+  const prev = parseMaybeJsonObject(prevArgs)
+  const eventArgs = liveToolArgs(payload)
+
+  return {
+    ...prev,
+    ...eventArgs,
+    ...(payload?.context ? { context: payload.context } : {}),
+    ...(payload?.preview ? { preview: payload.preview } : {}),
+    ...carryTodos(payload, prevArgs)
+  }
+}
+
+function toolResult(
+  payload: GatewayEventPayload | undefined,
+  prevResult?: unknown,
+  prevArgs?: unknown
+): Record<string, unknown> {
+  const parsedResult = parseMaybeJsonObject(payload?.result)
+
+  return {
+    ...parsedResult,
+    ...(payload?.inline_diff ? { inline_diff: payload.inline_diff } : {}),
+    ...(payload?.summary ? { summary: payload.summary } : {}),
+    ...(payload?.message ? { message: payload.message } : {}),
+    ...(payload?.preview ? { preview: payload.preview } : {}),
+    ...(payload?.duration_s !== undefined ? { duration_s: payload.duration_s } : {}),
+    ...carryTodos(payload, prevResult, prevArgs),
+    ...(payload?.error ? { error: payload.error } : {})
+  }
+}
+
+function completeOpenStreamParts(parts: ChatMessagePart[], completedAt: number): ChatMessagePart[] {
+  return parts.map(part =>
+    (part.type === 'text' || part.type === 'reasoning') && part.completedAt === undefined
+      ? ({ ...part, completedAt } as ChatMessagePart)
+      : part
+  )
+}
+
+export function upsertToolPart(
+  parts: ChatMessagePart[],
+  payload: GatewayEventPayload | undefined,
+  phase: 'running' | 'complete',
+  occurredAt = Date.now() / 1000
+): ChatMessagePart[] {
+  const stableId = toolId(payload)
+  const name = payload?.name || 'tool'
+  // A completion can be the first tool event observed after reconnect, so it
+  // also constitutes a text/reasoning -> tool boundary when no start arrived.
+  const next = completeOpenStreamParts(parts, occurredAt)
+
+  const index = findToolPartIndex(next, name, stableId, payload, phase)
+
+  const prev = index >= 0 ? next[index] : null
+  const prevArgs = prev && 'args' in prev ? prev.args : undefined
+  const prevResult = prev && 'result' in prev ? prev.result : undefined
+  const args = toolArgs(payload, prevArgs)
+
+  const id =
+    stableId ||
+    (prev && 'toolCallId' in prev && typeof prev.toolCallId === 'string' ? prev.toolCallId : '') ||
+    nextLiveToolId(name)
+
+  const base = {
+    type: 'tool-call' as const,
+    toolCallId: id,
+    toolName: name,
+    args: args as never,
+    argsText: JSON.stringify(args),
+    timestamp: prev?.timestamp ?? occurredAt,
+    ...(phase === 'complete' && {
+      completedAt: occurredAt,
+      result: toolResult(payload, prevResult, prevArgs),
+      isError: Boolean(payload?.error)
+    })
+  } satisfies ChatMessagePart
+
+  if (index === -1) {
+    return [...next, base]
+  }
+
+  next[index] = { ...next[index], ...base }
+
+  return next
+}
+
+/**
+ * Turn-settle reconciliation: close every tool-call part that never received
+ * its completion event. A `tool.complete` lost to a degraded websocket
+ * (reconnect, profile swap, hidden window) leaves the part without a `result`,
+ * which renders as a permanently spinning tool row even though the turn itself
+ * completed. A settled session cannot have tools still running, so an open
+ * part at settle time is a lost event, not live work. Pending messages are
+ * left alone, and no-op calls return the input array unchanged.
+ */
+export function sealOpenToolParts(messages: ChatMessage[]): ChatMessage[] {
+  let changed = false
+
+  const next = messages.map(message => {
+    if (message.role !== 'assistant' || message.pending) {
+      return message
+    }
+
+    let partChanged = false
+
+    const parts = message.parts.map(part => {
+      if (part.type !== 'tool-call' || Object.hasOwn(part, 'result')) {
+        return part
+      }
+
+      partChanged = true
+
+      return { ...part, result: {} }
+    })
+
+    if (!partChanged) {
+      return message
+    }
+
+    changed = true
+
+    return { ...message, parts }
+  })
+
+  return changed ? next : messages
+}
+
+// ── Stored-tool conversion (hydration path) ────────────────────────────────
+
+export function textFromUnknown(value: unknown, depth = 0): string {
+  if (typeof value === 'string') {
+    return value
+  }
+
+  if (value === null || value === undefined) {
+    return ''
+  }
+
+  if (depth > 2) {
+    return ''
+  }
+
+  if (Array.isArray(value)) {
+    return value.map(item => textFromUnknown(item, depth + 1)).join('')
+  }
+
+  if (typeof value === 'object') {
+    const row = value as Record<string, unknown>
+    const textValue = row.text ?? row.output_text ?? row.content ?? row.message
+    const nestedText = textFromUnknown(textValue, depth + 1)
+
+    if (nestedText) {
+      return nestedText
+    }
+
+    try {
+      return JSON.stringify(value)
+    } catch {
+      return ''
+    }
+  }
+
+  return String(value)
+}
+
+function parseStoredToolResult(content: unknown): unknown {
+  if (content && typeof content === 'object') {
+    return content
+  }
+
+  const textContent = textFromUnknown(content)
+
+  if (!textContent.trim()) {
+    return ''
+  }
+
+  try {
+    return JSON.parse(textContent)
+  } catch {
+    return textContent
+  }
+}
+
+export function toolPartFromStoredCall(call: unknown, fallbackIndex: number, timestamp?: number): ChatMessagePart {
+  const row = recordFromUnknown(call) ?? {}
+  const fn = recordFromUnknown(row.function)
+  const id = String(row.id || row.tool_call_id || `stored-tool-${fallbackIndex}`)
+
+  const toolName = String(
+    row.name || row.tool_name || fn?.name || (recordFromUnknown(row.input)?.name as string | undefined) || 'tool'
+  )
+
+  const args = firstNonEmptyObject(fn?.arguments, row.arguments, row.args, row.input)
+
+  return {
+    type: 'tool-call',
+    toolCallId: id,
+    toolName,
+    args: args as never,
+    argsText: Object.keys(args).length ? JSON.stringify(args) : '',
+    ...(timestamp !== undefined ? { timestamp } : {})
+  }
+}
+
+export function applyStoredToolResult(messages: ChatMessage[], toolMessage: SessionMessage): boolean {
+  const toolCallId = toolMessage.tool_call_id || undefined
+  const toolName = toolMessage.tool_name || toolMessage.name || 'tool'
+  const content = toolMessage.content || toolMessage.text || toolMessage.context || toolMessage.name
+
+  for (let i = messages.length - 1; i >= 0; i -= 1) {
+    const message = messages[i]
+
+    if (message.role !== 'assistant') {
+      continue
+    }
+
+    const partIndex = message.parts.findIndex(
+      part =>
+        part.type === 'tool-call' &&
+        ((toolCallId && part.toolCallId === toolCallId) || (!toolCallId && part.toolName === toolName))
+    )
+
+    if (partIndex < 0) {
+      continue
+    }
+
+    const parts = [...message.parts]
+    const existing = parts[partIndex]
+    parts[partIndex] = {
+      ...existing,
+      completedAt: toolMessage.timestamp,
+      result: parseStoredToolResult(content),
+      isError: false
+    } as ChatMessagePart
+    messages[i] = { ...message, parts }
+
+    return true
+  }
+
+  return false
+}
+
+export function applyStoredToolResultToParts(
+  parts: ChatMessagePart[],
+  toolMessage: SessionMessage
+): ChatMessagePart[] | null {
+  const toolCallId = toolMessage.tool_call_id || undefined
+  const toolName = toolMessage.tool_name || toolMessage.name || 'tool'
+  const content = toolMessage.content || toolMessage.text || toolMessage.context || toolMessage.name
+
+  const partIndex = parts.findIndex(
+    part =>
+      part.type === 'tool-call' &&
+      ((toolCallId && part.toolCallId === toolCallId) || (!toolCallId && part.toolName === toolName))
+  )
+
+  if (partIndex < 0) {
+    return null
+  }
+
+  const next = [...parts]
+  const existing = next[partIndex]
+  next[partIndex] = {
+    ...existing,
+    completedAt: toolMessage.timestamp,
+    result: parseStoredToolResult(content),
+    isError: false
+  } as ChatMessagePart
+
+  return next
+}
+
+export function storedToolMessagePart(toolMessage: SessionMessage, fallbackIndex: number): ChatMessagePart {
+  const name = toolMessage.tool_name || toolMessage.name || 'tool'
+  const context = textFromUnknown(toolMessage.context || toolMessage.text || toolMessage.content || '')
+  // Prefer the full arguments when the gateway projection carries them:
+  // `context` is an 80-char display preview, and the expanded tool row
+  // rebuilds the real command from args. Keep `context` alongside as the
+  // title-side placeholder.
+  const storedArgs = parseMaybeJsonObject(toolMessage.args)
+  const args = { ...storedArgs, ...(context ? { context } : {}) }
+
+  return {
+    type: 'tool-call',
+    toolCallId: toolMessage.tool_call_id || `stored-tool-message-${fallbackIndex}`,
+    toolName: name,
+    args: args as never,
+    argsText: Object.keys(args).length ? JSON.stringify(args) : '',
+    timestamp: toolMessage.timestamp,
+    completedAt: toolMessage.timestamp,
+    result: context ? { context } : {},
+    isError: false
+  }
+}
+
+export function withUniqueToolCallIds(messages: ChatMessage[]): ChatMessage[] {
+  const seen = new Set<string>()
+
+  return messages.map(message => {
+    let changed = false
+
+    const parts = message.parts.map((part, index) => {
+      if (part.type !== 'tool-call') {
+        return part
+      }
+
+      const id = part.toolCallId || `${message.id}-tool-${index}`
+
+      if (!seen.has(id)) {
+        seen.add(id)
+
+        if (part.toolCallId) {
+          return part
+        }
+
+        changed = true
+
+        return { ...part, toolCallId: id } as ChatMessagePart
+      }
+
+      changed = true
+      const uniqueId = `${id}-${message.id}-${index}`
+      seen.add(uniqueId)
+
+      return { ...part, toolCallId: uniqueId } as ChatMessagePart
+    })
+
+    return changed ? { ...message, parts } : message
+  })
+}
diff --git a/apps/desktop/src/lib/chat-messages/types.ts b/apps/desktop/src/lib/chat-messages/types.ts
new file mode 100644
index 0000000000..2974b8d56a
--- /dev/null
+++ b/apps/desktop/src/lib/chat-messages/types.ts
@@ -0,0 +1,158 @@
+import type { ThreadMessageLike } from '@assistant-ui/react'
+import { type BillingBlock } from '@hermes/shared'
+
+import type { MessageReaction, SessionMessage, UsageStats } from '@/types/hermes'
+
+export interface TimelinePartMetadata {
+  /** Unix seconds when this visible activity segment began. Fractional values
+   * preserve the millisecond precision available on live gateway events. */
+  timestamp?: number
+  /** Unix seconds when this segment stopped or handed off to the next one. */
+  completedAt?: number
+}
+
+export type ChatMessagePart = Exclude<ThreadMessageLike['content'], string>[number] & TimelinePartMetadata
+
+export type ChatMessage = {
+  id: string
+  role: SessionMessage['role']
+  parts: ChatMessagePart[]
+  timestamp?: number
+  completedAt?: number
+  pending?: boolean
+  error?: string
+  branchGroupId?: string
+  hidden?: boolean
+  /** Sealed mid-turn commentary (`message.interim`) — rendered without the
+   *  action footer so only the turn's final reply carries copy/refresh, and
+   *  the live view matches rehydration (which merges the turn into one bubble). */
+  interim?: boolean
+  /** Whole-turn wall-clock seconds (message.start → message.complete),
+   *  stamped by the desktop when it watched the turn run. Absent for
+   *  messages hydrated from history — the backend doesn't persist it. */
+  durationS?: number
+  /** Composer attachment ref strings (`@file:...`, `@image:...`) sent with this user message. */
+  attachmentRefs?: string[]
+  /** Durable backend `messages.id`. Absent until the row is persisted. */
+  rowId?: number
+  /** Emoji reactions on this message — one per author (see MessageReaction). */
+  reactions?: MessageReaction[]
+}
+
+export type GatewayEventPayload = {
+  /** Unix seconds supplied by tests/newer gateways; the desktop falls back to
+   * its local receipt clock when older gateways omit it. */
+  timestamp?: number
+  text?: string
+  rendered?: string
+  status?: string
+  message?: string
+  id?: string
+  name?: string
+  tool_id?: string
+  tool_call_id?: string
+  args?: unknown
+  arguments?: unknown
+  context?: string
+  input?: unknown
+  preview?: string
+  result?: unknown
+  summary?: string
+  error?: string | boolean
+  inline_diff?: string
+  duration_s?: number
+  todos?: unknown
+  model?: string
+  provider?: string
+  reasoning_effort?: string
+  service_tier?: string
+  fast?: boolean
+  approval_mode?: string
+  yolo?: boolean
+  running?: boolean
+  turn_started_at?: number | null
+  cwd?: string
+  branch?: string
+  terminal_backend?: string
+  credential_warning?: string
+  install_warning?: string
+  personality?: string
+  usage?: Partial<UsageStats>
+  // agent.terminal.output — live chunk for a read-only agent terminal tab
+  process_id?: string
+  chunk?: string
+  // clarify.request
+  request_id?: string
+  question?: string
+  choices?: string[] | null
+  multi_select?: boolean
+  // clarify.request batch form: questions replaces question/choices, and
+  // answers (qid → locked answer) rides along on reconnect replay only.
+  questions?: unknown
+  answers?: Record<string, unknown>
+  // mcp.setup.request (setup_mcp tool — inline MCP consent card)
+  server?: string
+  action?: string
+  reason?: string
+  // approval.request (dangerous command / execute_code) — session-keyed
+  command?: string
+  description?: string
+  // False when a tirith content-security warning forbids a permanent allow.
+  allow_permanent?: boolean
+  smart_denied?: boolean
+  // secret.request (skill credential capture)
+  env_var?: string
+  prompt?: string
+  // terminal.read.request / preview.read.request (GUI agent reading the
+  // in-app terminal pane or the browser/preview pane)
+  start?: number
+  count?: number
+  // status.update (kind=process → background process completion/watch-match)
+  kind?: string
+  // pane.reveal (agent focusing a desktop pane via the focus_pane tool)
+  pane?: string
+  // layout.apply (agent applying a layout preset via the apply_layout tool)
+  preset?: string
+  // tour.request (tour tool — agent-guided driver.js walkthrough). `action`
+  // and `steps` name the tour verb and step list; `surface` picks the app's
+  // own DOM vs the preview pane's guest page.
+  surface?: string
+  selector?: string
+  side?: string
+  steps?: unknown
+  step_index?: number
+  // message.reaction (agent reacting via the react_to_message tool) — the
+  // durable messages.id, that row's full reaction list after the write, and
+  // the row's role so a live (not-yet-round-tripped) message can be matched.
+  row_id?: number
+  reactions?: MessageReaction[]
+  role?: string
+  // session.title (live auto-title push) — stored session id + generated title
+  session_id?: string
+  title?: string
+  // session.info — the stored (durable) session id for this runtime session.
+  // Lets the desktop app map runtime→stored for background sessions it hasn't
+  // opened, so the sidebar working indicator updates without opening the chat.
+  stored_session_id?: string
+  // moa.reference / moa.aggregating (Mixture of Agents per-model relay)
+  label?: string
+  index?: number
+  aggregator?: string
+  // moa.progress / moa.phase (Mixture of Agents fan-out progress relay)
+  refs_done?: number
+  refs_total?: number
+  phase?: string
+  // message.complete — signals the final text was already previewed via
+  // interim_assistant_callback, so the UI can settle instead of duplicating.
+  response_previewed?: boolean
+  // message.complete with status "error" — `text` is streamed partial output
+  // (keep it visible), not the error string.
+  partial?: boolean
+  // message.complete with status "error" — the failed turn was retained
+  // backend-side and will replay through session.resume's inflight payload.
+  recoverable?: boolean
+  // Structured billing wall forwarded on message.complete when a turn fails
+  // with FailoverReason.billing (shape mirrors @hermes/shared BillingBlock).
+  billing?: BillingBlock
+  failure_reason?: string
+}

From f6e63237d42935ec6e5e6ad0c3c224a017cf1625 Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 19 Aug 2026 03:34:50 -0500
Subject: [PATCH 12/48] refactor(desktop): extract IPC clusters from
 electron/main.ts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

52 handlers move into five registrars — git, pet overlay, hud, fs and
terminal. Each takes injected deps (window handles, binary resolvers,
path hardening) following the existing electron/ module pattern rather
than closing over main.ts locals, and terminal-ipc returns its dispose
helpers so SSH teardown and app shutdown keep working.
---
 apps/desktop/electron/fs-ipc.ts               | 197 ++++
 apps/desktop/electron/git-ipc.ts              | 120 +++
 apps/desktop/electron/hardening.ts            |  28 +-
 apps/desktop/electron/hud-ipc.ts              | 128 +++
 apps/desktop/electron/main.ts                 | 874 +-----------------
 apps/desktop/electron/pet-overlay-ipc.ts      | 151 +++
 apps/desktop/electron/remote-lifecycle.ts     |  33 +-
 apps/desktop/electron/ssh-connection.ts       |  12 +
 apps/desktop/electron/terminal-ipc.ts         | 377 ++++++++
 .../electron/windows-remote-lifecycle.ts      |  18 +-
 apps/desktop/tsconfig.electron.json           |   2 +-
 11 files changed, 1057 insertions(+), 883 deletions(-)
 create mode 100644 apps/desktop/electron/fs-ipc.ts
 create mode 100644 apps/desktop/electron/git-ipc.ts
 create mode 100644 apps/desktop/electron/hud-ipc.ts
 create mode 100644 apps/desktop/electron/pet-overlay-ipc.ts
 create mode 100644 apps/desktop/electron/terminal-ipc.ts

diff --git a/apps/desktop/electron/fs-ipc.ts b/apps/desktop/electron/fs-ipc.ts
new file mode 100644
index 0000000000..ff25db2013
--- /dev/null
+++ b/apps/desktop/electron/fs-ipc.ts
@@ -0,0 +1,197 @@
+// IPC surface for local filesystem operations the renderer's project/file
+// surfaces use: directory reads, reveal/open in the OS file manager, plugin
+// roots + git installs, rename/write/trash. Extracted from main.ts; path
+// hardening, HERMES_HOME resolution, and the git binary stay injected.
+import fs from 'node:fs'
+import path from 'node:path'
+
+import { ipcMain, shell } from 'electron'
+
+import { installDesktopPluginFromGit, probePluginRepo } from './desktop-plugin-install'
+import { readDirForIpc } from './fs-read-dir'
+import { gitRootForIpc } from './git-root'
+
+export interface FsIpcDeps {
+  hermesHome: string
+  readActiveDesktopProfile: () => null | string
+  expandUserPath: (value: string) => string
+  resolveRequestedPathForIpc: (value: string, options: { purpose: string }) => string
+  directoryExists: (value: string) => boolean
+  resolveGitBinary: () => string
+}
+
+export function registerFsIpc({
+  hermesHome,
+  readActiveDesktopProfile,
+  expandUserPath,
+  resolveRequestedPathForIpc,
+  directoryExists,
+  resolveGitBinary
+}: FsIpcDeps) {
+  ipcMain.handle('hermes:fs:readDir', async (_event, dirPath) => readDirForIpc(dirPath))
+
+  ipcMain.handle('hermes:fs:gitRoot', async (_event, startPath) => gitRootForIpc(startPath))
+
+  // Reveal a path in the OS file manager (Finder / Explorer / Files).
+  ipcMain.handle('hermes:fs:reveal', async (_event, targetPath) => {
+    const target = String(targetPath || '').trim()
+
+    if (!target) {
+      return false
+    }
+
+    try {
+      shell.showItemInFolder(target)
+
+      return true
+    } catch {
+      return false
+    }
+  })
+
+  // Open a DIRECTORY in the OS file manager, creating it first if needed. Unlike
+  // `reveal` (which selects an existing item and silently no-ops on a missing
+  // path — the "Open plugins folder" Windows bug), this is for the plugins door,
+  // which often doesn't exist on first use. `shell.openPath` returns '' on
+  // success or an error string; both mkdir + openPath failures are surfaced.
+  ipcMain.handle('hermes:fs:openDir', async (_event, dirPath) => {
+    const dir = String(dirPath || '').trim()
+
+    if (!dir) {
+      return { ok: false, error: 'no path' }
+    }
+
+    try {
+      await fs.promises.mkdir(dir, { recursive: true })
+      const error = await shell.openPath(path.normalize(dir))
+
+      return error ? { ok: false, error } : { ok: true }
+    } catch (error) {
+      return { ok: false, error: error instanceof Error ? error.message : String(error) }
+    }
+  })
+
+  // The LOCAL Desktop runtime-plugin root: `<HERMES_HOME>/desktop-plugins`,
+  // resolved from the main-process HERMES_HOME (see resolveHermesHome) — NOT from
+  // the connected backend. A remote backend reports its own `hermes_home` over
+  // the gateway, which is a path on the REMOTE box; deriving the plugin dir from
+  // it yields `undefined/desktop-plugins` (or a non-existent remote path) and the
+  // on-disk plugin door silently breaks (#66899). Electron owns this resolution
+  // so it stays valid in every connection mode. Created on demand, like openDir.
+  async function localPluginsRoot(dirName: string): Promise<string> {
+    // Profile-aware: a named Desktop profile gets its own plugin root under
+    // profiles/<name>/, matching the profile-scoped hermes_home the backend
+    // reported before this resolver existed. 'default'/unset pins the global root.
+    const profile = readActiveDesktopProfile()
+    const base = profile && profile !== 'default' ? path.join(hermesHome, 'profiles', profile) : hermesHome
+    const dir = path.join(base, dirName)
+
+    try {
+      await fs.promises.mkdir(dir, { recursive: true })
+    } catch {
+      // Best-effort create; return the path regardless so the reveal action can
+      // still surface a real openPath error and the scanner can retry later.
+    }
+
+    return dir
+  }
+
+  ipcMain.handle('hermes:fs:desktopPluginsRoot', async () => localPluginsRoot('desktop-plugins'))
+
+  // The LOCAL agent-plugin root (`<HERMES_HOME>/plugins`), same Electron-local
+  // resolution as above. This is the desktop half of a UNIFIED plugin package:
+  // an agent plugin may ship `desktop/plugin.js` alongside its Python code (the
+  // same shape as `dashboard/manifest.json`), and the renderer's disk door scans
+  // this root for it — one installable folder serving both SDKs.
+  ipcMain.handle('hermes:fs:agentPluginsRoot', async () => localPluginsRoot('plugins'))
+
+  ipcMain.handle('hermes:plugin:probe', async (_event, payload) => {
+    const identifier = String(payload?.identifier || payload?.repo || '').trim()
+
+    if (!identifier) {
+      return { ok: false, error: 'identifier is required', agent: false, desktop: false, warnings: [] }
+    }
+
+    return probePluginRepo(resolveGitBinary(), identifier)
+  })
+
+  ipcMain.handle('hermes:plugin:installDesktop', async (_event, payload) => {
+    const identifier = String(payload?.identifier || payload?.repo || '').trim()
+
+    if (!identifier) {
+      return { ok: false, error: 'identifier is required' }
+    }
+
+    const desktopPluginsRoot = await localPluginsRoot('desktop-plugins')
+
+    return installDesktopPluginFromGit(resolveGitBinary(), identifier, desktopPluginsRoot, Boolean(payload?.force))
+  })
+
+  // Rename a file/folder in place. The renderer passes the existing path + a new
+  // base name; the destination is resolved in the SAME parent dir so a rename can
+  // never move the item elsewhere or traverse out. Rejects on a name collision.
+  ipcMain.handle('hermes:fs:rename', async (_event, targetPath, newName) => {
+    const src = String(targetPath || '').trim()
+    const name = String(newName || '').trim()
+
+    if (!src || !name || name === '.' || name === '..' || name.includes('/') || name.includes('\\')) {
+      throw new Error('Invalid rename')
+    }
+
+    const dst = path.join(path.dirname(src), name)
+
+    if (dst === src) {
+      return { path: dst }
+    }
+
+    if (fs.existsSync(dst)) {
+      throw new Error(`"${name}" already exists`)
+    }
+
+    await fs.promises.rename(src, dst)
+
+    return { path: dst }
+  })
+
+  // Write a small UTF-8 text file (e.g. a project's IDEA.md at creation). The path
+  // is hardened (resolveRequestedPathForIpc) and the parent must already exist —
+  // this never creates directory trees or escapes the allowed roots, and content
+  // is size-capped so it can't be abused as a bulk-write primitive.
+  ipcMain.handle('hermes:fs:writeText', async (_event, filePath, content) => {
+    const raw = String(filePath || '').trim()
+
+    if (!raw) {
+      throw new Error('Invalid path')
+    }
+
+    const text = String(content ?? '')
+
+    if (text.length > 1_000_000) {
+      throw new Error('Content too large')
+    }
+
+    const resolved = resolveRequestedPathForIpc(expandUserPath(raw), { purpose: 'Write text file' })
+
+    if (!directoryExists(path.dirname(resolved))) {
+      throw new Error('Parent directory does not exist')
+    }
+
+    await fs.promises.writeFile(resolved, text, 'utf8')
+
+    return { path: resolved }
+  })
+
+  // Move a file/folder to the OS trash (recoverable) — the VS Code "Delete"
+  // default. `shell.trashItem` routes to Finder/Explorer/Files trash per platform.
+  ipcMain.handle('hermes:fs:trash', async (_event, targetPath) => {
+    const target = String(targetPath || '').trim()
+
+    if (!target) {
+      throw new Error('Invalid delete')
+    }
+
+    await shell.trashItem(target)
+
+    return true
+  })
+}
diff --git a/apps/desktop/electron/git-ipc.ts b/apps/desktop/electron/git-ipc.ts
new file mode 100644
index 0000000000..105307d03e
--- /dev/null
+++ b/apps/desktop/electron/git-ipc.ts
@@ -0,0 +1,120 @@
+// IPC surface for git-driven features: worktree management ("Start work"),
+// the composer coding rail's repo status, the Codex-style review pane, and
+// repo-first project discovery. Extracted from main.ts; the git/gh binary
+// resolvers stay injected because main.ts also uses them for self-update and
+// plugin installs.
+import { ipcMain } from 'electron'
+
+import { scanGitRepos } from './git-repo-scan'
+import {
+  fileDiffVsHead,
+  repoStatus,
+  reviewCommit,
+  reviewCommitContext,
+  reviewCreatePr,
+  reviewDiff,
+  reviewFetchPrComment,
+  reviewList,
+  reviewPrList,
+  reviewPush,
+  reviewRevert,
+  reviewRevParse,
+  reviewShipInfo,
+  reviewStage,
+  reviewUnstage
+} from './git-review-ops'
+import {
+  addWorktree,
+  listBaseBranches,
+  listBranches,
+  listWorktrees,
+  removeWorktree,
+  switchBranch
+} from './git-worktree-ops'
+
+export interface GitIpcDeps {
+  resolveGitBinary: () => string
+  resolveGhBinary: () => string
+}
+
+export function registerGitIpc({ resolveGitBinary, resolveGhBinary }: GitIpcDeps) {
+  // Git-driven worktree management ("Start work" flow). Errors surface to the
+  // renderer as rejected promises so it can toast a friendly message.
+  ipcMain.handle('hermes:git:worktreeList', async (_event, repoPath) => listWorktrees(repoPath, resolveGitBinary()))
+
+  ipcMain.handle('hermes:git:worktreeAdd', async (_event, repoPath, options) =>
+    addWorktree(repoPath, options || {}, resolveGitBinary())
+  )
+
+  ipcMain.handle('hermes:git:worktreeRemove', async (_event, repoPath, worktreePath, options) =>
+    removeWorktree(repoPath, worktreePath, options || {}, resolveGitBinary())
+  )
+
+  ipcMain.handle('hermes:git:branchSwitch', async (_event, repoPath, branch) =>
+    switchBranch(repoPath, branch, resolveGitBinary())
+  )
+
+  ipcMain.handle('hermes:git:branchList', async (_event, repoPath) => listBranches(repoPath, resolveGitBinary()))
+
+  ipcMain.handle('hermes:git:baseBranchList', async (_event, repoPath) =>
+    listBaseBranches(repoPath, resolveGitBinary())
+  )
+
+  // Compact repo status (branch, ahead/behind, change counts + files) for the
+  // composer coding rail. Returns null on a non-repo / remote backend so the rail
+  // hides cleanly rather than erroring.
+  ipcMain.handle('hermes:git:repoStatus', async (_event, repoPath) => repoStatus(repoPath, resolveGitBinary()))
+
+  // Codex-style review pane: list changed files for a scope, fetch one file's
+  // unified diff, and stage / unstage / revert. Reads return empty on failure;
+  // mutations reject so the renderer can toast.
+  ipcMain.handle('hermes:git:review:list', async (_event, repoPath, scope, baseRef) =>
+    reviewList(repoPath, scope, baseRef, resolveGitBinary())
+  )
+  ipcMain.handle('hermes:git:review:diff', async (_event, repoPath, filePath, scope, baseRef, staged) =>
+    reviewDiff(repoPath, filePath, scope, baseRef, staged, resolveGitBinary())
+  )
+  // Working-tree-vs-HEAD diff for one file (the preview's "show the diff" view).
+  ipcMain.handle('hermes:git:fileDiff', async (_event, repoPath, filePath) =>
+    fileDiffVsHead(repoPath, filePath, resolveGitBinary())
+  )
+  ipcMain.handle('hermes:git:review:stage', async (_event, repoPath, filePath) =>
+    reviewStage(repoPath, filePath ?? null, resolveGitBinary())
+  )
+  ipcMain.handle('hermes:git:review:unstage', async (_event, repoPath, filePath) =>
+    reviewUnstage(repoPath, filePath ?? null, resolveGitBinary())
+  )
+  ipcMain.handle('hermes:git:review:revert', async (_event, repoPath, filePath) =>
+    reviewRevert(repoPath, filePath ?? null, resolveGitBinary())
+  )
+  ipcMain.handle('hermes:git:review:revParse', async (_event, repoPath, ref) =>
+    reviewRevParse(repoPath, ref, resolveGitBinary())
+  )
+  ipcMain.handle('hermes:git:review:commit', async (_event, repoPath, message, push) =>
+    reviewCommit(repoPath, message, Boolean(push), resolveGitBinary())
+  )
+  ipcMain.handle('hermes:git:review:commitContext', async (_event, repoPath) =>
+    reviewCommitContext(repoPath, resolveGitBinary())
+  )
+  ipcMain.handle('hermes:git:review:push', async (_event, repoPath) => reviewPush(repoPath, resolveGitBinary()))
+  ipcMain.handle('hermes:git:review:shipInfo', async (_event, repoPath) => reviewShipInfo(repoPath, resolveGhBinary()))
+  ipcMain.handle('hermes:git:review:prList', async (_event, repoPath, branches, numbers) =>
+    reviewPrList(repoPath, resolveGhBinary(), branches, numbers)
+  )
+  ipcMain.handle('hermes:git:review:fetchPrComment', async (_event, repoPath, url) =>
+    reviewFetchPrComment(repoPath, resolveGhBinary(), url)
+  )
+  ipcMain.handle('hermes:git:review:createPr', async (_event, repoPath) =>
+    reviewCreatePr(repoPath, resolveGitBinary(), resolveGhBinary())
+  )
+
+  // Repo-first project discovery: scan bounded roots for git repos (pure fs walk,
+  // no native addon). Never throws to the renderer — failures yield an empty list.
+  ipcMain.handle('hermes:git:scanRepos', async (_event, roots, options) => {
+    try {
+      return await scanGitRepos(roots || [], options || {})
+    } catch {
+      return []
+    }
+  })
+}
diff --git a/apps/desktop/electron/hardening.ts b/apps/desktop/electron/hardening.ts
index b885dda1af..f8c77f3186 100644
--- a/apps/desktop/electron/hardening.ts
+++ b/apps/desktop/electron/hardening.ts
@@ -3,31 +3,23 @@ import os from 'node:os'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+// Relative, not `@hermes/shared`: the electron bundle is built by esbuild with
+// no tsconfig path resolution (see scripts/bundle-electron-main.mjs), so a bare
+// specifier would typecheck and then fail to bundle.
+import {
+  clampDataUrlReadMaxMb,
+  DATA_URL_READ_DEFAULT_MAX_MB,
+  DATA_URL_READ_MAX_MAX_MB,
+  DATA_URL_READ_MIN_MAX_MB
+} from '../../shared/src/data-url-read-max'
+
 const DEFAULT_FETCH_TIMEOUT_MS = 15_000
-// Default / floor / ceiling for Desktop's data-URL file load (composer attach,
-// image preview, etc.). The whole file is base64-buffered in main, so this is
-// a memory guard — not a model limit. Settings → Chat takes a free-form MB
-// value; 16 MB ships as default. The ceiling is only a typo guard (very large
-// values can OOM / crash the app).
-const DATA_URL_READ_DEFAULT_MAX_MB = 16
-const DATA_URL_READ_MIN_MAX_MB = 1
-const DATA_URL_READ_MAX_MAX_MB = 4096
 // Remote file.attach sends one base64 JSON-RPC frame. Cap the dedicated attach
 // reader so the payload still fits uvicorn's raised ws_max_size (384 MiB)
 // after base64 + framing. Preview stays on the Settings-configurable path.
 const ATTACHMENT_UPLOAD_DEFAULT_MAX_BYTES = 256 * 1024 * 1024
 const TEXT_PREVIEW_SOURCE_MAX_BYTES = 64 * 1024 * 1024
 
-function clampDataUrlReadMaxMb(value) {
-  const parsed = Number(value)
-
-  if (!Number.isFinite(parsed)) {
-    return DATA_URL_READ_DEFAULT_MAX_MB
-  }
-
-  return Math.min(DATA_URL_READ_MAX_MAX_MB, Math.max(DATA_URL_READ_MIN_MAX_MB, Math.round(parsed)))
-}
-
 function dataUrlReadMaxBytesFromMb(maxMb) {
   return clampDataUrlReadMaxMb(maxMb) * 1024 * 1024
 }
diff --git a/apps/desktop/electron/hud-ipc.ts b/apps/desktop/electron/hud-ipc.ts
new file mode 100644
index 0000000000..8a8b7cf000
--- /dev/null
+++ b/apps/desktop/electron/hud-ipc.ts
@@ -0,0 +1,128 @@
+// IPC surface for HUD mode (the chrome-free floating chat band). Extracted
+// from main.ts; the HUD window handle and session-id latch stay injected
+// because main.ts owns the window lifecycle and the close broadcast reads the
+// latch when handing the session back to the app window.
+import { type BrowserWindow, ipcMain } from 'electron'
+
+export interface HudIpcDeps {
+  isMac: boolean
+  getHudWindow: () => BrowserWindow | null
+  openHudWindow: (sessionId: null | string, profile: null | string) => void
+  closeHudWindow: () => void
+  setHudSessionId: (sessionId: null | string) => void
+}
+
+export function registerHudIpc({ isMac, getHudWindow, openHudWindow, closeHudWindow, setHudSessionId }: HudIpcDeps) {
+  ipcMain.handle('hermes:hud:open', async (_event, request) => {
+    openHudWindow(
+      typeof request?.sessionId === 'string' ? request.sessionId : null,
+      typeof request?.profile === 'string' ? request.profile : null
+    )
+
+    return { ok: true }
+  })
+
+  // Real frosted glass behind the band — the thing CSS backdrop-filter cannot do,
+  // because Chromium composites a transparent window's page against nothing and
+  // the desktop is not in its backdrop root. Vibrancy IS the window's content
+  // view, so it frosts the whole rectangle; the HUD's layout leaves no dead
+  // margins for that reason, and the renderer only turns it on while the band is
+  // showing (idle HUD mode must be the bar and nothing else).
+  ipcMain.handle('hermes:hud:vibrancy', (_event, on) => {
+    const hudWindow = getHudWindow()
+
+    if (hudWindow && !hudWindow.isDestroyed() && isMac) {
+      hudWindow.setVibrancy(on ? 'hud' : null)
+    }
+
+    return { ok: true }
+  })
+
+  // Let clicks fall through the HUD wherever it isn't really there. An
+  // always-on-top window eats every click inside its rectangle, and most of that
+  // rectangle is a faded-out band over whatever the user is actually working in.
+  // `forward` keeps mousemove flowing so the renderer can re-arm when the cursor
+  // reaches the bar.
+  ipcMain.on('hermes:hud:ignore-mouse', (_event, ignore) => {
+    const hudWindow = getHudWindow()
+
+    if (hudWindow && !hudWindow.isDestroyed()) {
+      hudWindow.setIgnoreMouseEvents(Boolean(ignore), { forward: true })
+    }
+  })
+
+  ipcMain.on('hermes:hud:move-by', (event, delta) => {
+    const hudWindow = getHudWindow()
+
+    if (!hudWindow || hudWindow.isDestroyed() || event.sender !== hudWindow.webContents) {
+      return
+    }
+
+    const dx = Number(delta?.x)
+    const dy = Number(delta?.y)
+    const width = Number(delta?.width)
+    const height = Number(delta?.height)
+
+    if (!Number.isFinite(dx) || !Number.isFinite(dy) || !Number.isFinite(width) || !Number.isFinite(height)) {
+      return
+    }
+
+    const [x, y] = hudWindow.getPosition()
+
+    // setBounds — NOT setPosition: on Windows, a transparent frameless window
+    // silently grows ~1px per setPosition call (worse at >100% DPI). The renderer
+    // snapshots outerWidth/outerHeight when the composer drag arms and re-pins
+    // to that size on every moveBy (same pattern as the pet overlay drag).
+    hudWindow.setBounds({
+      x: Math.round(x + dx),
+      y: Math.round(y + dy),
+      width: Math.round(width),
+      height: Math.round(height)
+    })
+  })
+
+  // Resize from the HUD's corner handle. The window is created non-resizable
+  // (see spawnHudWindow — a transparent frameless window must not expose a
+  // system resize hot-zone, or dragging grows it), which on Windows/Linux also
+  // blocks programmatic setBounds sizing — so briefly flip resizable on while
+  // the size actually changes, exactly like the pet overlay's wheel-scale does.
+  ipcMain.on('hermes:hud:set-bounds', (event, bounds) => {
+    const hudWindow = getHudWindow()
+
+    if (!hudWindow || hudWindow.isDestroyed() || event.sender !== hudWindow.webContents || !bounds) {
+      return
+    }
+
+    const win = hudWindow
+    const width = Math.max(380, Math.round(Number(bounds.width)))
+    const height = Math.max(160, Math.round(Number(bounds.height)))
+    const [curW, curH] = win.getSize()
+    const resizing = width !== curW || height !== curH
+
+    if (resizing && !win.isResizable()) {
+      win.setResizable(true)
+    }
+
+    win.setBounds({ x: Math.round(Number(bounds.x)), y: Math.round(Number(bounds.y)), width, height })
+
+    if (resizing) {
+      win.setResizable(false)
+    }
+  })
+
+  // The HUD renderer reporting which session it is on, so the close broadcast
+  // can hand it back to the app window (see hudSessionId).
+  ipcMain.on('hermes:hud:session', (event, sessionId) => {
+    const hudWindow = getHudWindow()
+
+    if (hudWindow && !hudWindow.isDestroyed() && event.sender === hudWindow.webContents) {
+      setHudSessionId(typeof sessionId === 'string' && sessionId ? sessionId : null)
+    }
+  })
+
+  ipcMain.handle('hermes:hud:close', async () => {
+    closeHudWindow()
+
+    return { ok: true }
+  })
+}
diff --git a/apps/desktop/electron/main.ts b/apps/desktop/electron/main.ts
index 8e35bbefd9..394abbbf87 100644
--- a/apps/desktop/electron/main.ts
+++ b/apps/desktop/electron/main.ts
@@ -29,7 +29,6 @@ import {
   shell,
   systemPreferences
 } from 'electron'
-import nodePty from 'node-pty'
 
 import { classifyActiveRuntime } from './active-runtime-state'
 import { stopBackendChild as stopBackendChildImpl, stopBackendTreesForUpdate } from './backend-child'
@@ -60,7 +59,7 @@ import {
 import { decideBootstrapRepair } from './bootstrap-repair-guard'
 import { runBootstrap } from './bootstrap-runner'
 import { detectBundleSkew } from './bundle-skew'
-import { applyConnectionChange, resolveTerminalConnection } from './connection-apply'
+import { applyConnectionChange } from './connection-apply'
 import {
   apiRequestRegistryConnectionId,
   authModeFromStatus,
@@ -120,7 +119,6 @@ import { describeCrashReason, installCrashForensics } from './crash-forensics'
 import { adoptServedDashboardToken } from './dashboard-token'
 import { loadOrCreateInstallationId, sshOwnershipId } from './desktop-installation'
 import { formatDesktopLogLine } from './desktop-log-line'
-import { installDesktopPluginFromGit, probePluginRepo } from './desktop-plugin-install'
 import { resolveDesktopRemoteRoute } from './desktop-remote-route'
 import {
   buildPosixCleanupScript,
@@ -149,7 +147,7 @@ import {
   stopFind
 } from './find-in-page'
 import { createFirstRunSetupGate } from './first-run-setup-gate'
-import { readDirForIpc } from './fs-read-dir'
+import { registerFsIpc } from './fs-ipc'
 import {
   filenameFromContentDisposition,
   gatewayFilePath,
@@ -158,33 +156,7 @@ import {
   pumpStreamToFile
 } from './gateway-file-download'
 import { probeGatewayWebSocket } from './gateway-ws-probe'
-import { scanGitRepos } from './git-repo-scan'
-import {
-  fileDiffVsHead,
-  repoStatus,
-  reviewCommit,
-  reviewCommitContext,
-  reviewCreatePr,
-  reviewDiff,
-  reviewFetchPrComment,
-  reviewList,
-  reviewPrList,
-  reviewPush,
-  reviewRevert,
-  reviewRevParse,
-  reviewShipInfo,
-  reviewStage,
-  reviewUnstage
-} from './git-review-ops'
-import { gitRootForIpc } from './git-root'
-import {
-  addWorktree,
-  listBaseBranches,
-  listBranches,
-  listWorktrees,
-  removeWorktree,
-  switchBranch
-} from './git-worktree-ops'
+import { registerGitIpc } from './git-ipc'
 import { clearStaleGitLocks } from './gitlock'
 import { readAndConsumeHandoffResult } from './handoff-result'
 import {
@@ -206,6 +178,7 @@ import {
   writeSecretFileAtomic
 } from './hardening'
 import { cursorPointInWindow } from './hud-cursor'
+import { registerHudIpc } from './hud-ipc'
 import { snapHudBounds } from './hud-snap'
 import { createHudSnapShortcut } from './hud-snap-shortcut'
 import { buildHudWindowUrl } from './hud-url'
@@ -234,6 +207,7 @@ import {
   electronProcessStartMarker,
   parentWatchdogEnv
 } from './parent-process-identity'
+import { registerPetOverlayIpc } from './pet-overlay-ipc'
 import {
   buildRegistryProfileRoutes,
   localRouteFallbackProfiles,
@@ -289,17 +263,11 @@ import {
   SESSION_WINDOW_MIN_WIDTH
 } from './session-windows'
 import { ensureLoginShellPath } from './shell-path'
-import { ensureSpawnHelperExecutable } from './spawn-helper-perms'
 import { createBootstrapCoordinator, sshConfigFingerprint } from './ssh-bootstrap-coordinator'
 import { collectSshConfigHosts, parseSshGOutput } from './ssh-config'
-import {
-  buildInteractiveSshArgs,
-  createSshProbeConnection,
-  pickLocalPort,
-  redactSecrets,
-  SshConnection
-} from './ssh-connection'
+import { createSshProbeConnection, pickLocalPort, redactSecrets, SshConnection } from './ssh-connection'
 import { createStreamThrottle } from './stream-throttle'
+import { registerTerminalIpc } from './terminal-ipc'
 import { nativeOverlayWidth as computeNativeOverlayWidth, macTitleBarOverlayHeight } from './titlebar-overlay-width'
 import {
   glassActive,
@@ -355,12 +323,7 @@ import {
   getVenvSitePackagesEntries,
   resolveVenvHermesCommand
 } from './windows-hermes-path'
-import {
-  buildWindowsInteractiveCommand,
-  connectWindowsRemote,
-  detectRemotePlatform,
-  helper
-} from './windows-remote-lifecycle'
+import { connectWindowsRemote, detectRemotePlatform, helper } from './windows-remote-lifecycle'
 import {
   alreadyHasNoSandbox,
   buildNoSandboxRelaunchArgs,
@@ -851,7 +814,6 @@ const APP_ICON_PATHS = [
 ]
 
 let rendererTitleBarTheme = null
-const terminalSessions = new Map()
 
 // Force the NATIVE window appearance (vibrancy material, titlebar, the
 // pre-first-paint window background) to follow the APP theme instead of the
@@ -8862,11 +8824,7 @@ async function teardownSshConnection(profile) {
 
   sshConnections.delete(scope)
 
-  for (const [id, info] of [...terminalSessions.entries()]) {
-    if (info.sshScope === scope) {
-      disposeTerminalSession(id)
-    }
-  }
+  terminalIpc.disposeTerminalSessionsForSshScope(scope)
 
   try {
     if (state.localPort && state.remotePort) {
@@ -12139,232 +12097,23 @@ ipcMain.on('hermes:zoom:set-percent', (event, percent) => {
   setAndPersistZoomLevel(window, percentToZoomLevel(Number(percent)))
 })
 
-// --- Pet overlay (pop-out mascot) -----------------------------------------
-// `request` is `{ bounds, screen }`. A fresh pop-out passes viewport-space
-// bounds (screen=false): convert to screen space by adding the main window's
-// content origin so the pet lands where it sat in-window. A remembered/dragged
-// spot passes screen-space bounds (screen=true) and is used as-is. We return the
-// resolved screen bounds so the renderer can persist exactly where it opened.
-ipcMain.handle('hermes:pet-overlay:open', async (_event, request) => {
-  const bounds = request && request.bounds ? request.bounds : request
-  const isScreen = Boolean(request && request.screen)
-  let screenBounds = bounds
-
-  try {
-    if (bounds && !isScreen && mainWindow && !mainWindow.isDestroyed()) {
-      const content = mainWindow.getContentBounds()
-      screenBounds = {
-        x: content.x + (bounds.x || 0),
-        y: content.y + (bounds.y || 0),
-        width: bounds.width,
-        height: bounds.height
-      }
-    }
-  } catch {
-    // Fall back to raw bounds if the window geometry is unavailable.
-  }
-
-  openPetOverlay(screenBounds)
-
-  return { ok: true, bounds: screenBounds }
-})
-ipcMain.handle('hermes:pet-overlay:close', async () => {
-  closePetOverlay()
-
-  return { ok: true }
-})
-// Drag/resize: the overlay reports new absolute screen bounds (it already knows
-// the pointer's screen coords). Drag keeps the size constant; the wheel-to-scale
-// gesture grows/shrinks it so the sprite is never cropped by the window edge.
-// The window is created non-resizable (no stray edge-drag on the transparent
-// frameless panel), which on Windows/Linux also blocks programmatic setBounds
-// sizing — so briefly flip resizable on whenever the size actually changes.
-ipcMain.on('hermes:pet-overlay:set-bounds', (_event, bounds) => {
-  if (!petOverlayWindow || petOverlayWindow.isDestroyed() || !bounds) {
-    return
-  }
-
-  const win = petOverlayWindow
-  const width = Math.max(80, Math.round(bounds.width))
-  const height = Math.max(80, Math.round(bounds.height))
-  const [curW, curH] = win.getSize()
-  const resizing = width !== curW || height !== curH
-
-  if (resizing && !win.isResizable()) {
-    win.setResizable(true)
-  }
-
-  win.setBounds({ x: Math.round(bounds.x), y: Math.round(bounds.y), width, height })
-
-  if (resizing) {
-    win.setResizable(false)
-  }
-})
-// Click-through: the overlay window is a full rectangle but only the pet pixels
-// should be interactive. The renderer toggles this as the cursor enters/leaves
-// the sprite so transparent margins pass clicks to whatever is behind.
-ipcMain.on('hermes:pet-overlay:ignore-mouse', (_event, ignore) => {
-  if (petOverlayWindow && !petOverlayWindow.isDestroyed()) {
-    petOverlayWindow.setIgnoreMouseEvents(Boolean(ignore), { forward: true })
-  }
-})
-// The overlay is a non-activating panel (focusable:false) so it never steals
-// the app's cmd/alt-tab anchor from the main window. But the pop-up composer
-// needs the keyboard, so the renderer asks us to flip it focusable + focus it
-// while the composer is open, then back to non-activating when it closes.
-ipcMain.on('hermes:pet-overlay:set-focusable', (_event, focusable) => {
-  if (!petOverlayWindow || petOverlayWindow.isDestroyed()) {
-    return
-  }
-
-  petOverlayWindow.setFocusable(Boolean(focusable))
-
-  if (focusable) {
-    petOverlayWindow.focus()
-  }
-})
-// Main renderer → overlay: forward the latest pet state for the overlay to render.
-ipcMain.on('hermes:pet-overlay:state', (_event, payload) => {
-  if (petOverlayWindow && !petOverlayWindow.isDestroyed()) {
-    petOverlayWindow.webContents.send('hermes:pet-overlay:state', payload)
-  }
-})
-// Overlay → main renderer: control messages (pop back in, composer submit).
-ipcMain.on('hermes:pet-overlay:control', (_event, payload) => {
-  if (!mainWindow || mainWindow.isDestroyed()) {
-    return
-  }
-
-  // Double-click toggles the app window: hide it away if it's up front, bring it
-  // back if it's minimized/buried. Pure window control — nothing for the
-  // renderer to do, so don't forward it.
-  if (payload && payload.type === 'toggle-app') {
-    if (mainWindow.isMinimized() || !mainWindow.isVisible()) {
-      mainWindow.show()
-      mainWindow.focus()
-    } else {
-      mainWindow.minimize()
-    }
-
-    return
-  }
-
-  // The mail icon means "take me to the app": raise the main window (it may be
-  // minimized or buried) before the renderer navigates to the latest thread.
-  if (payload && payload.type === 'open-app') {
-    if (mainWindow.isMinimized()) {
-      mainWindow.restore()
-    }
-
-    mainWindow.show()
-    mainWindow.focus()
-  }
-
-  mainWindow.webContents.send('hermes:pet-overlay:control', payload)
+// --- Pet overlay (pop-out mascot) — see pet-overlay-ipc.ts. ---------------
+registerPetOverlayIpc({
+  getMainWindow: () => mainWindow,
+  getPetOverlayWindow: () => petOverlayWindow,
+  openPetOverlay,
+  closePetOverlay
 })
 
-// --- HUD mode (chrome-free floating chat) -----------------------------------
-ipcMain.handle('hermes:hud:open', async (_event, request) => {
-  openHudWindow(
-    typeof request?.sessionId === 'string' ? request.sessionId : null,
-    typeof request?.profile === 'string' ? request.profile : null
-  )
-
-  return { ok: true }
-})
-
-// Real frosted glass behind the band — the thing CSS backdrop-filter cannot do,
-// because Chromium composites a transparent window's page against nothing and
-// the desktop is not in its backdrop root. Vibrancy IS the window's content
-// view, so it frosts the whole rectangle; the HUD's layout leaves no dead
-// margins for that reason, and the renderer only turns it on while the band is
-// showing (idle HUD mode must be the bar and nothing else).
-ipcMain.handle('hermes:hud:vibrancy', (_event, on) => {
-  if (hudWindow && !hudWindow.isDestroyed() && IS_MAC) {
-    hudWindow.setVibrancy(on ? 'hud' : null)
+// --- HUD mode (chrome-free floating chat) — see hud-ipc.ts. ---------------
+registerHudIpc({
+  isMac: IS_MAC,
+  getHudWindow: () => hudWindow,
+  openHudWindow,
+  closeHudWindow,
+  setHudSessionId: value => {
+    hudSessionId = value
   }
-
-  return { ok: true }
-})
-
-// Let clicks fall through the HUD wherever it isn't really there. An
-// always-on-top window eats every click inside its rectangle, and most of that
-// rectangle is a faded-out band over whatever the user is actually working in.
-// `forward` keeps mousemove flowing so the renderer can re-arm when the cursor
-// reaches the bar.
-ipcMain.on('hermes:hud:ignore-mouse', (_event, ignore) => {
-  if (hudWindow && !hudWindow.isDestroyed()) {
-    hudWindow.setIgnoreMouseEvents(Boolean(ignore), { forward: true })
-  }
-})
-
-ipcMain.on('hermes:hud:move-by', (event, delta) => {
-  if (!hudWindow || hudWindow.isDestroyed() || event.sender !== hudWindow.webContents) {
-    return
-  }
-
-  const dx = Number(delta?.x)
-  const dy = Number(delta?.y)
-  const width = Number(delta?.width)
-  const height = Number(delta?.height)
-
-  if (!Number.isFinite(dx) || !Number.isFinite(dy) || !Number.isFinite(width) || !Number.isFinite(height)) {
-    return
-  }
-
-  const [x, y] = hudWindow.getPosition()
-
-  // setBounds — NOT setPosition: on Windows, a transparent frameless window
-  // silently grows ~1px per setPosition call (worse at >100% DPI). The renderer
-  // snapshots outerWidth/outerHeight when the composer drag arms and re-pins
-  // to that size on every moveBy (same pattern as the pet overlay drag).
-  hudWindow.setBounds({
-    x: Math.round(x + dx),
-    y: Math.round(y + dy),
-    width: Math.round(width),
-    height: Math.round(height)
-  })
-})
-
-// Resize from the HUD's corner handle. The window is created non-resizable
-// (see spawnHudWindow — a transparent frameless window must not expose a
-// system resize hot-zone, or dragging grows it), which on Windows/Linux also
-// blocks programmatic setBounds sizing — so briefly flip resizable on while
-// the size actually changes, exactly like the pet overlay's wheel-scale does.
-ipcMain.on('hermes:hud:set-bounds', (event, bounds) => {
-  if (!hudWindow || hudWindow.isDestroyed() || event.sender !== hudWindow.webContents || !bounds) {
-    return
-  }
-
-  const win = hudWindow
-  const width = Math.max(380, Math.round(Number(bounds.width)))
-  const height = Math.max(160, Math.round(Number(bounds.height)))
-  const [curW, curH] = win.getSize()
-  const resizing = width !== curW || height !== curH
-
-  if (resizing && !win.isResizable()) {
-    win.setResizable(true)
-  }
-
-  win.setBounds({ x: Math.round(Number(bounds.x)), y: Math.round(Number(bounds.y)), width, height })
-
-  if (resizing) {
-    win.setResizable(false)
-  }
-})
-
-// The HUD renderer reporting which session it is on, so the close broadcast
-// can hand it back to the app window (see hudSessionId).
-ipcMain.on('hermes:hud:session', (event, sessionId) => {
-  if (hudWindow && !hudWindow.isDestroyed() && event.sender === hudWindow.webContents) {
-    hudSessionId = typeof sessionId === 'string' && sessionId ? sessionId : null
-  }
-})
-
-ipcMain.handle('hermes:hud:close', async () => {
-  closeHudWindow()
-
-  return { ok: true }
 })
 ipcMain.handle('hermes:bootstrap:reset', async () => {
   // Renderer's "Reload and retry" path. Clear the latched failure and
@@ -14383,565 +14132,30 @@ ipcMain.on('hermes:logs:renderer-error', (_event, report) => {
   flushDesktopLogBufferSync()
 })
 
-function isExecutableFile(filePath) {
-  if (!filePath || !path.isAbsolute(filePath)) {
-    return false
-  }
-
-  try {
-    fs.accessSync(filePath, fs.constants.X_OK)
-
-    return true
-  } catch {
-    return false
-  }
-}
-
-function posixShellSpec(shellPath) {
-  const shellName = path.basename(shellPath)
-  const interactiveArgs = shellName.includes('zsh') || shellName.includes('bash') ? ['-il'] : ['-i']
-
-  return { args: interactiveArgs, command: shellPath, name: shellName }
-}
-
-// Windows PowerShell 5.1 ships at a fixed System32 path on every Windows box;
-// prefer it only after PowerShell 7+ (`pwsh`).
-function windowsPowerShellPath() {
-  const systemRoot = process.env.SystemRoot || process.env.windir || 'C:\\Windows'
-  const builtin = path.join(systemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe')
-
-  return isExecutableFile(builtin) ? builtin : findOnPath('powershell.exe')
-}
-
-// Map a resolved shell path to its spawn spec, picking interactive flags by
-// family: PowerShell drops its logo banner (so the prompt sits flush like the
-// POSIX shells), cmd needs nothing, and everything else (zsh/bash/fish/sh…)
-// gets POSIX interactive-login flags.
-function shellSpecFor(shellPath) {
-  const name = path.basename(shellPath).toLowerCase()
-
-  if (name.startsWith('pwsh') || name.startsWith('powershell')) {
-    return { args: ['-NoLogo'], command: shellPath, name }
-  }
-
-  if (name.startsWith('cmd')) {
-    return { args: [], command: shellPath, name }
-  }
-
-  return posixShellSpec(shellPath)
-}
-
-// Best installed Windows shell: PowerShell 7+ (`pwsh`), then Windows PowerShell
-// 5.1, then comspec/cmd.exe as the universal fallback.
-function windowsShellSpec() {
-  const command =
-    findOnPath('pwsh.exe') || findOnPath('pwsh') || windowsPowerShellPath() || process.env.COMSPEC || 'cmd.exe'
-
-  return shellSpecFor(command)
-}
-
-// Resolve the interactive shell for the embedded terminal: an explicit user
-// override wins, otherwise auto-detect the best one installed for the platform.
-function terminalShellCommand() {
-  // HERMES_DESKTOP_SHELL is the cross-platform escape hatch (a path or a bare
-  // name on PATH); $SHELL is honored on POSIX, where it's the user's canonical
-  // choice, but ignored on Windows, where it's usually a stray MSYS/Git path
-  // node-pty can't spawn natively.
-  const override = (process.env.HERMES_DESKTOP_SHELL || (IS_WINDOWS ? '' : process.env.SHELL) || '').trim()
-
-  if (override) {
-    const resolved = isExecutableFile(override) ? override : findOnPath(override)
-
-    if (resolved) {
-      return shellSpecFor(resolved)
-    }
-  }
-
-  if (IS_WINDOWS) {
-    return windowsShellSpec()
-  }
-
-  const shellPath = ['/bin/zsh', '/bin/bash', '/bin/sh'].find(candidate => isExecutableFile(candidate))
-
-  return posixShellSpec(shellPath || '/bin/sh')
-}
-
-function safeTerminalCwd(cwd) {
-  const candidate = path.resolve(String(cwd || app.getPath('home')))
-
-  try {
-    const stat = fs.statSync(candidate)
-
-    return stat.isDirectory() ? candidate : path.dirname(candidate)
-  } catch {
-    return app.getPath('home')
-  }
-}
-
-function terminalShellEnv() {
-  const env = { ...process.env }
-
-  // Electron is commonly launched through `npm run dev`; do not leak npm's
-  // managed prefix into a user's interactive shell (nvm/proto warn loudly).
-  for (const key of Object.keys(env)) {
-    if (key === 'npm_config_prefix' || key.startsWith('npm_config_') || key.startsWith('npm_package_')) {
-      delete env[key]
-    }
-  }
-
-  // Strip color/theme-detection vars that ride along when Electron is launched
-  // from a non-tty agent shell (Cursor's runner sets NO_COLOR/FORCE_COLOR=0
-  // /TERM=dumb; some terminals set COLORFGBG which would flip Hermes' TUI into
-  // light-mode). Our PTY is a real xterm-compat terminal — force truecolor.
-  delete env.NO_COLOR
-  delete env.FORCE_COLOR
-  delete env.COLORFGBG
-
-  env.COLORTERM = 'truecolor'
-  env.LC_CTYPE = env.LC_CTYPE || 'UTF-8'
-  env.TERM = 'xterm-256color'
-  env.TERM_PROGRAM = 'Hermes'
-  env.TERM_PROGRAM_VERSION = app.getVersion()
-
-  // Let a hermes/--tui launched in this pane know it's embedded in the desktop
-  // GUI (build_environment_hints surfaces this). Distinct from HERMES_DESKTOP,
-  // which marks the agent *backend* and gates cron/gateway behavior.
-  env.HERMES_DESKTOP_TERMINAL = '1'
-
-  return env
-}
-
-function terminalChannel(id, suffix) {
-  return `hermes:terminal:${id}:${suffix}`
-}
-
-// Best-effort read of a live PTY child's current working directory so a
-// reopened tab can restart the shell where the user last `cd`'d, instead of the
-// tab's original launch dir. Shell-agnostic (no prompt/OSC config needed) on
-// POSIX; Windows has no cheap per-process cwd query without a native module, so
-// it returns null and the caller falls back to the launch cwd.
-function readProcessCwd(pid) {
-  return new Promise(resolve => {
-    if (!Number.isInteger(pid) || pid <= 0) {
-      resolve(null)
-
-      return
-    }
-
-    if (process.platform === 'linux') {
-      fs.promises
-        .readlink(`/proc/${pid}/cwd`)
-        .then(target => resolve(target || null))
-        .catch(() => resolve(null))
-
-      return
-    }
-
-    if (process.platform === 'darwin') {
-      // lsof ships with macOS; -Fn emits the cwd fd's path on an `n<path>` line.
-      execFile('lsof', ['-a', '-p', String(pid), '-d', 'cwd', '-Fn'], { timeout: 2000 }, (err, stdout) => {
-        if (err) {
-          resolve(null)
-
-          return
-        }
-
-        const line = String(stdout || '')
-          .split('\n')
-          .find(entry => entry.startsWith('n'))
-
-        resolve(line ? line.slice(1) : null)
-      })
-
-      return
-    }
-
-    resolve(null)
-  })
-}
-
-function disposeTerminalSession(id) {
-  const sessionInfo = terminalSessions.get(id)
-
-  if (!sessionInfo) {
-    return false
-  }
-
-  terminalSessions.delete(id)
-
-  try {
-    sessionInfo.pty.kill()
-  } catch {
-    // Process may already be gone.
-  }
-
-  return true
-}
-
-ipcMain.handle('hermes:fs:readDir', async (_event, dirPath) => readDirForIpc(dirPath))
-
-ipcMain.handle('hermes:fs:gitRoot', async (_event, startPath) => gitRootForIpc(startPath))
-
-// Reveal a path in the OS file manager (Finder / Explorer / Files).
-ipcMain.handle('hermes:fs:reveal', async (_event, targetPath) => {
-  const target = String(targetPath || '').trim()
-
-  if (!target) {
-    return false
-  }
-
-  try {
-    shell.showItemInFolder(target)
-
-    return true
-  } catch {
-    return false
-  }
+// Local filesystem + plugin-root IPC (readDir/reveal/rename/trash/…) — see fs-ipc.ts.
+registerFsIpc({
+  hermesHome: HERMES_HOME,
+  readActiveDesktopProfile,
+  expandUserPath,
+  resolveRequestedPathForIpc,
+  directoryExists,
+  resolveGitBinary
 })
 
-// Open a DIRECTORY in the OS file manager, creating it first if needed. Unlike
-// `reveal` (which selects an existing item and silently no-ops on a missing
-// path — the "Open plugins folder" Windows bug), this is for the plugins door,
-// which often doesn't exist on first use. `shell.openPath` returns '' on
-// success or an error string; both mkdir + openPath failures are surfaced.
-ipcMain.handle('hermes:fs:openDir', async (_event, dirPath) => {
-  const dir = String(dirPath || '').trim()
+// Git-driven features (worktrees, review pane, repo scan) — see git-ipc.ts.
+registerGitIpc({ resolveGitBinary, resolveGhBinary })
 
-  if (!dir) {
-    return { ok: false, error: 'no path' }
-  }
-
-  try {
-    await fs.promises.mkdir(dir, { recursive: true })
-    const error = await shell.openPath(path.normalize(dir))
-
-    return error ? { ok: false, error } : { ok: true }
-  } catch (error) {
-    return { ok: false, error: error instanceof Error ? error.message : String(error) }
-  }
+// Embedded terminal PTY host (hermes:terminal:*) — see terminal-ipc.ts.
+const terminalIpc = registerTerminalIpc({
+  isWindows: IS_WINDOWS,
+  findOnPath,
+  rememberLog,
+  activeSshTerminalTarget,
+  ensureBackend: () => ensureBackend(primaryProfileKey()),
+  getSshConnectionState: scope => sshConnections.get(scope)
 })
 
-// The LOCAL Desktop runtime-plugin root: `<HERMES_HOME>/desktop-plugins`,
-// resolved from the main-process HERMES_HOME (see resolveHermesHome) — NOT from
-// the connected backend. A remote backend reports its own `hermes_home` over
-// the gateway, which is a path on the REMOTE box; deriving the plugin dir from
-// it yields `undefined/desktop-plugins` (or a non-existent remote path) and the
-// on-disk plugin door silently breaks (#66899). Electron owns this resolution
-// so it stays valid in every connection mode. Created on demand, like openDir.
-async function localPluginsRoot(dirName: string): Promise<string> {
-  // Profile-aware: a named Desktop profile gets its own plugin root under
-  // profiles/<name>/, matching the profile-scoped hermes_home the backend
-  // reported before this resolver existed. 'default'/unset pins the global root.
-  const profile = readActiveDesktopProfile()
-  const base = profile && profile !== 'default' ? path.join(HERMES_HOME, 'profiles', profile) : HERMES_HOME
-  const dir = path.join(base, dirName)
-
-  try {
-    await fs.promises.mkdir(dir, { recursive: true })
-  } catch {
-    // Best-effort create; return the path regardless so the reveal action can
-    // still surface a real openPath error and the scanner can retry later.
-  }
-
-  return dir
-}
-
-ipcMain.handle('hermes:fs:desktopPluginsRoot', async () => localPluginsRoot('desktop-plugins'))
-
-// The LOCAL agent-plugin root (`<HERMES_HOME>/plugins`), same Electron-local
-// resolution as above. This is the desktop half of a UNIFIED plugin package:
-// an agent plugin may ship `desktop/plugin.js` alongside its Python code (the
-// same shape as `dashboard/manifest.json`), and the renderer's disk door scans
-// this root for it — one installable folder serving both SDKs.
-ipcMain.handle('hermes:fs:agentPluginsRoot', async () => localPluginsRoot('plugins'))
-
-ipcMain.handle('hermes:plugin:probe', async (_event, payload) => {
-  const identifier = String(payload?.identifier || payload?.repo || '').trim()
-
-  if (!identifier) {
-    return { ok: false, error: 'identifier is required', agent: false, desktop: false, warnings: [] }
-  }
-
-  return probePluginRepo(resolveGitBinary(), identifier)
-})
-
-ipcMain.handle('hermes:plugin:installDesktop', async (_event, payload) => {
-  const identifier = String(payload?.identifier || payload?.repo || '').trim()
-
-  if (!identifier) {
-    return { ok: false, error: 'identifier is required' }
-  }
-
-  const desktopPluginsRoot = await localPluginsRoot('desktop-plugins')
-
-  return installDesktopPluginFromGit(resolveGitBinary(), identifier, desktopPluginsRoot, Boolean(payload?.force))
-})
-
-// Rename a file/folder in place. The renderer passes the existing path + a new
-// base name; the destination is resolved in the SAME parent dir so a rename can
-// never move the item elsewhere or traverse out. Rejects on a name collision.
-ipcMain.handle('hermes:fs:rename', async (_event, targetPath, newName) => {
-  const src = String(targetPath || '').trim()
-  const name = String(newName || '').trim()
-
-  if (!src || !name || name === '.' || name === '..' || name.includes('/') || name.includes('\\')) {
-    throw new Error('Invalid rename')
-  }
-
-  const dst = path.join(path.dirname(src), name)
-
-  if (dst === src) {
-    return { path: dst }
-  }
-
-  if (fs.existsSync(dst)) {
-    throw new Error(`"${name}" already exists`)
-  }
-
-  await fs.promises.rename(src, dst)
-
-  return { path: dst }
-})
-
-// Write a small UTF-8 text file (e.g. a project's IDEA.md at creation). The path
-// is hardened (resolveRequestedPathForIpc) and the parent must already exist —
-// this never creates directory trees or escapes the allowed roots, and content
-// is size-capped so it can't be abused as a bulk-write primitive.
-ipcMain.handle('hermes:fs:writeText', async (_event, filePath, content) => {
-  const raw = String(filePath || '').trim()
-
-  if (!raw) {
-    throw new Error('Invalid path')
-  }
-
-  const text = String(content ?? '')
-
-  if (text.length > 1_000_000) {
-    throw new Error('Content too large')
-  }
-
-  const resolved = resolveRequestedPathForIpc(expandUserPath(raw), { purpose: 'Write text file' })
-
-  if (!directoryExists(path.dirname(resolved))) {
-    throw new Error('Parent directory does not exist')
-  }
-
-  await fs.promises.writeFile(resolved, text, 'utf8')
-
-  return { path: resolved }
-})
-
-// Move a file/folder to the OS trash (recoverable) — the VS Code "Delete"
-// default. `shell.trashItem` routes to Finder/Explorer/Files trash per platform.
-ipcMain.handle('hermes:fs:trash', async (_event, targetPath) => {
-  const target = String(targetPath || '').trim()
-
-  if (!target) {
-    throw new Error('Invalid delete')
-  }
-
-  await shell.trashItem(target)
-
-  return true
-})
-
-// Git-driven worktree management ("Start work" flow). Errors surface to the
-// renderer as rejected promises so it can toast a friendly message.
-ipcMain.handle('hermes:git:worktreeList', async (_event, repoPath) => listWorktrees(repoPath, resolveGitBinary()))
-
-ipcMain.handle('hermes:git:worktreeAdd', async (_event, repoPath, options) =>
-  addWorktree(repoPath, options || {}, resolveGitBinary())
-)
-
-ipcMain.handle('hermes:git:worktreeRemove', async (_event, repoPath, worktreePath, options) =>
-  removeWorktree(repoPath, worktreePath, options || {}, resolveGitBinary())
-)
-
-ipcMain.handle('hermes:git:branchSwitch', async (_event, repoPath, branch) =>
-  switchBranch(repoPath, branch, resolveGitBinary())
-)
-
-ipcMain.handle('hermes:git:branchList', async (_event, repoPath) => listBranches(repoPath, resolveGitBinary()))
-
-ipcMain.handle('hermes:git:baseBranchList', async (_event, repoPath) => listBaseBranches(repoPath, resolveGitBinary()))
-
-// Compact repo status (branch, ahead/behind, change counts + files) for the
-// composer coding rail. Returns null on a non-repo / remote backend so the rail
-// hides cleanly rather than erroring.
-ipcMain.handle('hermes:git:repoStatus', async (_event, repoPath) => repoStatus(repoPath, resolveGitBinary()))
-
-// Codex-style review pane: list changed files for a scope, fetch one file's
-// unified diff, and stage / unstage / revert. Reads return empty on failure;
-// mutations reject so the renderer can toast.
-ipcMain.handle('hermes:git:review:list', async (_event, repoPath, scope, baseRef) =>
-  reviewList(repoPath, scope, baseRef, resolveGitBinary())
-)
-ipcMain.handle('hermes:git:review:diff', async (_event, repoPath, filePath, scope, baseRef, staged) =>
-  reviewDiff(repoPath, filePath, scope, baseRef, staged, resolveGitBinary())
-)
-// Working-tree-vs-HEAD diff for one file (the preview's "show the diff" view).
-ipcMain.handle('hermes:git:fileDiff', async (_event, repoPath, filePath) =>
-  fileDiffVsHead(repoPath, filePath, resolveGitBinary())
-)
-ipcMain.handle('hermes:git:review:stage', async (_event, repoPath, filePath) =>
-  reviewStage(repoPath, filePath ?? null, resolveGitBinary())
-)
-ipcMain.handle('hermes:git:review:unstage', async (_event, repoPath, filePath) =>
-  reviewUnstage(repoPath, filePath ?? null, resolveGitBinary())
-)
-ipcMain.handle('hermes:git:review:revert', async (_event, repoPath, filePath) =>
-  reviewRevert(repoPath, filePath ?? null, resolveGitBinary())
-)
-ipcMain.handle('hermes:git:review:revParse', async (_event, repoPath, ref) =>
-  reviewRevParse(repoPath, ref, resolveGitBinary())
-)
-ipcMain.handle('hermes:git:review:commit', async (_event, repoPath, message, push) =>
-  reviewCommit(repoPath, message, Boolean(push), resolveGitBinary())
-)
-ipcMain.handle('hermes:git:review:commitContext', async (_event, repoPath) =>
-  reviewCommitContext(repoPath, resolveGitBinary())
-)
-ipcMain.handle('hermes:git:review:push', async (_event, repoPath) => reviewPush(repoPath, resolveGitBinary()))
-ipcMain.handle('hermes:git:review:shipInfo', async (_event, repoPath) => reviewShipInfo(repoPath, resolveGhBinary()))
-ipcMain.handle('hermes:git:review:prList', async (_event, repoPath, branches, numbers) =>
-  reviewPrList(repoPath, resolveGhBinary(), branches, numbers)
-)
-ipcMain.handle('hermes:git:review:fetchPrComment', async (_event, repoPath, url) =>
-  reviewFetchPrComment(repoPath, resolveGhBinary(), url)
-)
-ipcMain.handle('hermes:git:review:createPr', async (_event, repoPath) =>
-  reviewCreatePr(repoPath, resolveGitBinary(), resolveGhBinary())
-)
-
-// Repo-first project discovery: scan bounded roots for git repos (pure fs walk,
-// no native addon). Never throws to the renderer — failures yield an empty list.
-ipcMain.handle('hermes:git:scanRepos', async (_event, roots, options) => {
-  try {
-    return await scanGitRepos(roots || [], options || {})
-  } catch {
-    return []
-  }
-})
-
-// node-pty's published tarball ships the POSIX `spawn-helper` without an exec
-// bit; the dev flow resolves node-pty straight from node_modules (nothing
-// chmods it there), so the first terminal spawn dies with `posix_spawnp
-// failed`. Restore the bit once, lazily, right before the first spawn. Packaged
-// builds already stage an executable copy, so this is a no-op there.
-let _spawnHelperEnsured = false
-
-function ensureNodePtySpawnHelper() {
-  if (_spawnHelperEnsured || IS_WINDOWS) {
-    return
-  }
-
-  _spawnHelperEnsured = true
-
-  try {
-    const nodePtyRoot = path.dirname(require.resolve('node-pty/package.json'))
-    const { fixed, errors } = ensureSpawnHelperExecutable(nodePtyRoot)
-
-    for (const helperPath of fixed) {
-      rememberLog(`[terminal] restored +x on node-pty spawn-helper: ${helperPath}`)
-    }
-
-    for (const failure of errors) {
-      rememberLog(`[terminal] could not chmod spawn-helper ${failure.path}: ${failure.error}`)
-    }
-  } catch (error) {
-    rememberLog(`[terminal] spawn-helper exec check skipped: ${error instanceof Error ? error.message : String(error)}`)
-  }
-}
-
-ipcMain.handle('hermes:terminal:start', async (event, payload = {}) => {
-  ensureNodePtySpawnHelper()
-
-  const id = crypto.randomUUID()
-  const { args, command, name } = terminalShellCommand()
-  const cwd = safeTerminalCwd(payload?.cwd)
-  const cols = Math.max(2, Number.parseInt(String(payload?.cols || 80), 10) || 80)
-  const rows = Math.max(2, Number.parseInt(String(payload?.rows || 24), 10) || 24)
-
-  const sshTarget = await resolveTerminalConnection(activeSshTerminalTarget, () => ensureBackend(primaryProfileKey()))
-  const remote = Boolean(sshTarget)
-  const remoteState = remote ? sshConnections.get(sshTarget.scope) : null
-
-  const remoteCommand =
-    remoteState?.remotePlatform === 'Windows'
-      ? buildWindowsInteractiveCommand(String(payload?.cwd || '').trim())
-      : undefined
-
-  const ptyProcess = remote
-    ? nodePty.spawn(
-        process.platform === 'win32'
-          ? path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'OpenSSH', 'ssh.exe')
-          : 'ssh',
-        buildInteractiveSshArgs(sshTarget.ssh, String(payload?.cwd || '').trim(), undefined, remoteCommand),
-        { cols, cwd: app.getPath('home'), env: terminalShellEnv(), name: 'xterm-256color', rows }
-      )
-    : nodePty.spawn(command, args, { cols, cwd, env: terminalShellEnv(), name: 'xterm-256color', rows })
-
-  terminalSessions.set(id, {
-    pty: ptyProcess,
-    webContentsId: event.sender.id,
-    ...(remote ? { sshScope: sshTarget.scope, remoteCwd: String(payload?.cwd || '') } : {})
-  })
-
-  const send = (suffix, payload) => {
-    if (event.sender.isDestroyed()) {
-      return
-    }
-
-    event.sender.send(terminalChannel(id, suffix), payload)
-  }
-
-  ptyProcess.onData(data => send('data', data))
-  ptyProcess.onExit(({ exitCode, signal }) => {
-    terminalSessions.delete(id)
-    send('exit', { code: exitCode, signal: signal || null })
-  })
-  event.sender.once('destroyed', () => disposeTerminalSession(id))
-
-  return { cwd: remote ? null : cwd, id, shell: remote ? 'ssh' : name }
-})
-
-ipcMain.handle('hermes:terminal:write', (_event, id, data) => {
-  const sessionInfo = terminalSessions.get(String(id || ''))
-
-  if (!sessionInfo) {
-    return false
-  }
-
-  sessionInfo.pty.write(String(data || ''))
-
-  return true
-})
-
-ipcMain.handle('hermes:terminal:resize', (_event, id, size = {}) => {
-  const sessionInfo = terminalSessions.get(String(id || ''))
-
-  if (!sessionInfo) {
-    return false
-  }
-
-  const cols = Math.max(2, Number.parseInt(String(size?.cols || 80), 10) || 80)
-  const rows = Math.max(2, Number.parseInt(String(size?.rows || 24), 10) || 24)
-
-  sessionInfo.pty.resize(cols, rows)
-
-  return true
-})
-ipcMain.handle('hermes:terminal:cwd', async (_event, id) => {
-  const sessionInfo = terminalSessions.get(String(id || ''))
-
-  if (!sessionInfo) {
-    return null
-  }
-
-  return sessionInfo.sshScope !== undefined ? null : readProcessCwd(sessionInfo.pty.pid)
-})
-
-ipcMain.handle('hermes:terminal:dispose', (_event, id) => disposeTerminalSession(String(id || '')))
+const disposeTerminalSession = terminalIpc.disposeTerminalSession
 
 ipcMain.handle('hermes:updates:check', async () =>
   checkUpdates().catch(error => ({
@@ -15644,9 +14858,7 @@ app.on('before-quit', event => {
 
   // Kill open PTYs before environment teardown to avoid the node-pty#904
   // ThreadSafeFunction SIGABRT race.
-  for (const id of [...terminalSessions.keys()]) {
-    disposeTerminalSession(id)
-  }
+  terminalIpc.disposeAllTerminalSessions()
 
   void backendShutdown.run()
 })
diff --git a/apps/desktop/electron/pet-overlay-ipc.ts b/apps/desktop/electron/pet-overlay-ipc.ts
new file mode 100644
index 0000000000..9738f4e8e0
--- /dev/null
+++ b/apps/desktop/electron/pet-overlay-ipc.ts
@@ -0,0 +1,151 @@
+// IPC surface for the pop-out pet overlay (mascot window). Extracted from
+// main.ts; window handles stay injected because main.ts owns their lifecycle.
+import { type BrowserWindow, ipcMain } from 'electron'
+
+export interface PetOverlayIpcDeps {
+  getMainWindow: () => BrowserWindow | null
+  getPetOverlayWindow: () => BrowserWindow | null
+  openPetOverlay: (bounds: unknown) => void
+  closePetOverlay: () => void
+}
+
+export function registerPetOverlayIpc({
+  getMainWindow,
+  getPetOverlayWindow,
+  openPetOverlay,
+  closePetOverlay
+}: PetOverlayIpcDeps) {
+  // `request` is `{ bounds, screen }`. A fresh pop-out passes viewport-space
+  // bounds (screen=false): convert to screen space by adding the main window's
+  // content origin so the pet lands where it sat in-window. A remembered/dragged
+  // spot passes screen-space bounds (screen=true) and is used as-is. We return the
+  // resolved screen bounds so the renderer can persist exactly where it opened.
+  ipcMain.handle('hermes:pet-overlay:open', async (_event, request) => {
+    const bounds = request && request.bounds ? request.bounds : request
+    const isScreen = Boolean(request && request.screen)
+    const mainWindow = getMainWindow()
+    let screenBounds = bounds
+
+    try {
+      if (bounds && !isScreen && mainWindow && !mainWindow.isDestroyed()) {
+        const content = mainWindow.getContentBounds()
+        screenBounds = {
+          x: content.x + (bounds.x || 0),
+          y: content.y + (bounds.y || 0),
+          width: bounds.width,
+          height: bounds.height
+        }
+      }
+    } catch {
+      // Fall back to raw bounds if the window geometry is unavailable.
+    }
+
+    openPetOverlay(screenBounds)
+
+    return { ok: true, bounds: screenBounds }
+  })
+  ipcMain.handle('hermes:pet-overlay:close', async () => {
+    closePetOverlay()
+
+    return { ok: true }
+  })
+  // Drag/resize: the overlay reports new absolute screen bounds (it already knows
+  // the pointer's screen coords). Drag keeps the size constant; the wheel-to-scale
+  // gesture grows/shrinks it so the sprite is never cropped by the window edge.
+  // The window is created non-resizable (no stray edge-drag on the transparent
+  // frameless panel), which on Windows/Linux also blocks programmatic setBounds
+  // sizing — so briefly flip resizable on whenever the size actually changes.
+  ipcMain.on('hermes:pet-overlay:set-bounds', (_event, bounds) => {
+    const petOverlayWindow = getPetOverlayWindow()
+
+    if (!petOverlayWindow || petOverlayWindow.isDestroyed() || !bounds) {
+      return
+    }
+
+    const win = petOverlayWindow
+    const width = Math.max(80, Math.round(bounds.width))
+    const height = Math.max(80, Math.round(bounds.height))
+    const [curW, curH] = win.getSize()
+    const resizing = width !== curW || height !== curH
+
+    if (resizing && !win.isResizable()) {
+      win.setResizable(true)
+    }
+
+    win.setBounds({ x: Math.round(bounds.x), y: Math.round(bounds.y), width, height })
+
+    if (resizing) {
+      win.setResizable(false)
+    }
+  })
+  // Click-through: the overlay window is a full rectangle but only the pet pixels
+  // should be interactive. The renderer toggles this as the cursor enters/leaves
+  // the sprite so transparent margins pass clicks to whatever is behind.
+  ipcMain.on('hermes:pet-overlay:ignore-mouse', (_event, ignore) => {
+    const petOverlayWindow = getPetOverlayWindow()
+
+    if (petOverlayWindow && !petOverlayWindow.isDestroyed()) {
+      petOverlayWindow.setIgnoreMouseEvents(Boolean(ignore), { forward: true })
+    }
+  })
+  // The overlay is a non-activating panel (focusable:false) so it never steals
+  // the app's cmd/alt-tab anchor from the main window. But the pop-up composer
+  // needs the keyboard, so the renderer asks us to flip it focusable + focus it
+  // while the composer is open, then back to non-activating when it closes.
+  ipcMain.on('hermes:pet-overlay:set-focusable', (_event, focusable) => {
+    const petOverlayWindow = getPetOverlayWindow()
+
+    if (!petOverlayWindow || petOverlayWindow.isDestroyed()) {
+      return
+    }
+
+    petOverlayWindow.setFocusable(Boolean(focusable))
+
+    if (focusable) {
+      petOverlayWindow.focus()
+    }
+  })
+  // Main renderer → overlay: forward the latest pet state for the overlay to render.
+  ipcMain.on('hermes:pet-overlay:state', (_event, payload) => {
+    const petOverlayWindow = getPetOverlayWindow()
+
+    if (petOverlayWindow && !petOverlayWindow.isDestroyed()) {
+      petOverlayWindow.webContents.send('hermes:pet-overlay:state', payload)
+    }
+  })
+  // Overlay → main renderer: control messages (pop back in, composer submit).
+  ipcMain.on('hermes:pet-overlay:control', (_event, payload) => {
+    const mainWindow = getMainWindow()
+
+    if (!mainWindow || mainWindow.isDestroyed()) {
+      return
+    }
+
+    // Double-click toggles the app window: hide it away if it's up front, bring it
+    // back if it's minimized/buried. Pure window control — nothing for the
+    // renderer to do, so don't forward it.
+    if (payload && payload.type === 'toggle-app') {
+      if (mainWindow.isMinimized() || !mainWindow.isVisible()) {
+        mainWindow.show()
+        mainWindow.focus()
+      } else {
+        mainWindow.minimize()
+      }
+
+      return
+    }
+
+    // The mail icon means "take me to the app": raise the main window (it may be
+    // minimized or buried) before the renderer navigates to the latest thread.
+    if (payload && payload.type === 'open-app') {
+      if (mainWindow.isMinimized()) {
+        mainWindow.restore()
+      }
+
+      mainWindow.show()
+      mainWindow.focus()
+    }
+
+    mainWindow.webContents.send('hermes:pet-overlay:control', payload)
+  })
+}
diff --git a/apps/desktop/electron/remote-lifecycle.ts b/apps/desktop/electron/remote-lifecycle.ts
index 501786863c..4a672685ec 100644
--- a/apps/desktop/electron/remote-lifecycle.ts
+++ b/apps/desktop/electron/remote-lifecycle.ts
@@ -28,6 +28,7 @@
 import crypto from 'node:crypto'
 
 import { parseRemoteProfileListing } from './connection-registry'
+import { assertBootstrapNotSuperseded } from './ssh-connection'
 
 const LOCKFILE_SCHEMA_VERSION = 2
 // Bumped when the desktop<->dashboard reuse contract changes in a way that makes
@@ -558,7 +559,7 @@ async function scrapeReadyPort(ssh, logPath, { timeoutMs = DEFAULT_READY_TIMEOUT
   const remoteLog = expandRemotePath(logPath)
 
   while (Date.now() < deadline) {
-    assertNotAborted(signal)
+    assertBootstrapNotSuperseded(signal)
 
     if (isAlive && !(await isAlive())) {
       const err: any = new Error('Remote dashboard process exited before announcing its port.')
@@ -696,14 +697,6 @@ async function cancelForwardSafe(deps, localPort, remotePort) {
   }
 }
 
-function assertNotAborted(signal) {
-  if (signal?.aborted) {
-    const error: any = new Error('SSH bootstrap was cancelled.')
-    error.kind = 'superseded'
-    throw error
-  }
-}
-
 function isForwardBindCollision(error) {
   return /address already in use|cannot listen to port|bind.*failed/i.test(String(error?.message || error || ''))
 }
@@ -769,7 +762,7 @@ async function connect(deps) {
 
   const log = msg => rememberLog(`[ssh-lifecycle] ${msg}`)
 
-  assertNotAborted(signal)
+  assertBootstrapNotSuperseded(signal)
   const platform = await probeRemotePlatform(ssh)
   log(`remote platform ${platform.os}/${platform.arch}`)
   const hermesPath = await locateHermes(ssh, remoteHermesPath)
@@ -810,7 +803,7 @@ async function connect(deps) {
       lock.hermesHome === hermesHome
 
     if (reusable) {
-      assertNotAborted(signal)
+      assertBootstrapNotSuperseded(signal)
       const localPort = await openForward(deps, lock.port)
 
       try {
@@ -827,7 +820,7 @@ async function connect(deps) {
         }
 
         if (reuseClassification === 'authenticated-stale') {
-          assertNotAborted(signal)
+          assertBootstrapNotSuperseded(signal)
           await cancelForwardSafe(deps, localPort, lock.port)
           await cleanupStale(ssh, ownershipId, lock)
         } else if (reuseClassification === 'authenticated-ok') {
@@ -840,7 +833,7 @@ async function connect(deps) {
             'reused remote dashboard'
           )
 
-          assertNotAborted(signal)
+          assertBootstrapNotSuperseded(signal)
           log(`reusing remote dashboard pid=${lock.pid} port=${lock.port}`)
 
           return {
@@ -868,12 +861,12 @@ async function connect(deps) {
         throw error
       }
     } else {
-      assertNotAborted(signal)
+      assertBootstrapNotSuperseded(signal)
       await cleanupStale(ssh, ownershipId, lock, pidAlive)
     }
   }
 
-  assertNotAborted(signal)
+  assertBootstrapNotSuperseded(signal)
   const spawnToken = mintToken()
 
   const { pid, spawnNonce, logPath, tokenFilePath } = await spawnRemoteDashboard(ssh, {
@@ -914,21 +907,21 @@ async function connect(deps) {
       isAlive: () => remotePidAlive(ssh, pid),
       signal
     })
-    assertNotAborted(signal)
+    assertBootstrapNotSuperseded(signal)
     log(`remote dashboard bound port ${remotePort}`)
 
     localPort = await openForward(deps, remotePort)
-    assertNotAborted(signal)
+    assertBootstrapNotSuperseded(signal)
     const baseUrl = `http://127.0.0.1:${localPort}`
     await waitForHermes(baseUrl, spawnToken)
-    assertNotAborted(signal)
+    assertBootstrapNotSuperseded(signal)
 
     const token = await adoptOwnedServedToken(adoptServedToken, baseUrl, spawnToken, ssh, pid, 'remote dashboard')
 
-    assertNotAborted(signal)
+    assertBootstrapNotSuperseded(signal)
     const tokenFingerprint = fingerprintToken(token)
     await writeLockfile(ssh, ownershipId, { ...ownedSpawn, port: remotePort, tokenFingerprint })
-    assertNotAborted(signal)
+    assertBootstrapNotSuperseded(signal)
 
     return {
       baseUrl,
diff --git a/apps/desktop/electron/ssh-connection.ts b/apps/desktop/electron/ssh-connection.ts
index 5015f979e3..57264ec639 100644
--- a/apps/desktop/electron/ssh-connection.ts
+++ b/apps/desktop/electron/ssh-connection.ts
@@ -988,7 +988,19 @@ function createSshProbeConnection(config, options: any = {}) {
   return new SshConnection(config, { ...options, mux: false })
 }
 
+// Bootstrap loops poll a remote for readiness; a newer attempt aborts the
+// signal so the stale one stops polling and unwinds. `superseded` tells the
+// caller this was replaced, not that it failed.
+function assertBootstrapNotSuperseded(signal) {
+  if (signal?.aborted) {
+    const error: any = new Error('SSH bootstrap was cancelled.')
+    error.kind = 'superseded'
+    throw error
+  }
+}
+
 export {
+  assertBootstrapNotSuperseded,
   baseSshOptions,
   buildControlArgs,
   buildExecArgs,
diff --git a/apps/desktop/electron/terminal-ipc.ts b/apps/desktop/electron/terminal-ipc.ts
new file mode 100644
index 0000000000..1b5953b859
--- /dev/null
+++ b/apps/desktop/electron/terminal-ipc.ts
@@ -0,0 +1,377 @@
+// The embedded terminal's PTY host: shell resolution, env scrubbing, session
+// registry, and the hermes:terminal:* IPC surface. Extracted from main.ts; the
+// factory owns the session map and returns the dispose helpers main.ts needs
+// for SSH teardown. findOnPath / logging / connection routing stay injected.
+import { execFile } from 'node:child_process'
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+
+import { app, ipcMain } from 'electron'
+import nodePty from 'node-pty'
+
+import { resolveTerminalConnection } from './connection-apply'
+import { ensureSpawnHelperExecutable } from './spawn-helper-perms'
+import { buildInteractiveSshArgs } from './ssh-connection'
+import { buildWindowsInteractiveCommand } from './windows-remote-lifecycle'
+
+export interface TerminalIpcDeps {
+  isWindows: boolean
+  findOnPath: (command: string) => null | string
+  rememberLog: (line: string) => void
+  activeSshTerminalTarget: () => unknown
+  ensureBackend: () => Promise<unknown>
+  getSshConnectionState: (scope: string) => undefined | { remotePlatform?: string }
+}
+
+export interface TerminalIpcApi {
+  disposeTerminalSession: (id: string) => boolean
+  disposeTerminalSessionsForSshScope: (scope: string) => void
+  disposeAllTerminalSessions: () => void
+}
+
+export function registerTerminalIpc({
+  isWindows,
+  findOnPath,
+  rememberLog,
+  activeSshTerminalTarget,
+  ensureBackend,
+  getSshConnectionState
+}: TerminalIpcDeps): TerminalIpcApi {
+  const terminalSessions = new Map()
+
+  function isExecutableFile(filePath) {
+    if (!filePath || !path.isAbsolute(filePath)) {
+      return false
+    }
+
+    try {
+      fs.accessSync(filePath, fs.constants.X_OK)
+
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  function posixShellSpec(shellPath) {
+    const shellName = path.basename(shellPath)
+    const interactiveArgs = shellName.includes('zsh') || shellName.includes('bash') ? ['-il'] : ['-i']
+
+    return { args: interactiveArgs, command: shellPath, name: shellName }
+  }
+
+  // Windows PowerShell 5.1 ships at a fixed System32 path on every Windows box;
+  // prefer it only after PowerShell 7+ (`pwsh`).
+  function windowsPowerShellPath() {
+    const systemRoot = process.env.SystemRoot || process.env.windir || 'C:\\Windows'
+    const builtin = path.join(systemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe')
+
+    return isExecutableFile(builtin) ? builtin : findOnPath('powershell.exe')
+  }
+
+  // Map a resolved shell path to its spawn spec, picking interactive flags by
+  // family: PowerShell drops its logo banner (so the prompt sits flush like the
+  // POSIX shells), cmd needs nothing, and everything else (zsh/bash/fish/sh…)
+  // gets POSIX interactive-login flags.
+  function shellSpecFor(shellPath) {
+    const name = path.basename(shellPath).toLowerCase()
+
+    if (name.startsWith('pwsh') || name.startsWith('powershell')) {
+      return { args: ['-NoLogo'], command: shellPath, name }
+    }
+
+    if (name.startsWith('cmd')) {
+      return { args: [], command: shellPath, name }
+    }
+
+    return posixShellSpec(shellPath)
+  }
+
+  // Best installed Windows shell: PowerShell 7+ (`pwsh`), then Windows PowerShell
+  // 5.1, then comspec/cmd.exe as the universal fallback.
+  function windowsShellSpec() {
+    const command =
+      findOnPath('pwsh.exe') || findOnPath('pwsh') || windowsPowerShellPath() || process.env.COMSPEC || 'cmd.exe'
+
+    return shellSpecFor(command)
+  }
+
+  // Resolve the interactive shell for the embedded terminal: an explicit user
+  // override wins, otherwise auto-detect the best one installed for the platform.
+  function terminalShellCommand() {
+    // HERMES_DESKTOP_SHELL is the cross-platform escape hatch (a path or a bare
+    // name on PATH); $SHELL is honored on POSIX, where it's the user's canonical
+    // choice, but ignored on Windows, where it's usually a stray MSYS/Git path
+    // node-pty can't spawn natively.
+    const override = (process.env.HERMES_DESKTOP_SHELL || (isWindows ? '' : process.env.SHELL) || '').trim()
+
+    if (override) {
+      const resolved = isExecutableFile(override) ? override : findOnPath(override)
+
+      if (resolved) {
+        return shellSpecFor(resolved)
+      }
+    }
+
+    if (isWindows) {
+      return windowsShellSpec()
+    }
+
+    const shellPath = ['/bin/zsh', '/bin/bash', '/bin/sh'].find(candidate => isExecutableFile(candidate))
+
+    return posixShellSpec(shellPath || '/bin/sh')
+  }
+
+  function safeTerminalCwd(cwd) {
+    const candidate = path.resolve(String(cwd || app.getPath('home')))
+
+    try {
+      const stat = fs.statSync(candidate)
+
+      return stat.isDirectory() ? candidate : path.dirname(candidate)
+    } catch {
+      return app.getPath('home')
+    }
+  }
+
+  function terminalShellEnv() {
+    const env = { ...process.env }
+
+    // Electron is commonly launched through `npm run dev`; do not leak npm's
+    // managed prefix into a user's interactive shell (nvm/proto warn loudly).
+    for (const key of Object.keys(env)) {
+      if (key === 'npm_config_prefix' || key.startsWith('npm_config_') || key.startsWith('npm_package_')) {
+        delete env[key]
+      }
+    }
+
+    // Strip color/theme-detection vars that ride along when Electron is launched
+    // from a non-tty agent shell (Cursor's runner sets NO_COLOR/FORCE_COLOR=0
+    // /TERM=dumb; some terminals set COLORFGBG which would flip Hermes' TUI into
+    // light-mode). Our PTY is a real xterm-compat terminal — force truecolor.
+    delete env.NO_COLOR
+    delete env.FORCE_COLOR
+    delete env.COLORFGBG
+
+    env.COLORTERM = 'truecolor'
+    env.LC_CTYPE = env.LC_CTYPE || 'UTF-8'
+    env.TERM = 'xterm-256color'
+    env.TERM_PROGRAM = 'Hermes'
+    env.TERM_PROGRAM_VERSION = app.getVersion()
+
+    // Let a hermes/--tui launched in this pane know it's embedded in the desktop
+    // GUI (build_environment_hints surfaces this). Distinct from HERMES_DESKTOP,
+    // which marks the agent *backend* and gates cron/gateway behavior.
+    env.HERMES_DESKTOP_TERMINAL = '1'
+
+    return env
+  }
+
+  function terminalChannel(id, suffix) {
+    return `hermes:terminal:${id}:${suffix}`
+  }
+
+  // Best-effort read of a live PTY child's current working directory so a
+  // reopened tab can restart the shell where the user last `cd`'d, instead of the
+  // tab's original launch dir. Shell-agnostic (no prompt/OSC config needed) on
+  // POSIX; Windows has no cheap per-process cwd query without a native module, so
+  // it returns null and the caller falls back to the launch cwd.
+  function readProcessCwd(pid) {
+    return new Promise(resolve => {
+      if (!Number.isInteger(pid) || pid <= 0) {
+        resolve(null)
+
+        return
+      }
+
+      if (process.platform === 'linux') {
+        fs.promises
+          .readlink(`/proc/${pid}/cwd`)
+          .then(target => resolve(target || null))
+          .catch(() => resolve(null))
+
+        return
+      }
+
+      if (process.platform === 'darwin') {
+        // lsof ships with macOS; -Fn emits the cwd fd's path on an `n<path>` line.
+        execFile('lsof', ['-a', '-p', String(pid), '-d', 'cwd', '-Fn'], { timeout: 2000 }, (err, stdout) => {
+          if (err) {
+            resolve(null)
+
+            return
+          }
+
+          const line = String(stdout || '')
+            .split('\n')
+            .find(entry => entry.startsWith('n'))
+
+          resolve(line ? line.slice(1) : null)
+        })
+
+        return
+      }
+
+      resolve(null)
+    })
+  }
+
+  function disposeTerminalSession(id: string) {
+    const sessionInfo = terminalSessions.get(id)
+
+    if (!sessionInfo) {
+      return false
+    }
+
+    terminalSessions.delete(id)
+
+    try {
+      sessionInfo.pty.kill()
+    } catch {
+      // Process may already be gone.
+    }
+
+    return true
+  }
+
+  // SSH teardown: close every pane whose PTY rode the disconnected tunnel.
+  function disposeTerminalSessionsForSshScope(scope: string) {
+    for (const [id, info] of [...terminalSessions.entries()]) {
+      if (info.sshScope === scope) {
+        disposeTerminalSession(id)
+      }
+    }
+  }
+
+  // App shutdown: kill every open PTY before environment teardown.
+  function disposeAllTerminalSessions() {
+    for (const id of [...terminalSessions.keys()]) {
+      disposeTerminalSession(id)
+    }
+  }
+
+  // node-pty's published tarball ships the POSIX `spawn-helper` without an exec
+  // bit; the dev flow resolves node-pty straight from node_modules (nothing
+  // chmods it there), so the first terminal spawn dies with `posix_spawnp
+  // failed`. Restore the bit once, lazily, right before the first spawn. Packaged
+  // builds already stage an executable copy, so this is a no-op there.
+  let _spawnHelperEnsured = false
+
+  function ensureNodePtySpawnHelper() {
+    if (_spawnHelperEnsured || isWindows) {
+      return
+    }
+
+    _spawnHelperEnsured = true
+
+    try {
+      const nodePtyRoot = path.dirname(require.resolve('node-pty/package.json'))
+      const { fixed, errors } = ensureSpawnHelperExecutable(nodePtyRoot)
+
+      for (const helperPath of fixed) {
+        rememberLog(`[terminal] restored +x on node-pty spawn-helper: ${helperPath}`)
+      }
+
+      for (const failure of errors) {
+        rememberLog(`[terminal] could not chmod spawn-helper ${failure.path}: ${failure.error}`)
+      }
+    } catch (error) {
+      rememberLog(
+        `[terminal] spawn-helper exec check skipped: ${error instanceof Error ? error.message : String(error)}`
+      )
+    }
+  }
+
+  ipcMain.handle('hermes:terminal:start', async (event, payload = {}) => {
+    ensureNodePtySpawnHelper()
+
+    const id = crypto.randomUUID()
+    const { args, command, name } = terminalShellCommand()
+    const cwd = safeTerminalCwd(payload?.cwd)
+    const cols = Math.max(2, Number.parseInt(String(payload?.cols || 80), 10) || 80)
+    const rows = Math.max(2, Number.parseInt(String(payload?.rows || 24), 10) || 24)
+
+    const sshTarget = await resolveTerminalConnection(activeSshTerminalTarget, ensureBackend)
+    const remote = Boolean(sshTarget)
+    const remoteState = remote ? getSshConnectionState(sshTarget.scope) : null
+
+    const remoteCommand =
+      remoteState?.remotePlatform === 'Windows'
+        ? buildWindowsInteractiveCommand(String(payload?.cwd || '').trim())
+        : undefined
+
+    const ptyProcess = remote
+      ? nodePty.spawn(
+          process.platform === 'win32'
+            ? path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'OpenSSH', 'ssh.exe')
+            : 'ssh',
+          buildInteractiveSshArgs(sshTarget.ssh, String(payload?.cwd || '').trim(), undefined, remoteCommand),
+          { cols, cwd: app.getPath('home'), env: terminalShellEnv(), name: 'xterm-256color', rows }
+        )
+      : nodePty.spawn(command, args, { cols, cwd, env: terminalShellEnv(), name: 'xterm-256color', rows })
+
+    terminalSessions.set(id, {
+      pty: ptyProcess,
+      webContentsId: event.sender.id,
+      ...(remote ? { sshScope: sshTarget.scope, remoteCwd: String(payload?.cwd || '') } : {})
+    })
+
+    const send = (suffix, payload) => {
+      if (event.sender.isDestroyed()) {
+        return
+      }
+
+      event.sender.send(terminalChannel(id, suffix), payload)
+    }
+
+    ptyProcess.onData(data => send('data', data))
+    ptyProcess.onExit(({ exitCode, signal }) => {
+      terminalSessions.delete(id)
+      send('exit', { code: exitCode, signal: signal || null })
+    })
+    event.sender.once('destroyed', () => disposeTerminalSession(id))
+
+    return { cwd: remote ? null : cwd, id, shell: remote ? 'ssh' : name }
+  })
+
+  ipcMain.handle('hermes:terminal:write', (_event, id, data) => {
+    const sessionInfo = terminalSessions.get(String(id || ''))
+
+    if (!sessionInfo) {
+      return false
+    }
+
+    sessionInfo.pty.write(String(data || ''))
+
+    return true
+  })
+
+  ipcMain.handle('hermes:terminal:resize', (_event, id, size = {}) => {
+    const sessionInfo = terminalSessions.get(String(id || ''))
+
+    if (!sessionInfo) {
+      return false
+    }
+
+    const cols = Math.max(2, Number.parseInt(String(size?.cols || 80), 10) || 80)
+    const rows = Math.max(2, Number.parseInt(String(size?.rows || 24), 10) || 24)
+
+    sessionInfo.pty.resize(cols, rows)
+
+    return true
+  })
+  ipcMain.handle('hermes:terminal:cwd', async (_event, id) => {
+    const sessionInfo = terminalSessions.get(String(id || ''))
+
+    if (!sessionInfo) {
+      return null
+    }
+
+    return sessionInfo.sshScope !== undefined ? null : readProcessCwd(sessionInfo.pty.pid)
+  })
+
+  ipcMain.handle('hermes:terminal:dispose', (_event, id) => disposeTerminalSession(String(id || '')))
+
+  return { disposeTerminalSession, disposeTerminalSessionsForSshScope, disposeAllTerminalSessions }
+}
diff --git a/apps/desktop/electron/windows-remote-lifecycle.ts b/apps/desktop/electron/windows-remote-lifecycle.ts
index 5d96853a1a..40d89b3ece 100644
--- a/apps/desktop/electron/windows-remote-lifecycle.ts
+++ b/apps/desktop/electron/windows-remote-lifecycle.ts
@@ -1,6 +1,6 @@
 import crypto from 'node:crypto'
 
-import { redactSecrets, SSH_ERROR } from './ssh-connection'
+import { assertBootstrapNotSuperseded, redactSecrets, SSH_ERROR } from './ssh-connection'
 
 const LOCKFILE_SCHEMA_VERSION = 2
 const PROTOCOL_VERSION = 1
@@ -162,14 +162,6 @@ function reusableWindowsLock(lock, state, profile, reuseToken, runtime) {
   )
 }
 
-function assertCurrent(signal) {
-  if (signal?.aborted) {
-    const error: any = new Error('SSH bootstrap was cancelled.')
-    error.kind = 'superseded'
-    throw error
-  }
-}
-
 async function processState(ssh, runtime, lock) {
   return helper(ssh, runtime, 'process-state', [
     String(lock.pid),
@@ -215,7 +207,7 @@ async function waitReady(ssh, runtime, ownershipId, lock, timeoutMs, signal) {
   const deadline = Date.now() + timeoutMs
 
   while (Date.now() < deadline) {
-    assertCurrent(signal)
+    assertBootstrapNotSuperseded(signal)
     let state
 
     try {
@@ -286,7 +278,7 @@ async function connectWindowsRemote(deps) {
     readyTimeoutMs = 45_000
   } = deps
 
-  assertCurrent(signal)
+  assertBootstrapNotSuperseded(signal)
   const runtime = await probeWindowsRemote(ssh, remoteHermesPath)
   const inspection = await helper(ssh, runtime, 'inspect', [runtime.hermesPath])
 
@@ -356,7 +348,7 @@ async function connectWindowsRemote(deps) {
     await helper(ssh, runtime, 'remove-lock', [ownershipId])
   }
 
-  assertCurrent(signal)
+  assertBootstrapNotSuperseded(signal)
   const token = crypto.randomBytes(32).toString('hex')
   const spawnNonce = crypto.randomBytes(8).toString('hex')
   await helper(ssh, runtime, 'upload-token', [ownershipId, spawnNonce], token)
@@ -405,7 +397,7 @@ async function connectWindowsRemote(deps) {
     await forward(localPort, remotePort)
     const baseUrl = `http://127.0.0.1:${localPort}`
     await waitForHermes(baseUrl, token)
-    assertCurrent(signal)
+    assertBootstrapNotSuperseded(signal)
     await helper(ssh, runtime, 'write-lock', [ownershipId], JSON.stringify({ ...owned, port: remotePort }))
 
     return {
diff --git a/apps/desktop/tsconfig.electron.json b/apps/desktop/tsconfig.electron.json
index 6b331453fb..058f132dea 100644
--- a/apps/desktop/tsconfig.electron.json
+++ b/apps/desktop/tsconfig.electron.json
@@ -16,6 +16,6 @@
     "rootDir": "..",
     "outDir": "build/electron-types"
   },
-  "include": ["electron", "../shared/src/translucency.ts"],
+  "include": ["electron", "../shared/src/data-url-read-max.ts", "../shared/src/translucency.ts"],
   "exclude": ["src", "electron/**/*.e2e.mts"]
 }

From 8a918bdc6483f386fa248f83f81785410c389901 Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 19 Aug 2026 02:10:05 -0500
Subject: [PATCH 13/48] feat(desktop): scope the translucency controls to what
 each OS can do
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The row offered one unlabelled 0-100 slider whose meaning changed with the
mode. Under Clear it is window opacity; under Glass it was never opacity at
all — it sets how much of the theme tint stays painted over the material.
Same track, same percent readout, two different things.

Glass now gets a labelled panel: Tint keeps the renderer lever, Fade is a
real native opacity on the ramp Clear uses, defaulting to 0 because fading
a glass window fades its text — the thing Glass exists to avoid. Frost
offers only the rungs the OS renders distinctly, so Windows shows three
instead of two buttons that composite identically; a frost saved on a Mac
highlights the button that renders the same backdrop rather than leaving
the picker blank, and is not rewritten.

Linux loses the row entirely, from the page and from settings search.
setOpacity is a documented no-op there and there is no material, so both
halves were dead — a lever that moved a number and changed nothing.
---
 .../src/app/settings/appearance-settings.tsx  | 237 +++++++++++-------
 .../src/app/settings/use-settings-search.ts   |  25 +-
 2 files changed, 167 insertions(+), 95 deletions(-)

diff --git a/apps/desktop/src/app/settings/appearance-settings.tsx b/apps/desktop/src/app/settings/appearance-settings.tsx
index b84debd606..602da2cd66 100644
--- a/apps/desktop/src/app/settings/appearance-settings.tsx
+++ b/apps/desktop/src/app/settings/appearance-settings.tsx
@@ -24,18 +24,22 @@ import {
   $translucency,
   beginTranslucencyPeek,
   endTranslucencyPeek,
-  GLASS_MATERIALS,
+  GLASS_IS_WINDOWS,
   GLASS_SCOPES,
   GLASS_SUPPORTED,
+  glassMaterialForPicker,
+  glassMaterialsFor,
   pulseTranslucencyPeek,
   resetTranslucencyPeek,
   setTranslucency,
+  setTranslucencyFade,
   setTranslucencyMaterial,
   setTranslucencyMode,
   setTranslucencyScope,
   TRANSLUCENCY_MAX,
   TRANSLUCENCY_MIN,
-  TRANSLUCENCY_STEP
+  TRANSLUCENCY_STEP,
+  TRANSLUCENCY_SUPPORTED
 } from '@/store/translucency'
 import { $zoomPercent, setZoomPercent } from '@/store/zoom'
 import { getBaseColors, useTheme } from '@/themes/context'
@@ -280,6 +284,71 @@ const SLIDER_STEP_KEYS = new Set([
   'PageUp'
 ])
 
+interface TranslucencySliderProps {
+  label: string
+  onChange: (value: number) => void
+  value: number
+}
+
+/**
+ * One 0–100 lever, used up to twice: Clear's window opacity, and under Glass
+ * the tint plus an optional native fade.
+ *
+ * Peek while the hand is on it — the overlay (scrim + near-opaque card) ghosts
+ * so the window behind IS the live preview. The pointer pair covers
+ * mouse/touch drags; the keyboard path pulses per step instead, and blur ends
+ * any residual hold.
+ */
+function TranslucencySlider({ label, onChange, value }: TranslucencySliderProps) {
+  return (
+    <>
+      <input
+        aria-label={label}
+        className="h-1 w-40 cursor-pointer appearance-none rounded-full bg-(--ui-stroke-tertiary)"
+        max={TRANSLUCENCY_MAX}
+        min={TRANSLUCENCY_MIN}
+        onBlur={endTranslucencyPeek}
+        onChange={event => {
+          triggerHaptic('selection')
+          onChange(Number(event.target.value))
+        }}
+        onKeyDown={event => {
+          if (SLIDER_STEP_KEYS.has(event.key)) {
+            pulseTranslucencyPeek()
+          }
+        }}
+        onLostPointerCapture={endTranslucencyPeek}
+        onPointerDown={beginTranslucencyPeek}
+        onPointerUp={endTranslucencyPeek}
+        step={TRANSLUCENCY_STEP}
+        style={{ accentColor: 'var(--dt-primary)' }}
+        type="range"
+        value={value}
+      />
+      <span className="w-9 text-right text-[length:var(--conversation-caption-font-size)] tabular-nums text-(--ui-text-tertiary)">
+        {value}%
+      </span>
+    </>
+  )
+}
+
+interface GlassRowProps {
+  children: React.ReactNode
+  label: string
+}
+
+/** A labelled control in the Glass sub-panel: tint, fade, frost, area. */
+function GlassRow({ children, label }: GlassRowProps) {
+  return (
+    <div className="flex items-center gap-3">
+      <span className="w-12 text-[length:var(--conversation-caption-font-size)] text-(--ui-text-tertiary)">
+        {label}
+      </span>
+      {children}
+    </div>
+  )
+}
+
 export function AppearanceSettings() {
   const { t, isSavingLocale } = useI18n()
   const { themeName, mode, resolvedMode, availableThemes, setTheme, setMode } = useTheme()
@@ -291,6 +360,7 @@ export function AppearanceSettings() {
   const embedAllowed = useStore($embedAllowed)
   const composerPopoutGesturesEnabled = useStore($composerPopoutGesturesEnabled)
   const translucency = useStore($translucency)
+  const glassMode = translucency.mode === 'glass' && GLASS_SUPPORTED
   const reactionsEnabled = useStore($reactionsEnabled)
   const backdrop = useStore($backdrop)
   const installs = useStore($marketplaceInstalls)
@@ -522,94 +592,89 @@ export function AppearanceSettings() {
             title={a.sessionDensityTitle}
           />
 
-          <ListRow
-            action={
-              <div
-                className="flex items-center gap-3"
-                // Arms the peek for the overlay this row lives in — the
-                // ghosting rules in styles.css scope to it, so no other
-                // overlay pays for an opacity transition it never uses.
-                data-translucency-peek-scope=""
-              >
-                {GLASS_SUPPORTED && (
-                  <SegmentedControl
-                    onChange={pickTranslucency(setTranslucencyMode)}
-                    options={[
-                      { id: 'clear' as const, label: a.translucencyModeClear },
-                      { id: 'glass' as const, label: a.translucencyModeGlass }
-                    ]}
-                    value={translucency.mode}
-                  />
-                )}
-                <input
-                  aria-label={a.translucencyTitle}
-                  className="h-1 w-40 cursor-pointer appearance-none rounded-full bg-(--ui-stroke-tertiary)"
-                  max={TRANSLUCENCY_MAX}
-                  min={TRANSLUCENCY_MIN}
-                  // Peek while the hand is on the slider: the overlay (scrim +
-                  // near-opaque card) ghosts so the window behind IS the live
-                  // preview. Pointer pair covers mouse/touch drags; the
-                  // keyboard path pulses per step instead (blur ends any
-                  // residual hold).
-                  onBlur={endTranslucencyPeek}
-                  onChange={event => {
-                    triggerHaptic('selection')
-                    setTranslucency(Number(event.target.value))
-                  }}
-                  onKeyDown={event => {
-                    if (SLIDER_STEP_KEYS.has(event.key)) {
-                      pulseTranslucencyPeek()
-                    }
-                  }}
-                  onLostPointerCapture={endTranslucencyPeek}
-                  onPointerDown={beginTranslucencyPeek}
-                  onPointerUp={endTranslucencyPeek}
-                  step={TRANSLUCENCY_STEP}
-                  style={{ accentColor: 'var(--dt-primary)' }}
-                  type="range"
-                  value={translucency.intensity}
-                />
-                <span className="w-9 text-right text-[length:var(--conversation-caption-font-size)] tabular-nums text-(--ui-text-tertiary)">
-                  {translucency.intensity}%
-                </span>
-              </div>
-            }
-            below={
-              translucency.mode === 'glass' && GLASS_SUPPORTED ? (
-                <div className="mt-3 flex flex-col gap-2.5">
-                  <div className="flex items-center gap-3">
-                    <span className="w-12 text-[length:var(--conversation-caption-font-size)] text-(--ui-text-tertiary)">
-                      {a.translucencyFrostTitle}
-                    </span>
+          {/* Linux has neither half of this setting (see TRANSLUCENCY_SUPPORTED),
+              so the row is absent there rather than offering a dead lever. */}
+          {TRANSLUCENCY_SUPPORTED && (
+            <ListRow
+              action={
+                <div
+                  className="flex items-center gap-3"
+                  // Arms the peek for the overlay this row lives in — the
+                  // ghosting rules in styles.css scope to it, so no other
+                  // overlay pays for an opacity transition it never uses.
+                  data-translucency-peek-scope=""
+                >
+                  {GLASS_SUPPORTED && (
                     <SegmentedControl
-                      onChange={pickTranslucency(setTranslucencyMaterial)}
-                      options={GLASS_MATERIALS.map(material => ({
-                        id: material,
-                        label: a.translucencyFrost[material]
-                      }))}
-                      value={translucency.material}
+                      onChange={pickTranslucency(setTranslucencyMode)}
+                      options={[
+                        { id: 'clear' as const, label: a.translucencyModeClear },
+                        { id: 'glass' as const, label: a.translucencyModeGlass }
+                      ]}
+                      value={translucency.mode}
                     />
-                  </div>
-                  <div className="flex items-center gap-3">
-                    <span className="w-12 text-[length:var(--conversation-caption-font-size)] text-(--ui-text-tertiary)">
-                      {a.translucencyScopeTitle}
-                    </span>
-                    <SegmentedControl
-                      onChange={pickTranslucency(setTranslucencyScope)}
-                      options={GLASS_SCOPES.map(scope => ({
-                        id: scope,
-                        label: a.translucencyScope[scope]
-                      }))}
-                      value={translucency.scope}
+                  )}
+                  {/* Clear has one lever and it belongs beside the mode. Glass
+                      has four controls, so they move into the labelled panel
+                      below rather than crowding this line with an unlabelled
+                      slider that means something different. */}
+                  {!glassMode && (
+                    <TranslucencySlider
+                      label={a.translucencyTitle}
+                      onChange={setTranslucency}
+                      value={translucency.intensity}
                     />
-                  </div>
+                  )}
                 </div>
-              ) : undefined
-            }
-            description={translucency.mode === 'glass' ? a.translucencyGlassDesc : a.translucencyDesc}
-            id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.translucency)}
-            title={a.translucencyTitle}
-          />
+              }
+              below={
+                glassMode ? (
+                  <div className="mt-3 flex flex-col gap-2.5" data-translucency-peek-scope="">
+                    <GlassRow label={a.translucencyTintTitle}>
+                      <TranslucencySlider
+                        label={a.translucencyTintTitle}
+                        onChange={setTranslucency}
+                        value={translucency.intensity}
+                      />
+                    </GlassRow>
+                    <GlassRow label={a.translucencyFadeTitle}>
+                      <TranslucencySlider
+                        label={a.translucencyFadeTitle}
+                        onChange={setTranslucencyFade}
+                        value={translucency.fade}
+                      />
+                    </GlassRow>
+                    <GlassRow label={a.translucencyFrostTitle}>
+                      <SegmentedControl
+                        onChange={pickTranslucency(setTranslucencyMaterial)}
+                        // Windows renders four rungs as three backdrops, so it
+                        // is offered three; a frost saved on a Mac highlights
+                        // the rung that renders the same backdrop here.
+                        options={glassMaterialsFor(GLASS_IS_WINDOWS).map(material => ({
+                          id: material,
+                          label: a.translucencyFrost[material]
+                        }))}
+                        value={glassMaterialForPicker(translucency.material, GLASS_IS_WINDOWS)}
+                      />
+                    </GlassRow>
+                    <GlassRow label={a.translucencyScopeTitle}>
+                      <SegmentedControl
+                        onChange={pickTranslucency(setTranslucencyScope)}
+                        options={GLASS_SCOPES.map(scope => ({
+                          id: scope,
+                          label: a.translucencyScope[scope]
+                        }))}
+                        value={translucency.scope}
+                      />
+                    </GlassRow>
+                  </div>
+                ) : undefined
+              }
+              description={glassMode ? a.translucencyGlassDesc : a.translucencyDesc}
+              id={appearanceSettingElementId(APPEARANCE_SETTING_IDS.translucency)}
+              title={a.translucencyTitle}
+            />
+          )}
 
           <ListRow
             action={
diff --git a/apps/desktop/src/app/settings/use-settings-search.ts b/apps/desktop/src/app/settings/use-settings-search.ts
index 20d9b44173..74171dedac 100644
--- a/apps/desktop/src/app/settings/use-settings-search.ts
+++ b/apps/desktop/src/app/settings/use-settings-search.ts
@@ -9,6 +9,7 @@ import { useI18n } from '@/i18n'
 import { Package, Palette, Settings2, Wrench } from '@/lib/icons'
 import { $agentPlugins, isDesktopRelevantPlugin, loadAgentPlugins } from '@/store/agent-plugins'
 import { $gatewayState } from '@/store/session'
+import { TRANSLUCENCY_SUPPORTED } from '@/store/translucency'
 
 import { useHermesConfigRecord } from '../hooks/use-config-record'
 import { useOnProfileSwitch } from '../hooks/use-on-profile-switch'
@@ -135,15 +136,21 @@ export function useSettingsSearchCatalog(enabled: boolean) {
       label: appearance.uiScaleTitle,
       target: { setting: APPEARANCE_SETTING_IDS.uiScale, view: 'config:appearance' }
     },
-    {
-      context: appearanceContext,
-      description: appearance.translucencyDesc,
-      icon: Palette,
-      id: `setting:${APPEARANCE_SETTING_IDS.translucency}`,
-      keywords: ['opacity', 'transparent'],
-      label: appearance.translucencyTitle,
-      target: { setting: APPEARANCE_SETTING_IDS.translucency, view: 'config:appearance' }
-    },
+    // Linux has no translucency row to land on, and a palette hit that scrolls
+    // to nothing is worse than no hit.
+    ...(TRANSLUCENCY_SUPPORTED
+      ? [
+          {
+            context: appearanceContext,
+            description: appearance.translucencyDesc,
+            icon: Palette,
+            id: `setting:${APPEARANCE_SETTING_IDS.translucency}`,
+            keywords: ['opacity', 'transparent'],
+            label: appearance.translucencyTitle,
+            target: { setting: APPEARANCE_SETTING_IDS.translucency, view: 'config:appearance' as const }
+          }
+        ]
+      : []),
     {
       context: appearanceContext,
       description: appearance.backdropDesc,

From 5a027a0081ec1e5cd40950383a5bde9a34b0f7ae Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 19 Aug 2026 03:34:50 -0500
Subject: [PATCH 14/48] refactor(desktop): give duplicated helpers one owner
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Splitting the god files made a pile of copy-paste helpers visible and,
for the first time, fixable — sharing them previously meant importing a
god file. Hashing function bodies through the TypeScript AST found
twelve groups desktop-wide; production code is now at zero duplicates.

Each helper went to the module that already owns its concern:
firstStringField to lib/text, the two REST 404 predicates to
lib/gateway-rpc beside isMissingRpcMethod, useDebounced and
prefersReducedMotion to their hooks, the superseded-bootstrap guard to
electron/ssh-connection, the composer keyup handler to the trigger hook
that owns the rest of that state machine, and clampDataUrlReadMaxMb to
apps/shared, replacing a "keep these in sync" comment between two
copies.

Only helpers with no existing owner got a new file: lib/mcp-servers,
lib/audio-context, lib/keyed-timeouts, lib/pointer-drag, and the command
palette's status row. Error-shape predicates are the worst thing to
copy — when the backend changes how it reports a missing route, every
copy has to be found.
---
 .../composer/hooks/use-composer-trigger.ts    | 20 ++++++++++
 apps/desktop/src/app/chat/composer/index.tsx  | 18 +--------
 .../marketplace-theme-page.tsx                | 36 +++---------------
 .../app/command-palette/pet-palette-page.tsx  | 23 +++---------
 .../src/app/command-palette/status-row.tsx    | 18 +++++++++
 .../contrib/mcp-install-deeplink-dialog.tsx   |  9 +----
 .../src/app/settings/appearance-settings.tsx  | 13 +------
 apps/desktop/src/app/skills/mcp-tab.tsx       | 25 +------------
 .../thread/user-edit-composer.tsx             | 18 +--------
 .../assistant-ui/tool/delegate-model.ts       |  4 +-
 .../assistant-ui/tool/fallback-model/index.ts | 14 +------
 .../assistant-ui/tool/run-summary.ts          |  3 +-
 .../components/gateway-connecting-overlay.tsx |  5 +--
 .../pane-shell/tree/renderer/edit-bar.tsx     |  9 +----
 .../pane-shell/tree/zone-editor.tsx           | 18 ++-------
 .../desktop/src/components/ui/decode-text.tsx |  5 +--
 apps/desktop/src/hooks/use-media-query.ts     |  4 ++
 apps/desktop/src/lib/audio-context.ts         | 37 +++++++++++++++++++
 apps/desktop/src/lib/completion-sound.ts      | 34 +----------------
 apps/desktop/src/lib/desktop-git.ts           | 17 ---------
 apps/desktop/src/lib/gateway-rpc.ts           | 18 +++++++++
 apps/desktop/src/lib/keyed-timeouts.ts        | 29 +++++++++++++++
 apps/desktop/src/lib/mcp-import.ts            | 17 +--------
 apps/desktop/src/lib/mcp-servers.ts           | 29 +++++++++++++++
 apps/desktop/src/lib/pointer-drag.ts          | 26 +++++++++++++
 apps/desktop/src/lib/text.ts                  | 14 +++++++
 apps/desktop/src/lib/thinking-sound.ts        | 31 +---------------
 apps/desktop/src/lib/wake-sound.ts            | 34 +----------------
 apps/desktop/src/store/data-url-read-max.ts   | 25 +++++--------
 apps/desktop/src/store/goals.ts               | 25 +++----------
 apps/desktop/src/store/pet-gallery.ts         | 13 ++-----
 apps/desktop/src/store/pet-generate.ts        |  9 +----
 apps/desktop/src/store/projects.ts            |  6 +--
 apps/desktop/src/store/todos.ts               | 24 +++---------
 apps/shared/src/data-url-read-max.ts          | 27 ++++++++++++++
 apps/shared/src/index.ts                      |  6 +++
 36 files changed, 296 insertions(+), 367 deletions(-)
 create mode 100644 apps/desktop/src/app/command-palette/status-row.tsx
 create mode 100644 apps/desktop/src/lib/audio-context.ts
 create mode 100644 apps/desktop/src/lib/keyed-timeouts.ts
 create mode 100644 apps/desktop/src/lib/mcp-servers.ts
 create mode 100644 apps/desktop/src/lib/pointer-drag.ts
 create mode 100644 apps/shared/src/data-url-read-max.ts

diff --git a/apps/desktop/src/app/chat/composer/hooks/use-composer-trigger.ts b/apps/desktop/src/app/chat/composer/hooks/use-composer-trigger.ts
index fae1d03a31..a6c5c898af 100644
--- a/apps/desktop/src/app/chat/composer/hooks/use-composer-trigger.ts
+++ b/apps/desktop/src/app/chat/composer/hooks/use-composer-trigger.ts
@@ -36,6 +36,26 @@ import { detectTrigger, textBeforeCaret, type TriggerState } from '../text-utils
  * prose off and stranded a partial `folder:` in front of the chip, because the
  * window it removed wasn't the token the user was typing.
  */
+/** The keyup half of trigger detection, shared by both composers.
+ *
+ *  If the open popover already consumed this key in keydown (Arrow/Enter/Tab/
+ *  Escape), skip the refresh: those keys never edit text, and for Escape the
+ *  keydown already closed the menu — refreshing here would re-detect the
+ *  still-present `/` and instantly reopen it. It reads a ref set during keydown
+ *  rather than `trigger`, because by keyup time React has re-rendered and
+ *  `trigger` may already be null. */
+export function triggerKeyUpHandler(consumedRef: MutableRefObject<boolean>, refreshTrigger: () => void) {
+  return () => {
+    if (consumedRef.current) {
+      consumedRef.current = false
+
+      return
+    }
+
+    window.setTimeout(refreshTrigger, 0)
+  }
+}
+
 export function rebuildAroundCaret(editor: HTMLDivElement, tokenLength: number, insert: DocumentFragment | string) {
   const current = composerPlainText(editor)
   const caret = caretOffsetInEditor(editor)
diff --git a/apps/desktop/src/app/chat/composer/index.tsx b/apps/desktop/src/app/chat/composer/index.tsx
index c61f81f1fc..519e6422eb 100644
--- a/apps/desktop/src/app/chat/composer/index.tsx
+++ b/apps/desktop/src/app/chat/composer/index.tsx
@@ -50,7 +50,7 @@ import { useComposerPlaceholder } from './hooks/use-composer-placeholder'
 import { useComposerPopout } from './hooks/use-composer-popout'
 import { useComposerQueue } from './hooks/use-composer-queue'
 import { useComposerSubmit } from './hooks/use-composer-submit'
-import { useComposerTrigger } from './hooks/use-composer-trigger'
+import { triggerKeyUpHandler, useComposerTrigger } from './hooks/use-composer-trigger'
 import { useComposerUndo } from './hooks/use-composer-undo'
 import { useComposerUrlDialog } from './hooks/use-composer-url-dialog'
 import { useComposerVoice } from './hooks/use-composer-voice'
@@ -904,21 +904,7 @@ export function ChatBar({
     }
   }
 
-  const handleEditorKeyUp = () => {
-    // If this keyup belongs to a key the open trigger popover already consumed
-    // in keydown (Arrow/Enter/Tab/Escape), skip the refresh. Those keys never
-    // edit text, and for Escape the keydown already closed the menu — a refresh
-    // here would re-detect the still-present `/` and instantly reopen it. We
-    // read a ref set during keydown rather than `trigger`, because by keyup
-    // time React has re-rendered and `trigger` may already be null.
-    if (triggerKeyConsumedRef.current) {
-      triggerKeyConsumedRef.current = false
-
-      return
-    }
-
-    window.setTimeout(refreshTrigger, 0)
-  }
+  const handleEditorKeyUp = triggerKeyUpHandler(triggerKeyConsumedRef, refreshTrigger)
 
   const {
     dragActive,
diff --git a/apps/desktop/src/app/command-palette/marketplace-theme-page.tsx b/apps/desktop/src/app/command-palette/marketplace-theme-page.tsx
index 6766b2dae3..1adab907f3 100644
--- a/apps/desktop/src/app/command-palette/marketplace-theme-page.tsx
+++ b/apps/desktop/src/app/command-palette/marketplace-theme-page.tsx
@@ -10,9 +10,11 @@
 
 import { useStore } from '@nanostores/react'
 import { useQuery } from '@tanstack/react-query'
-import { useEffect, useState } from 'react'
+import { useState } from 'react'
 
+import { StatusRow } from '@/app/command-palette/status-row'
 import { HUD_ITEM, HUD_TEXT } from '@/app/floating-hud'
+import { useDebounced } from '@/app/hooks/use-debounced'
 import type { DesktopMarketplaceSearchItem } from '@/global'
 import { useI18n } from '@/i18n'
 import { triggerHaptic } from '@/lib/haptics'
@@ -23,18 +25,6 @@ import { $marketplaceInstalls } from '@/themes/user-themes'
 
 const compactNumber = new Intl.NumberFormat(undefined, { notation: 'compact', maximumFractionDigits: 1 })
 
-function useDebounced<T>(value: T, delayMs: number): T {
-  const [debounced, setDebounced] = useState(value)
-
-  useEffect(() => {
-    const handle = setTimeout(() => setDebounced(value), delayMs)
-
-    return () => clearTimeout(handle)
-  }, [value, delayMs])
-
-  return debounced
-}
-
 interface MarketplaceThemePageProps {
   search: string
   /** Activate a freshly installed theme by slug. */
@@ -90,17 +80,17 @@ export function MarketplaceThemePage({ search, onPickTheme }: MarketplaceThemePa
   }
 
   if (query.isLoading) {
-    return <Status icon={<Loader2 className="size-3.5 animate-spin" />} text={copy.loading} />
+    return <StatusRow icon={<Loader2 className="size-3.5 animate-spin" />} text={copy.loading} />
   }
 
   if (query.isError) {
-    return <Status text={copy.error} tone="error" />
+    return <StatusRow text={copy.error} tone="error" />
   }
 
   const results = query.data ?? []
 
   if (results.length === 0) {
-    return <Status text={copy.empty} />
+    return <StatusRow text={copy.empty} />
   }
 
   return (
@@ -156,17 +146,3 @@ export function MarketplaceThemePage({ search, onPickTheme }: MarketplaceThemePa
     </div>
   )
 }
-
-function Status({ icon, text, tone }: { icon?: React.ReactNode; text: string; tone?: 'error' }) {
-  return (
-    <div
-      className={cn(
-        'flex items-center justify-center gap-2 px-2 py-6 text-xs',
-        tone === 'error' ? 'text-(--ui-red)' : 'text-muted-foreground'
-      )}
-    >
-      {icon}
-      {text}
-    </div>
-  )
-}
diff --git a/apps/desktop/src/app/command-palette/pet-palette-page.tsx b/apps/desktop/src/app/command-palette/pet-palette-page.tsx
index 241bb43312..b23157f5d4 100644
--- a/apps/desktop/src/app/command-palette/pet-palette-page.tsx
+++ b/apps/desktop/src/app/command-palette/pet-palette-page.tsx
@@ -10,6 +10,7 @@
 import { useStore } from '@nanostores/react'
 import { useEffect, useMemo } from 'react'
 
+import { StatusRow } from '@/app/command-palette/status-row'
 import { HUD_ITEM, HUD_TEXT } from '@/app/floating-hud'
 import { useGatewayRequest } from '@/app/gateway/hooks/use-gateway-request'
 import { PetThumb } from '@/components/pet/pet-thumb'
@@ -59,15 +60,15 @@ export function PetPalettePage({ search, onGenerate }: PetPalettePageProps) {
   }
 
   if (status === 'loading' && !gallery) {
-    return <Status icon={<Loader2 className="size-3.5 animate-spin" />} text={copy.loading} />
+    return <StatusRow icon={<Loader2 className="size-3.5 animate-spin" />} text={copy.loading} />
   }
 
   if (status === 'stale') {
-    return <Status text={copy.staleBackend} tone="error" />
+    return <StatusRow text={copy.staleBackend} tone="error" />
   }
 
   if (!gallery?.pets.length && error) {
-    return <Status text={error} tone="error" />
+    return <StatusRow text={error} tone="error" />
   }
 
   const mutating = Boolean(busy)
@@ -95,7 +96,7 @@ export function PetPalettePage({ search, onGenerate }: PetPalettePageProps) {
       {error && <p className="px-2 pb-1 pt-1.5 text-[0.6875rem] text-(--ui-red)">{error}</p>}
 
       {shown.length === 0 ? (
-        <Status text={copy.empty} />
+        <StatusRow text={copy.empty} />
       ) : (
         shown.map(pet => {
           const isActive = enabled && pet.slug === active
@@ -198,17 +199,3 @@ export function PetInlineToggle() {
     </button>
   )
 }
-
-function Status({ icon, text, tone }: { icon?: React.ReactNode; text: string; tone?: 'error' }) {
-  return (
-    <div
-      className={cn(
-        'flex items-center justify-center gap-2 px-2 py-6 text-xs',
-        tone === 'error' ? 'text-(--ui-red)' : 'text-muted-foreground'
-      )}
-    >
-      {icon}
-      {text}
-    </div>
-  )
-}
diff --git a/apps/desktop/src/app/command-palette/status-row.tsx b/apps/desktop/src/app/command-palette/status-row.tsx
new file mode 100644
index 0000000000..2fad2de52f
--- /dev/null
+++ b/apps/desktop/src/app/command-palette/status-row.tsx
@@ -0,0 +1,18 @@
+import type React from 'react'
+
+import { cn } from '@/lib/utils'
+
+/** Centered loading / empty / error row for a Cmd-K page's result list. */
+export function StatusRow({ icon, text, tone }: { icon?: React.ReactNode; text: string; tone?: 'error' }) {
+  return (
+    <div
+      className={cn(
+        'flex items-center justify-center gap-2 px-2 py-6 text-xs',
+        tone === 'error' ? 'text-(--ui-red)' : 'text-muted-foreground'
+      )}
+    >
+      {icon}
+      {text}
+    </div>
+  )
+}
diff --git a/apps/desktop/src/app/contrib/mcp-install-deeplink-dialog.tsx b/apps/desktop/src/app/contrib/mcp-install-deeplink-dialog.tsx
index aa4b1b3cab..a657c98687 100644
--- a/apps/desktop/src/app/contrib/mcp-install-deeplink-dialog.tsx
+++ b/apps/desktop/src/app/contrib/mcp-install-deeplink-dialog.tsx
@@ -16,19 +16,12 @@ import { getHermesConfigRecord, saveMcpServers } from '@/hermes'
 import { useI18n } from '@/i18n'
 import { AlertTriangle } from '@/lib/icons'
 import { MCP_DEEPLINK_NAME_RE } from '@/lib/mcp-deeplink'
+import { getServers } from '@/lib/mcp-servers'
 import { $mcpInstallRequest } from '@/store/mcp-deeplink-install'
 import { notify, readableError } from '@/store/notifications'
 
 import { setHermesConfigCache } from '../hooks/use-config-record'
 
-type McpServers = Record<string, Record<string, unknown>>
-
-const getServers = (config: { mcp_servers?: unknown } | null): McpServers => {
-  const raw = config?.mcp_servers
-
-  return raw && typeof raw === 'object' && !Array.isArray(raw) ? (raw as McpServers) : {}
-}
-
 /**
  * Explicit-confirm gate for `hermes://mcp/install` deep links. The payload is
  * arbitrary attacker-controllable input (any web page can open the link), so
diff --git a/apps/desktop/src/app/settings/appearance-settings.tsx b/apps/desktop/src/app/settings/appearance-settings.tsx
index b84debd606..c401bea383 100644
--- a/apps/desktop/src/app/settings/appearance-settings.tsx
+++ b/apps/desktop/src/app/settings/appearance-settings.tsx
@@ -2,6 +2,7 @@ import { useStore } from '@nanostores/react'
 import { useQuery } from '@tanstack/react-query'
 import { useEffect, useState } from 'react'
 
+import { useDebounced } from '@/app/hooks/use-debounced'
 import { LanguageSwitcher } from '@/components/language-switcher'
 import { Button } from '@/components/ui/button'
 import { SegmentedControl } from '@/components/ui/segmented-control'
@@ -102,18 +103,6 @@ function matchUiScalePreset(percent: number): UiScalePreset | null {
   return UI_SCALE_PRESETS.find(preset => Number(preset) === percent) ?? null
 }
 
-function useDebounced<T>(value: T, delayMs: number): T {
-  const [debounced, setDebounced] = useState(value)
-
-  useEffect(() => {
-    const handle = setTimeout(() => setDebounced(value), delayMs)
-
-    return () => clearTimeout(handle)
-  }, [value, delayMs])
-
-  return debounced
-}
-
 const compactNumber = new Intl.NumberFormat(undefined, { notation: 'compact', maximumFractionDigits: 1 })
 
 /**
diff --git a/apps/desktop/src/app/skills/mcp-tab.tsx b/apps/desktop/src/app/skills/mcp-tab.tsx
index 78b5d74937..93088c6258 100644
--- a/apps/desktop/src/app/skills/mcp-tab.tsx
+++ b/apps/desktop/src/app/skills/mcp-tab.tsx
@@ -38,12 +38,12 @@ import { estimateServerTokens, serverUsageCount } from '@/lib/mcp-cost'
 import { completeMcpDesktopOAuth } from '@/lib/mcp-dashboard-oauth'
 import { type McpImportEntry, parseMcpImport } from '@/lib/mcp-import'
 import { NEEDS_AUTH_RE, PROBE_TTL_MS, probeCache, probeKey, serverFingerprint } from '@/lib/mcp-probe-cache'
+import { getServers, isServerShape, type McpServers, normalizeEntry } from '@/lib/mcp-servers'
 import { countEnabledTools, isToolEnabled, toggleToolInServer } from '@/lib/mcp-tool-filter'
 import { cn } from '@/lib/utils'
 import { notify, notifyError } from '@/store/notifications'
 import { $activeGatewayProfile, normalizeProfileKey } from '@/store/profile'
 import { $activeSessionId } from '@/store/session'
-import type { HermesConfigRecord } from '@/types/hermes'
 
 import { hermesConfigCacheWriter, useHermesConfigRecord } from '../hooks/use-config-record'
 import { useOnProfileSwitch } from '../hooks/use-on-profile-switch'
@@ -52,8 +52,6 @@ import { PanelAddButton, PanelEmpty } from '../overlays/panel'
 import { prettyName } from '../settings/helpers'
 import { useDeepLinkHighlight } from '../settings/use-deep-link-highlight'
 
-type McpServers = Record<string, Record<string, unknown>>
-
 // The editor always speaks the ecosystem's mcp.json document format — names
 // are the JSON keys, transport is inferred from `command` vs `url` — so any
 // README's "add this to your mcp.json" snippet pastes verbatim. Storage stays
@@ -63,21 +61,6 @@ const STARTER_ENTRY = { command: 'npx', args: ['-y', '@modelcontextprotocol/serv
 const pretty = (value: unknown) => JSON.stringify(value, null, 2)
 const wrapDoc = (entries: McpServers) => pretty({ mcpServers: entries })
 
-const isServerShape = (value: Record<string, unknown>) =>
-  typeof value.command === 'string' || typeof value.url === 'string'
-
-// Cursor/Claude write `type`; Hermes reads `transport`. Normalize on the way
-// in so pasted configs behave identically under the CLI/TUI loader.
-function normalizeEntry(entry: Record<string, unknown>): Record<string, unknown> {
-  if (typeof entry.type === 'string' && entry.transport === undefined) {
-    const { type, ...rest } = entry
-
-    return { ...rest, transport: type }
-  }
-
-  return entry
-}
-
 /** Accepts `{"mcpServers": {...}}` (ecosystem), a bare name→config map, or throws. */
 function parseServersDoc(raw: string): McpServers {
   const parsed = JSON.parse(raw) as unknown
@@ -100,12 +83,6 @@ function parseServersDoc(raw: string): McpServers {
   return Object.fromEntries(Object.entries(map).map(([name, entry]) => [name, normalizeEntry(entry)]))
 }
 
-function getServers(config: HermesConfigRecord | null): McpServers {
-  const raw = config?.mcp_servers
-
-  return raw && typeof raw === 'object' && !Array.isArray(raw) ? (raw as McpServers) : {}
-}
-
 // The runtime gate is `enabled: false` — the same flag `hermes mcp` and the
 // agent's MCP loader read.
 const serverEnabled = (server: Record<string, unknown>) => server.enabled !== false
diff --git a/apps/desktop/src/components/assistant-ui/thread/user-edit-composer.tsx b/apps/desktop/src/components/assistant-ui/thread/user-edit-composer.tsx
index b29715f98b..d9bf458c80 100644
--- a/apps/desktop/src/components/assistant-ui/thread/user-edit-composer.tsx
+++ b/apps/desktop/src/components/assistant-ui/thread/user-edit-composer.tsx
@@ -24,7 +24,7 @@ import {
   releaseActiveComposer
 } from '@/app/chat/composer/focus'
 import { useAtCompletions } from '@/app/chat/composer/hooks/use-at-completions'
-import { rebuildAroundCaret } from '@/app/chat/composer/hooks/use-composer-trigger'
+import { rebuildAroundCaret, triggerKeyUpHandler } from '@/app/chat/composer/hooks/use-composer-trigger'
 import { useComposerUndo } from '@/app/chat/composer/hooks/use-composer-undo'
 import { useEmojiCompletions } from '@/app/chat/composer/hooks/use-emoji-completions'
 import { useSlashCompletions } from '@/app/chat/composer/hooks/use-slash-completions'
@@ -760,21 +760,7 @@ export const UserEditComposer: FC<UserEditComposerProps> = ({ cwd, gateway, sess
     }
   }
 
-  const handleKeyUp = () => {
-    // If this keyup belongs to a key the open trigger popover already consumed
-    // in keydown (Arrow/Enter/Tab/Escape), skip the refresh. Those keys never
-    // edit text, and for Escape the keydown already closed the menu — a refresh
-    // here would re-detect the still-present `/` and instantly reopen it. We
-    // read a ref set during keydown rather than `trigger`, because by keyup
-    // time React has re-rendered and `trigger` may already be null.
-    if (triggerKeyConsumedRef.current) {
-      triggerKeyConsumedRef.current = false
-
-      return
-    }
-
-    window.setTimeout(refreshTrigger, 0)
-  }
+  const handleKeyUp = triggerKeyUpHandler(triggerKeyConsumedRef, refreshTrigger)
 
   return (
     <ComposerPrimitive.Root className="contents" data-slot="aui_edit-composer-root">
diff --git a/apps/desktop/src/components/assistant-ui/tool/delegate-model.ts b/apps/desktop/src/components/assistant-ui/tool/delegate-model.ts
index eff61ec17d..694c34d752 100644
--- a/apps/desktop/src/components/assistant-ui/tool/delegate-model.ts
+++ b/apps/desktop/src/components/assistant-ui/tool/delegate-model.ts
@@ -1,7 +1,7 @@
-import { normalize } from '@/lib/text'
+import { firstStringField, normalize } from '@/lib/text'
 import type { SubagentProgress, SubagentStatus } from '@/store/subagents'
 
-import { firstStringField, numberValue, parseMaybeObject } from './fallback-model'
+import { numberValue, parseMaybeObject } from './fallback-model'
 
 /**
  * A delegation runs somewhere the transcript can't see: the tool call carries
diff --git a/apps/desktop/src/components/assistant-ui/tool/fallback-model/index.ts b/apps/desktop/src/components/assistant-ui/tool/fallback-model/index.ts
index 2a21657f68..4ea420732e 100644
--- a/apps/desktop/src/components/assistant-ui/tool/fallback-model/index.ts
+++ b/apps/desktop/src/components/assistant-ui/tool/fallback-model/index.ts
@@ -1,7 +1,7 @@
 import { type ToolTitleKey, translateNow } from '@/i18n'
 import { normalizeExternalUrl } from '@/lib/external-link'
 import { summarizeShellCommand } from '@/lib/summarize-command'
-import { capitalize, normalize } from '@/lib/text'
+import { capitalize, firstStringField, normalize } from '@/lib/text'
 import { isCardTool, isFileEditTool, isSilentTool } from '@/lib/tool-render-class'
 import { extractToolErrorMessage, formatToolResultSummary } from '@/lib/tool-result-summary'
 
@@ -595,18 +595,6 @@ function summarizeBrowserSnapshot(snapshot: string): string {
   return labels.length ? `${stats}\nTop controls: ${labels.join(', ')}` : stats
 }
 
-export function firstStringField(record: Record<string, unknown>, keys: readonly string[]): string {
-  for (const key of keys) {
-    const value = record[key]
-
-    if (typeof value === 'string' && value.trim()) {
-      return value.trim()
-    }
-  }
-
-  return ''
-}
-
 function collectResultItems(value: unknown): unknown[] {
   if (Array.isArray(value)) {
     return value
diff --git a/apps/desktop/src/components/assistant-ui/tool/run-summary.ts b/apps/desktop/src/components/assistant-ui/tool/run-summary.ts
index 6abf559a33..7693e67ed6 100644
--- a/apps/desktop/src/components/assistant-ui/tool/run-summary.ts
+++ b/apps/desktop/src/components/assistant-ui/tool/run-summary.ts
@@ -1,6 +1,7 @@
 import { summarizeShellCommand } from '@/lib/summarize-command'
+import { firstStringField } from '@/lib/text'
 
-import { fileEditBasename, firstStringField, isFileEditTool, parseMaybeObject } from './fallback-model'
+import { fileEditBasename, isFileEditTool, parseMaybeObject } from './fallback-model'
 
 /**
  * The little a summary needs from a tool call, stated structurally so both
diff --git a/apps/desktop/src/components/gateway-connecting-overlay.tsx b/apps/desktop/src/components/gateway-connecting-overlay.tsx
index 34303bb52c..dcc24c64d8 100644
--- a/apps/desktop/src/components/gateway-connecting-overlay.tsx
+++ b/apps/desktop/src/components/gateway-connecting-overlay.tsx
@@ -2,6 +2,7 @@ import { useStore } from '@nanostores/react'
 import { useEffect, useRef, useState } from 'react'
 
 import { DecodeText } from '@/components/ui/decode-text'
+import { prefersReducedMotion } from '@/hooks/use-media-query'
 import { cn } from '@/lib/utils'
 import { $desktopBoot } from '@/store/boot'
 import { $gatewaySwitching } from '@/store/gateway-switch'
@@ -35,10 +36,6 @@ function forcedPreview(): boolean {
   }
 }
 
-function prefersReducedMotion(): boolean {
-  return typeof window !== 'undefined' && Boolean(window.matchMedia?.('(prefers-reduced-motion: reduce)').matches)
-}
-
 export function GatewayConnectingOverlay() {
   const gatewayState = useStore($gatewayState)
   const boot = useStore($desktopBoot)
diff --git a/apps/desktop/src/components/pane-shell/tree/renderer/edit-bar.tsx b/apps/desktop/src/components/pane-shell/tree/renderer/edit-bar.tsx
index 56e5c66e22..854229c8f8 100644
--- a/apps/desktop/src/components/pane-shell/tree/renderer/edit-bar.tsx
+++ b/apps/desktop/src/components/pane-shell/tree/renderer/edit-bar.tsx
@@ -11,6 +11,7 @@ import { type PointerEvent as ReactPointerEvent, useCallback, useRef, useState }
 import { Button } from '@/components/ui/button'
 import { useI18n } from '@/i18n'
 import { formatCombo } from '@/lib/keybinds/combo'
+import { startPointerDrag } from '@/lib/pointer-drag'
 import { $bindings, bindingsFor } from '@/store/keybinds'
 
 import { $layoutEditMode } from '../../edit-mode'
@@ -61,13 +62,7 @@ export function TreeEditBar() {
       setPos(next)
     }
 
-    const onUp = () => {
-      window.removeEventListener('pointermove', onMove, true)
-      window.removeEventListener('pointerup', onUp, true)
-    }
-
-    window.addEventListener('pointermove', onMove, true)
-    window.addEventListener('pointerup', onUp, true)
+    startPointerDrag(onMove)
   }, [])
 
   if (!editMode) {
diff --git a/apps/desktop/src/components/pane-shell/tree/zone-editor.tsx b/apps/desktop/src/components/pane-shell/tree/zone-editor.tsx
index 74a269463e..fe40ca2c8b 100644
--- a/apps/desktop/src/components/pane-shell/tree/zone-editor.tsx
+++ b/apps/desktop/src/components/pane-shell/tree/zone-editor.tsx
@@ -25,6 +25,7 @@ import { Input } from '@/components/ui/input'
 import { registry } from '@/contrib/registry'
 import { useI18n } from '@/i18n'
 import { ESCAPE_PRIORITY, isTopEscapeLayer, pushEscapeLayer } from '@/lib/escape-layers'
+import { startPointerDrag } from '@/lib/pointer-drag'
 import { cn } from '@/lib/utils'
 
 import {
@@ -214,9 +215,7 @@ export function ZoneEditor() {
       setSelection(mergeClosureIndices(model, picked))
     }
 
-    const onUp = (ev: PointerEvent) => {
-      window.removeEventListener('pointermove', onMove, true)
-      window.removeEventListener('pointerup', onUp, true)
+    startPointerDrag(onMove, ev => {
       setSelectBox(null)
 
       if (!dragged) {
@@ -233,10 +232,7 @@ export function ZoneEditor() {
 
       const rect = canvasRef.current!.getBoundingClientRect()
       setMergeAt({ x: ev.clientX - rect.x, y: ev.clientY - rect.y })
-    }
-
-    window.addEventListener('pointermove', onMove, true)
-    window.addEventListener('pointerup', onUp, true)
+    })
   }
 
   const startResizerDrag = (index: number, e: ReactPointerEvent<HTMLDivElement>) => {
@@ -267,13 +263,7 @@ export function ZoneEditor() {
       }
     }
 
-    const onUp = () => {
-      window.removeEventListener('pointermove', onMove, true)
-      window.removeEventListener('pointerup', onUp, true)
-    }
-
-    window.addEventListener('pointermove', onMove, true)
-    window.addEventListener('pointerup', onUp, true)
+    startPointerDrag(onMove)
   }
 
   const merge = () => {
diff --git a/apps/desktop/src/components/ui/decode-text.tsx b/apps/desktop/src/components/ui/decode-text.tsx
index 243de60f62..edd91641a6 100644
--- a/apps/desktop/src/components/ui/decode-text.tsx
+++ b/apps/desktop/src/components/ui/decode-text.tsx
@@ -1,5 +1,6 @@
 import { type ComponentProps, useEffect, useState } from 'react'
 
+import { prefersReducedMotion } from '@/hooks/use-media-query'
 import { cn } from '@/lib/utils'
 
 /**
@@ -23,10 +24,6 @@ export const DECODE_SCRAMBLE_CHARS = '/\\|-_=+<>~:*'
 const TICK_MS = 45
 const HOLD_TICKS = 16
 
-function prefersReducedMotion(): boolean {
-  return typeof window !== 'undefined' && Boolean(window.matchMedia?.('(prefers-reduced-motion: reduce)').matches)
-}
-
 function scrambled(tail: string, resolvedCount: number): string {
   return Array.from(tail, (ch, i) =>
     ch === ' ' || i < resolvedCount ? ch : DECODE_SCRAMBLE_CHARS[(Math.random() * DECODE_SCRAMBLE_CHARS.length) | 0]
diff --git a/apps/desktop/src/hooks/use-media-query.ts b/apps/desktop/src/hooks/use-media-query.ts
index aa368dfb93..219715811d 100644
--- a/apps/desktop/src/hooks/use-media-query.ts
+++ b/apps/desktop/src/hooks/use-media-query.ts
@@ -3,6 +3,10 @@ import { useEffect, useState } from 'react'
 export const matchesQuery = (query: string) =>
   typeof window !== 'undefined' && !!window.matchMedia && window.matchMedia(query).matches
 
+/** Read at call time, not render time: animations check this as they start, and
+ *  the OS setting can flip mid-session. */
+export const prefersReducedMotion = () => matchesQuery('(prefers-reduced-motion: reduce)')
+
 export function useMediaQuery(query: string): boolean {
   const [matches, setMatches] = useState(() => matchesQuery(query))
 
diff --git a/apps/desktop/src/lib/audio-context.ts b/apps/desktop/src/lib/audio-context.ts
new file mode 100644
index 0000000000..a506399c2d
--- /dev/null
+++ b/apps/desktop/src/lib/audio-context.ts
@@ -0,0 +1,37 @@
+// One lazily-created AudioContext for the app's synthesized UI cues (wake
+// chime, turn-completion sound, thinking blips). Browsers cap how many
+// contexts a page may open, and these cues are short oscillator bursts that
+// need no isolation from each other, so they share one instead of each holding
+// its own. Nothing closes it — it lives for the window.
+
+let ctx: AudioContext | null = null
+
+/** The shared AudioContext, or null where WebAudio is unavailable. */
+export function getAudioContext(): AudioContext | null {
+  if (typeof window === 'undefined') {
+    return null
+  }
+
+  try {
+    if (!ctx) {
+      const Ctor =
+        window.AudioContext || (window as unknown as { webkitAudioContext?: typeof AudioContext }).webkitAudioContext
+
+      if (!Ctor) {
+        return null
+      }
+
+      ctx = new Ctor()
+    }
+
+    // Autoplay policies can leave the context suspended until a gesture; a
+    // resume() here recovers it once the user has interacted with the window.
+    if (ctx.state === 'suspended') {
+      void ctx.resume().catch(() => undefined)
+    }
+
+    return ctx
+  } catch {
+    return null
+  }
+}
diff --git a/apps/desktop/src/lib/completion-sound.ts b/apps/desktop/src/lib/completion-sound.ts
index 1557c58e41..6245c10723 100644
--- a/apps/desktop/src/lib/completion-sound.ts
+++ b/apps/desktop/src/lib/completion-sound.ts
@@ -1,43 +1,13 @@
 // Completion sound bank for agent turn-end cues.
 // Fourteen curated presets for A/B in Settings → Appearance. Default is variant 1.
 
+import { getAudioContext } from '@/lib/audio-context'
 import { ownsAmbientCue } from '@/store/ambient'
 import { $completionSoundVariantId, resolveCompletionSoundVariantId } from '@/store/completion-sound'
 import { $hapticsMuted } from '@/store/haptics'
 
 type OscType = OscillatorType
 
-let ctx: AudioContext | null = null
-
-function getCtx(): AudioContext | null {
-  if (typeof window === 'undefined') {
-    return null
-  }
-
-  try {
-    if (!ctx) {
-      const Ctor =
-        window.AudioContext || (window as unknown as { webkitAudioContext?: typeof AudioContext }).webkitAudioContext
-
-      if (!Ctor) {
-        return null
-      }
-
-      ctx = new Ctor()
-    }
-
-    // Autoplay policies can leave the context suspended until a gesture; a
-    // resume() here recovers it once the user has interacted with the window.
-    if (ctx.state === 'suspended') {
-      void ctx.resume().catch(() => undefined)
-    }
-
-    return ctx
-  } catch {
-    return null
-  }
-}
-
 // One enveloped oscillator voice → master. Linear attack into an exponential
 // decay keeps the tail smooth and avoids the click you get ramping to zero.
 function voice(ac: AudioContext, master: GainNode, t0: number, spec: ToneSpec) {
@@ -417,7 +387,7 @@ function playVariant(variantId: number) {
     return
   }
 
-  const ac = getCtx()
+  const ac = getAudioContext()
 
   if (!ac) {
     return
diff --git a/apps/desktop/src/lib/desktop-git.ts b/apps/desktop/src/lib/desktop-git.ts
index 0009900b72..98f41fbf87 100644
--- a/apps/desktop/src/lib/desktop-git.ts
+++ b/apps/desktop/src/lib/desktop-git.ts
@@ -115,20 +115,3 @@ export function desktopGit(): GitBridge | undefined {
 
   return isDesktopFsRemoteMode() ? remoteGit : window.hermesDesktop?.git
 }
-
-// True only for "the /api/git route does not exist on this backend" shapes:
-// the backend catch-all ('404: {"detail":"No such API endpoint: ...}'), a bare
-// FastAPI 404 (directly or through the IPC bridge's "Error invoking remote
-// method" wrapper), and the Electron JSON-guard ("endpoint is likely
-// missing"). Transient failures (timeouts, 5xx, connection refused) must NOT
-// match — they are retryable, not a capability verdict. Mirrors the sidebar
-// batch-endpoint detector in hermes.ts.
-export function isGitEndpointMissingError(err: unknown): boolean {
-  const message = err instanceof Error ? err.message : String(err)
-
-  return (
-    /no such api endpoint/i.test(message) ||
-    /endpoint is likely missing/i.test(message) ||
-    /(?:^\s*|error:\s*)404\b/i.test(message)
-  )
-}
diff --git a/apps/desktop/src/lib/gateway-rpc.ts b/apps/desktop/src/lib/gateway-rpc.ts
index 372cf0bc49..1b52ef1f33 100644
--- a/apps/desktop/src/lib/gateway-rpc.ts
+++ b/apps/desktop/src/lib/gateway-rpc.ts
@@ -5,6 +5,24 @@ export function isMissingRpcMethod(error: unknown): boolean {
   return /method not found|-32601|unknown method|no such method/i.test(message)
 }
 
+/** REST twin of isMissingRpcMethod: the route does not exist on this backend.
+ *  Matches the backend catch-all ('404: {"detail":"No such API endpoint: …}'),
+ *  FastAPI's bare 404 on headless serve — directly, or wrapped as "Error
+ *  invoking remote method 'hermes:api': Error: 404: …" through the IPC bridge
+ *  — and the Electron JSON-guard ("endpoint is likely missing"). Transient
+ *  failures (timeouts, 5xx, connection refused) must NOT match: they are
+ *  retryable, not a capability verdict. Only sound for calls where a 404 can
+ *  mean nothing else — a route with path params can 404 on a bad id. */
+export function isMissingRestEndpoint(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error)
+
+  return (
+    /no such api endpoint/i.test(message) ||
+    /endpoint is likely missing/i.test(message) ||
+    /(?:^\s*|error:\s*)404\b/i.test(message)
+  )
+}
+
 /** True when a prompt response raced a backend-side timeout / completion. */
 export function isMissingPendingPromptRequest(error: unknown, key: string): boolean {
   const message = error instanceof Error ? error.message : String(error)
diff --git a/apps/desktop/src/lib/keyed-timeouts.ts b/apps/desktop/src/lib/keyed-timeouts.ts
new file mode 100644
index 0000000000..fc3208cb92
--- /dev/null
+++ b/apps/desktop/src/lib/keyed-timeouts.ts
@@ -0,0 +1,29 @@
+/** Per-key setTimeout registry for "let this linger, then drop it" UI state.
+ *  Scheduling a key replaces its pending timer, and an entry removes itself
+ *  when it fires, so the map never accumulates dead keys. */
+export function keyedTimeouts() {
+  const timers = new Map<string, ReturnType<typeof setTimeout>>()
+
+  const cancel = (key: string) => {
+    const timer = timers.get(key)
+
+    if (timer !== undefined) {
+      clearTimeout(timer)
+      timers.delete(key)
+    }
+  }
+
+  return {
+    cancel,
+    schedule(key: string, delayMs: number, run: () => void) {
+      cancel(key)
+      timers.set(
+        key,
+        setTimeout(() => {
+          timers.delete(key)
+          run()
+        }, delayMs)
+      )
+    }
+  }
+}
diff --git a/apps/desktop/src/lib/mcp-import.ts b/apps/desktop/src/lib/mcp-import.ts
index 7b83460b01..7437c375ea 100644
--- a/apps/desktop/src/lib/mcp-import.ts
+++ b/apps/desktop/src/lib/mcp-import.ts
@@ -4,6 +4,8 @@
 // entries. Pure and side-effect free; the MCP tab merges the result into the
 // editor draft. Returns null when nothing recognizable is in the text.
 
+import { isServerShape, normalizeEntry } from '@/lib/mcp-servers'
+
 export interface McpImportEntry {
   config: Record<string, unknown>
   name: string
@@ -12,21 +14,6 @@ export interface McpImportEntry {
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   !!value && typeof value === 'object' && !Array.isArray(value)
 
-const isServerShape = (value: Record<string, unknown>) =>
-  typeof value.command === 'string' || typeof value.url === 'string'
-
-// Cursor/Claude write `type`; Hermes reads `transport` (same normalization the
-// MCP tab applies to pasted JSON).
-function normalizeEntry(entry: Record<string, unknown>): Record<string, unknown> {
-  if (typeof entry.type === 'string' && entry.transport === undefined) {
-    const { type, ...rest } = entry
-
-    return { ...rest, transport: type }
-  }
-
-  return entry
-}
-
 const URL_RE = /^https?:\/\/\S+$/i
 
 // "mcp.linear.app" → "linear": drop generic front labels, keep the brand one.
diff --git a/apps/desktop/src/lib/mcp-servers.ts b/apps/desktop/src/lib/mcp-servers.ts
new file mode 100644
index 0000000000..38bf9046bc
--- /dev/null
+++ b/apps/desktop/src/lib/mcp-servers.ts
@@ -0,0 +1,29 @@
+// Shape helpers for the `mcp_servers` config map, shared by everything that
+// reads or writes it: the MCP tab editor, the paste-anything importer, and the
+// `hermes://mcp/install` deeplink dialog. These agree on what a server entry
+// looks like, so they belong in one place — a config written by one path has to
+// be readable by the others.
+
+export type McpServers = Record<string, Record<string, unknown>>
+
+export const isServerShape = (value: Record<string, unknown>) =>
+  typeof value.command === 'string' || typeof value.url === 'string'
+
+/** Cursor/Claude write `type`; Hermes reads `transport`. Normalizing on the way
+ *  in makes pasted configs behave identically under the CLI/TUI loader. */
+export function normalizeEntry(entry: Record<string, unknown>): Record<string, unknown> {
+  if (typeof entry.type === 'string' && entry.transport === undefined) {
+    const { type, ...rest } = entry
+
+    return { ...rest, transport: type }
+  }
+
+  return entry
+}
+
+/** The `mcp_servers` map out of a config record, or `{}` when absent/malformed. */
+export function getServers(config: { mcp_servers?: unknown } | null): McpServers {
+  const raw = config?.mcp_servers
+
+  return raw && typeof raw === 'object' && !Array.isArray(raw) ? (raw as McpServers) : {}
+}
diff --git a/apps/desktop/src/lib/pointer-drag.ts b/apps/desktop/src/lib/pointer-drag.ts
new file mode 100644
index 0000000000..43ae8aa5a0
--- /dev/null
+++ b/apps/desktop/src/lib/pointer-drag.ts
@@ -0,0 +1,26 @@
+/** Run a pointer drag until pointerup, then unbind both listeners.
+ *
+ *  Capture-phase, on `window`, so the drag keeps tracking when the pointer
+ *  leaves the element it started on. Forgetting one half of the teardown leaks
+ *  a live pointermove handler for the rest of the session, which is why the
+ *  unbinding lives here rather than at each call site. */
+export function startPointerDrag(
+  onMove: (event: PointerEvent) => void,
+  onEnd?: (event: PointerEvent) => void
+): () => void {
+  const move = (event: PointerEvent) => onMove(event)
+
+  const up = (event: PointerEvent) => {
+    window.removeEventListener('pointermove', move, true)
+    window.removeEventListener('pointerup', up, true)
+    onEnd?.(event)
+  }
+
+  window.addEventListener('pointermove', move, true)
+  window.addEventListener('pointerup', up, true)
+
+  return () => {
+    window.removeEventListener('pointermove', move, true)
+    window.removeEventListener('pointerup', up, true)
+  }
+}
diff --git a/apps/desktop/src/lib/text.ts b/apps/desktop/src/lib/text.ts
index 815a5d731d..eecb0cc715 100644
--- a/apps/desktop/src/lib/text.ts
+++ b/apps/desktop/src/lib/text.ts
@@ -13,3 +13,17 @@ export const normalize = (v: unknown): string => asText(v).trim().toLowerCase()
 /** Uppercase the first character, leave the rest. Matches the
  *  `s.charAt(0).toUpperCase() + s.slice(1)` idiom (empty-safe). */
 export const capitalize = (v: string): string => (v ? v.charAt(0).toUpperCase() + v.slice(1) : v)
+
+/** First non-empty string among `keys`, trimmed. For reading tool args and
+ *  results, where the key carrying the interesting value varies by tool. */
+export const firstStringField = (record: Record<string, unknown>, keys: readonly string[]): string => {
+  for (const key of keys) {
+    const value = record[key]
+
+    if (typeof value === 'string' && value.trim()) {
+      return value.trim()
+    }
+  }
+
+  return ''
+}
diff --git a/apps/desktop/src/lib/thinking-sound.ts b/apps/desktop/src/lib/thinking-sound.ts
index 6a4d2bd6da..6d78dc50fe 100644
--- a/apps/desktop/src/lib/thinking-sound.ts
+++ b/apps/desktop/src/lib/thinking-sound.ts
@@ -11,40 +11,13 @@
 // stopThinkingSound() — callers fire it the moment TTS starts, the mic re-arms,
 // or the conversation ends.
 
+import { getAudioContext } from '@/lib/audio-context'
 import { $hapticsMuted } from '@/store/haptics'
 import { $thinkingSoundEnabled } from '@/store/voice-prefs'
 
-let ctx: AudioContext | null = null
 let timer: number | null = null
 let blipIndex = 0
 
-function getCtx(): AudioContext | null {
-  if (typeof window === 'undefined') {
-    return null
-  }
-
-  try {
-    if (!ctx) {
-      const Ctor =
-        window.AudioContext || (window as unknown as { webkitAudioContext?: typeof AudioContext }).webkitAudioContext
-
-      if (!Ctor) {
-        return null
-      }
-
-      ctx = new Ctor()
-    }
-
-    if (ctx.state === 'suspended') {
-      void ctx.resume().catch(() => undefined)
-    }
-
-    return ctx
-  } catch {
-    return null
-  }
-}
-
 // One soft "blub": short sine with a gentle downward pitch glide and a smooth
 // attack into an exponential decay — no clicks, deliberately quiet.
 function blub(ac: AudioContext, freq: number) {
@@ -79,7 +52,7 @@ export function startThinkingSound(): void {
 
   const tick = () => {
     if ($hapticsMuted.get() === false) {
-      const ac = getCtx()
+      const ac = getAudioContext()
 
       if (ac) {
         try {
diff --git a/apps/desktop/src/lib/wake-sound.ts b/apps/desktop/src/lib/wake-sound.ts
index 3eb9f1c0d8..acd61a267c 100644
--- a/apps/desktop/src/lib/wake-sound.ts
+++ b/apps/desktop/src/lib/wake-sound.ts
@@ -5,39 +5,9 @@
 // the completion cue settles (done). Reuses the same lightweight WebAudio
 // synthesis approach — no asset file to ship.
 
+import { getAudioContext } from '@/lib/audio-context'
 import { $hapticsMuted } from '@/store/haptics'
 
-let ctx: AudioContext | null = null
-
-function getCtx(): AudioContext | null {
-  if (typeof window === 'undefined') {
-    return null
-  }
-
-  try {
-    if (!ctx) {
-      const Ctor =
-        window.AudioContext || (window as unknown as { webkitAudioContext?: typeof AudioContext }).webkitAudioContext
-
-      if (!Ctor) {
-        return null
-      }
-
-      ctx = new Ctor()
-    }
-
-    // Autoplay policies can leave the context suspended until a gesture; a
-    // resume() here recovers it once the user has interacted with the window.
-    if (ctx.state === 'suspended') {
-      void ctx.resume().catch(() => undefined)
-    }
-
-    return ctx
-  } catch {
-    return null
-  }
-}
-
 // One enveloped sine voice → master. Linear-ish attack into an exponential
 // decay keeps the tail smooth and avoids the click you get ramping to zero.
 function ding(ac: AudioContext, master: GainNode, t0: number, freq: number, dur: number, gain: number) {
@@ -66,7 +36,7 @@ export function playWakeSound(): void {
     return
   }
 
-  const ac = getCtx()
+  const ac = getAudioContext()
 
   if (!ac) {
     return
diff --git a/apps/desktop/src/store/data-url-read-max.ts b/apps/desktop/src/store/data-url-read-max.ts
index b37556d3fd..e95dfb61af 100644
--- a/apps/desktop/src/store/data-url-read-max.ts
+++ b/apps/desktop/src/store/data-url-read-max.ts
@@ -2,28 +2,21 @@
  * Max size for local files Desktop loads as data URLs (composer attach, image
  * previews, etc.). Main owns the real cap + its JSON under userData — this
  * atom only mirrors it for Settings → Chat. See electron/main.ts
- * (`hermes:data-url-read-max:*`) and the default/clamp in electron/hardening.ts.
+ * (`hermes:data-url-read-max:*`). The default and the clamp are shared with
+ * main via apps/shared so the two ends cannot drift.
  */
 
+import {
+  clampDataUrlReadMaxMb,
+  DATA_URL_READ_DEFAULT_MAX_MB,
+  DATA_URL_READ_MAX_MAX_MB,
+  DATA_URL_READ_MIN_MAX_MB
+} from '@hermes/shared'
 import { atom } from 'nanostores'
 
 import { notifyError } from '@/store/notifications'
 
-/** Ship default; must match DATA_URL_READ_DEFAULT_MAX_MB in hardening.ts. */
-export const DATA_URL_READ_DEFAULT_MAX_MB = 16
-export const DATA_URL_READ_MIN_MAX_MB = 1
-/** Typo / absurd-value guard only — large values can still OOM the app. */
-export const DATA_URL_READ_MAX_MAX_MB = 4096
-
-export function clampDataUrlReadMaxMb(value: unknown): number {
-  const parsed = Number(value)
-
-  if (!Number.isFinite(parsed)) {
-    return DATA_URL_READ_DEFAULT_MAX_MB
-  }
-
-  return Math.min(DATA_URL_READ_MAX_MAX_MB, Math.max(DATA_URL_READ_MIN_MAX_MB, Math.round(parsed)))
-}
+export { clampDataUrlReadMaxMb, DATA_URL_READ_DEFAULT_MAX_MB, DATA_URL_READ_MAX_MAX_MB, DATA_URL_READ_MIN_MAX_MB }
 
 export const $dataUrlReadMaxMb = atom<number>(DATA_URL_READ_DEFAULT_MAX_MB)
 
diff --git a/apps/desktop/src/store/goals.ts b/apps/desktop/src/store/goals.ts
index 3b19b7eb63..eab0188d66 100644
--- a/apps/desktop/src/store/goals.ts
+++ b/apps/desktop/src/store/goals.ts
@@ -1,5 +1,7 @@
 import { atom } from 'nanostores'
 
+import { keyedTimeouts } from '@/lib/keyed-timeouts'
+
 import { $gateway } from './gateway'
 
 export type GoalStatus = 'active' | 'done' | 'paused' | 'waiting'
@@ -14,38 +16,23 @@ export interface SessionGoal {
 export const $goalsBySession = atom<Record<string, SessionGoal>>({})
 
 const DONE_LINGER_MS = 8_000
-const clearTimers = new Map<string, ReturnType<typeof setTimeout>>()
-
-function cancelScheduledClear(sid: string) {
-  const timer = clearTimers.get(sid)
-
-  if (timer !== undefined) {
-    clearTimeout(timer)
-    clearTimers.delete(sid)
-  }
-}
+const clearTimers = keyedTimeouts()
 
 export function setSessionGoal(sid: string, goal: SessionGoal) {
   if (!sid) {
     return
   }
 
-  cancelScheduledClear(sid)
+  clearTimers.cancel(sid)
   $goalsBySession.set({ ...$goalsBySession.get(), [sid]: goal })
 
   if (goal.status === 'done') {
-    clearTimers.set(
-      sid,
-      setTimeout(() => {
-        clearTimers.delete(sid)
-        clearSessionGoal(sid)
-      }, DONE_LINGER_MS)
-    )
+    clearTimers.schedule(sid, DONE_LINGER_MS, () => clearSessionGoal(sid))
   }
 }
 
 export function clearSessionGoal(sid: string) {
-  cancelScheduledClear(sid)
+  clearTimers.cancel(sid)
 
   const map = $goalsBySession.get()
 
diff --git a/apps/desktop/src/store/pet-gallery.ts b/apps/desktop/src/store/pet-gallery.ts
index 60322bcc1f..8c7f282c56 100644
--- a/apps/desktop/src/store/pet-gallery.ts
+++ b/apps/desktop/src/store/pet-gallery.ts
@@ -1,5 +1,6 @@
 import { atom } from 'nanostores'
 
+import { isMissingRpcMethod } from '@/lib/gateway-rpc'
 import { normalize } from '@/lib/text'
 import {
   $petInfo,
@@ -64,12 +65,6 @@ const petRpc = <T>(request: GatewayRequest, method: string, params: Record<strin
   request<T>(method, { ...params, profile: petProfile() })
 
 /** A JSON-RPC "method not found" — the backend predates the pet RPCs. */
-function isMissingMethod(error: unknown): boolean {
-  const message = error instanceof Error ? error.message : String(error)
-
-  return /method not found|-32601|unknown method|no such method/i.test(message)
-}
-
 export const $petGallery = atom<PetGallery | null>(null)
 export const $petGalleryStatus = atom<PetGalleryStatus>('idle')
 export const $petGalleryError = atom<string | null>(null)
@@ -148,7 +143,7 @@ export function loadPetGallery(request: GatewayRequest, options: { force?: boole
         localOk = true
       }
     } catch (e) {
-      if (isMissingMethod(e)) {
+      if (isMissingRpcMethod(e)) {
         $petGalleryStatus.set('stale')
       } else if (!$petGallery.get()) {
         // Only surface a hard error when we have nothing to show; a transient
@@ -188,7 +183,7 @@ async function syncInfo(request: GatewayRequest): Promise<void> {
     try {
       meta = await petRpc<PetInfoMeta>(request, 'pet.info.meta')
     } catch (e) {
-      if (!isMissingMethod(e)) {
+      if (!isMissingRpcMethod(e)) {
         throw e
       }
 
@@ -308,7 +303,7 @@ async function mutate(
 
     return true
   } catch (e) {
-    if (isMissingMethod(e)) {
+    if (isMissingRpcMethod(e)) {
       $petGalleryStatus.set('stale')
     } else {
       $petGalleryError.set(e instanceof Error ? e.message : fallback)
diff --git a/apps/desktop/src/store/pet-generate.ts b/apps/desktop/src/store/pet-generate.ts
index e829e68c09..bbb6986edc 100644
--- a/apps/desktop/src/store/pet-generate.ts
+++ b/apps/desktop/src/store/pet-generate.ts
@@ -1,5 +1,6 @@
 import { atom } from 'nanostores'
 
+import { isMissingRpcMethod } from '@/lib/gateway-rpc'
 import { persistBoolean, persistString, storedBoolean, storedString } from '@/lib/storage'
 import { capitalize } from '@/lib/text'
 import { $gateway } from '@/store/gateway'
@@ -181,12 +182,6 @@ export const $petGenInput = atom('')
 export const $petGenRefImage = atom<string | null>(null)
 export const $petGenRefName = atom('')
 
-function isMissingMethod(error: unknown): boolean {
-  const message = error instanceof Error ? error.message : String(error)
-
-  return /method not found|-32601|unknown method|no such method/i.test(message)
-}
-
 /** Clear all generation state (before a fresh run). */
 export function resetPetGen(): void {
   $petGenStatus.set('idle')
@@ -439,7 +434,7 @@ export async function generateDrafts(request: GatewayRequest, options: GenerateO
       return false
     }
 
-    if (isMissingMethod(e)) {
+    if (isMissingRpcMethod(e)) {
       $petGenStatus.set('stale')
     } else {
       $petGenStatus.set('error')
diff --git a/apps/desktop/src/store/projects.ts b/apps/desktop/src/store/projects.ts
index 9af7255c6f..b904b0f34e 100644
--- a/apps/desktop/src/store/projects.ts
+++ b/apps/desktop/src/store/projects.ts
@@ -9,8 +9,8 @@ import type { HermesGitBaseBranch, HermesGitBranch } from '@/global'
 import { getHermesConfig, hermesApi, type HermesGateway } from '@/hermes'
 import { translateNow } from '@/i18n'
 import { desktopDefaultCwd, isDesktopFsRemoteMode, selectDesktopPaths, writeDesktopFileText } from '@/lib/desktop-fs'
-import { desktopGit, isGitEndpointMissingError } from '@/lib/desktop-git'
-import { isMissingRpcMethod } from '@/lib/gateway-rpc'
+import { desktopGit } from '@/lib/desktop-git'
+import { isMissingRestEndpoint, isMissingRpcMethod } from '@/lib/gateway-rpc'
 import { isUnderPath } from '@/lib/path-compare'
 import { persistentAtom } from '@/lib/persisted'
 import { $gateway, activeGateway, ensureActiveGatewayOpen } from '@/store/gateway'
@@ -1097,7 +1097,7 @@ export async function startWorkInRepo(
     // backend's /api/git mirror, and an older backend may predate it. The raw
     // failure ("Expected JSON … but got HTML" / a bare 404) reads like a git
     // error — name the real remedy instead of degrading silently.
-    if (isDesktopFsRemoteMode() && isGitEndpointMissingError(err)) {
+    if (isDesktopFsRemoteMode() && isMissingRestEndpoint(err)) {
       throw new Error(translateNow('sidebar.projects.worktreeStaleBackend'))
     }
 
diff --git a/apps/desktop/src/store/todos.ts b/apps/desktop/src/store/todos.ts
index e63c4f67f5..864ab5c2cb 100644
--- a/apps/desktop/src/store/todos.ts
+++ b/apps/desktop/src/store/todos.ts
@@ -1,5 +1,6 @@
 import { atom, computed } from 'nanostores'
 
+import { keyedTimeouts } from '@/lib/keyed-timeouts'
 import { stableRecord } from '@/lib/stable-array'
 import type { TodoItem } from '@/lib/todos'
 
@@ -66,38 +67,23 @@ export function todosForHydration(todos: readonly TodoItem[] | null): TodoItem[]
 // lingers just long enough to see the last checkmark land, then the group
 // drops out of the stack on its own.
 const FINISHED_LINGER_MS = 4_000
-const clearTimers = new Map<string, ReturnType<typeof setTimeout>>()
-
-function cancelScheduledClear(sid: string) {
-  const timer = clearTimers.get(sid)
-
-  if (timer !== undefined) {
-    clearTimeout(timer)
-    clearTimers.delete(sid)
-  }
-}
+const clearTimers = keyedTimeouts()
 
 export function setSessionTodos(sid: string, todos: TodoItem[]) {
   if (!sid) {
     return
   }
 
-  cancelScheduledClear(sid)
+  clearTimers.cancel(sid)
   $todosBySession.set({ ...$todosBySession.get(), [sid]: todos })
 
   if (!todoListActive(todos)) {
-    clearTimers.set(
-      sid,
-      setTimeout(() => {
-        clearTimers.delete(sid)
-        clearSessionTodos(sid)
-      }, FINISHED_LINGER_MS)
-    )
+    clearTimers.schedule(sid, FINISHED_LINGER_MS, () => clearSessionTodos(sid))
   }
 }
 
 export function clearSessionTodos(sid: string) {
-  cancelScheduledClear(sid)
+  clearTimers.cancel(sid)
 
   const map = $todosBySession.get()
 
diff --git a/apps/shared/src/data-url-read-max.ts b/apps/shared/src/data-url-read-max.ts
new file mode 100644
index 0000000000..1b8cd157f6
--- /dev/null
+++ b/apps/shared/src/data-url-read-max.ts
@@ -0,0 +1,27 @@
+/**
+ * Size cap for local files Desktop loads as data URLs (composer attach, image
+ * preview, …).
+ *
+ * Main owns the persisted value; the renderer mirrors it in Settings → Chat and
+ * clamps optimistically before sending. Both ends have to agree on the default
+ * and the bounds, so they live here rather than as two constants with a
+ * "keep these in sync" comment between them.
+ *
+ * The whole file is base64-buffered in main, so this is a memory guard, not a
+ * model limit. The ceiling is only a typo guard — values well below it can
+ * still OOM the app.
+ */
+
+export const DATA_URL_READ_DEFAULT_MAX_MB = 16
+export const DATA_URL_READ_MIN_MAX_MB = 1
+export const DATA_URL_READ_MAX_MAX_MB = 4096
+
+export function clampDataUrlReadMaxMb(value: unknown): number {
+  const parsed = Number(value)
+
+  if (!Number.isFinite(parsed)) {
+    return DATA_URL_READ_DEFAULT_MAX_MB
+  }
+
+  return Math.min(DATA_URL_READ_MAX_MAX_MB, Math.max(DATA_URL_READ_MIN_MAX_MB, Math.round(parsed)))
+}
diff --git a/apps/shared/src/index.ts b/apps/shared/src/index.ts
index b4f6299ca2..5dfe39e1ff 100644
--- a/apps/shared/src/index.ts
+++ b/apps/shared/src/index.ts
@@ -40,6 +40,12 @@ export {
   type CronTriggerController,
   type CronTriggerRunResult
 } from './cron-trigger-controller'
+export {
+  clampDataUrlReadMaxMb,
+  DATA_URL_READ_DEFAULT_MAX_MB,
+  DATA_URL_READ_MAX_MAX_MB,
+  DATA_URL_READ_MIN_MAX_MB
+} from './data-url-read-max'
 export {
   type ConnectionState,
   type GatewayClientOptions,

From a8d87ac1d9e055b33aaa45dd8b5ca2cae6e84f04 Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 19 Aug 2026 02:52:20 -0500
Subject: [PATCH 15/48] fix(desktop): keep the preload bridge alive under the
 sandbox

Deciding whether the OS can back glass needs os.release(), but every
Hermes window runs its preload with sandbox: true, where require is a
polyfill limited to electron, events, timers and url. The node:os import
threw before contextBridge ran, so window.hermesDesktop was never defined
and the app booted straight into "Desktop IPC bridge is unavailable".

Main already computes both verdicts, so preload asks for them over a
synchronous channel instead. No reply degrades to no glass, which is an
ordinary opaque window rather than a page thinned over nothing.
---
 apps/desktop/e2e/boot.spec.ts    | 19 +++++++++++++++++++
 apps/desktop/electron/main.ts    | 11 +++++++++++
 apps/desktop/electron/preload.ts | 14 ++++++++++----
 3 files changed, 40 insertions(+), 4 deletions(-)

diff --git a/apps/desktop/e2e/boot.spec.ts b/apps/desktop/e2e/boot.spec.ts
index 3a74fa4cc5..19f2d81fa4 100644
--- a/apps/desktop/e2e/boot.spec.ts
+++ b/apps/desktop/e2e/boot.spec.ts
@@ -50,6 +50,25 @@ test.describe('dev-mode boot with mock backend', () => {
     })
   })
 
+  // A preload that throws never reaches contextBridge, so the renderer boots
+  // into "Desktop IPC bridge is unavailable" and every test below it dies on a
+  // 120s never-became-ready timeout instead. Checking the bridge by name makes
+  // that failure legible. The sandbox lets preload require only electron,
+  // events, timers and url — adding any other node builtin lands here.
+  test('the preload bridge reaches the renderer', async () => {
+    const bridge = await fixture!.page.evaluate(() => {
+      const desktop = (window as unknown as { hermesDesktop?: Record<string, unknown> }).hermesDesktop
+
+      return {
+        present: typeof desktop,
+        glassSupported: typeof desktop?.glassSupported,
+        translucencySupported: typeof desktop?.translucencySupported
+      }
+    })
+
+    expect(bridge).toEqual({ present: 'object', glassSupported: 'boolean', translucencySupported: 'boolean' })
+  })
+
   test('backend boots and app becomes ready', async () => {
     // This is the big one — wait for the full boot chain to complete:
     // electron starts → hermes serve is spawned → WS connects → config
diff --git a/apps/desktop/electron/main.ts b/apps/desktop/electron/main.ts
index c4746fc313..d4e3fcf165 100644
--- a/apps/desktop/electron/main.ts
+++ b/apps/desktop/electron/main.ts
@@ -306,6 +306,7 @@ import {
   glassActive,
   glassSupportedOn,
   normalizeState as normalizeTranslucency,
+  translucencySupportedOn,
   vibrancyFor as vibrancyForTranslucency,
   windowBackingOptions,
   windowOpacityFor
@@ -402,6 +403,9 @@ const DARWIN_MAJOR = IS_MAC ? Number.parseInt(os.release(), 10) || 0 : 0
 // Glass: macOS vibrancy, or Windows 11 22H2+ system backdrop. Computed once
 // so the renderer, the persisted default, and every chat window agree.
 const GLASS_SUPPORTED = glassSupportedOn(process.platform, os.release())
+// Clear rides setOpacity, a documented no-op on Linux, so neither mode works
+// there and Settings drops the row entirely.
+const TRANSLUCENCY_SUPPORTED = translucencySupportedOn(process.platform)
 const APP_ROOT = app.getAppPath()
 
 // Device-local preference: block F12 from opening DevTools.
@@ -14106,6 +14110,13 @@ app.on('before-quit', () => {
   }
 })
 
+// Answered synchronously so preload can publish the verdict before the
+// renderer's first script — see the note there on why it cannot decide this
+// itself. Registered at module scope, which runs long before any window.
+ipcMain.on('hermes:translucency:support', event => {
+  event.returnValue = { glass: GLASS_SUPPORTED, translucency: TRANSLUCENCY_SUPPORTED }
+})
+
 ipcMain.on('hermes:translucency', (_event, payload) => {
   const next = normalizeTranslucency(payload, GLASS_SUPPORTED)
   const previous = translucencyState
diff --git a/apps/desktop/electron/preload.ts b/apps/desktop/electron/preload.ts
index 1296d08ff9..2d1ba597ce 100644
--- a/apps/desktop/electron/preload.ts
+++ b/apps/desktop/electron/preload.ts
@@ -1,11 +1,17 @@
 import { contextBridge, ipcRenderer, webFrame, webUtils } from 'electron'
-import os from 'node:os'
 
-import { glassSupportedOn, translucencySupportedOn } from '../../shared/src/translucency'
+// Which translucency the OS can back. Asked synchronously because the renderer
+// needs it before its first paint, and answered by main because deciding it
+// needs `os.release()` — a sandboxed preload may only require electron, events,
+// timers and url, so importing node:os here throws before contextBridge runs
+// and takes the ENTIRE bridge down with it (window.hermesDesktop undefined =>
+// "Desktop IPC bridge is unavailable"). No reply means no glass, which degrades
+// to an ordinary opaque window rather than a page thinned over nothing.
+const translucencySupport = ipcRenderer.sendSync('hermes:translucency:support')
 
 contextBridge.exposeInMainWorld('hermesDesktop', {
-  glassSupported: glassSupportedOn(process.platform, os.release()),
-  translucencySupported: translucencySupportedOn(process.platform),
+  glassSupported: translucencySupport?.glass === true,
+  translucencySupported: translucencySupport?.translucency === true,
   getConnection: profile => ipcRenderer.invoke('hermes:connection', profile),
   // Registry-scoped backend resolution: { connectionId, profile } → descriptor.
   getConnectionFor: payload => ipcRenderer.invoke('hermes:connection:for', payload),

From 7ed3a5cbe293692fc33e42b70e025fc8f87ae17e Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 19 Aug 2026 03:34:50 -0500
Subject: [PATCH 16/48] docs(desktop): repoint comments at the modules that now
 own the code

Comments naming gateway-event.ts, chat-messages.ts and hermes.ts as the
place to look, for files those symbols no longer live in.
---
 .../desktop/src/app/contrib/dev/credits-notice-demo.ts |  2 +-
 .../src/app/session/hooks/use-prompt-actions/rewind.ts |  2 +-
 apps/desktop/src/store/live-sync.ts                    | 10 +++++-----
 apps/desktop/src/store/settings-scope.ts               |  2 +-
 4 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/apps/desktop/src/app/contrib/dev/credits-notice-demo.ts b/apps/desktop/src/app/contrib/dev/credits-notice-demo.ts
index 1766489818..4f934b8e53 100644
--- a/apps/desktop/src/app/contrib/dev/credits-notice-demo.ts
+++ b/apps/desktop/src/app/contrib/dev/credits-notice-demo.ts
@@ -2,7 +2,7 @@
 // usage bands. Each trigger emits ONE synthetic `notification.show` /
 // `notification.clear` gateway event through the real fan-out
 // (`emitLocalGatewayEvent`), so it exercises the actual dispatcher branch in
-// `use-message-stream/gateway-event.ts` — toast render, key-replacement
+// `use-message-stream/gateway-event/status.ts` — toast render, key-replacement
 // escalation, TTL self-dismiss, native OS notification, and billing re-poll.
 //
 // Installed only under `import.meta.env.DEV` (see contrib/wiring.tsx), so none
diff --git a/apps/desktop/src/app/session/hooks/use-prompt-actions/rewind.ts b/apps/desktop/src/app/session/hooks/use-prompt-actions/rewind.ts
index 8b83ba6c1d..aec6ad6ac6 100644
--- a/apps/desktop/src/app/session/hooks/use-prompt-actions/rewind.ts
+++ b/apps/desktop/src/app/session/hooks/use-prompt-actions/rewind.ts
@@ -94,7 +94,7 @@ export function rebindSurvivorRowIds(messages: ChatMessage[], survivorRowIds: Su
 
 /**
  * Renderer-synthetic message ids (`${timestamp}-${index}-${role}` from
- * chat-messages.ts, plus older `user-…` / `assistant-…` shapes). Gateway
+ * chat-messages/hydration.ts, plus older `user-…` / `assistant-…` shapes). Gateway
  * history never carries them — only durable `row_id` / platform message_id.
  */
 export function isSyntheticRendererId(messageId: string | undefined): boolean {
diff --git a/apps/desktop/src/store/live-sync.ts b/apps/desktop/src/store/live-sync.ts
index 61b2a55cf9..844c4d39f2 100644
--- a/apps/desktop/src/store/live-sync.ts
+++ b/apps/desktop/src/store/live-sync.ts
@@ -3,11 +3,11 @@ import { atom } from 'nanostores'
 // Event-driven "backend data changed" signals — the workspace-events twin for
 // gateway-side state. The change watcher in tui_gateway broadcasts
 // `pet.changed` / `cron.changed` / `sessions.changed` when its on-disk
-// signatures move (see server._broadcast_watched_changes), gateway-event.ts
-// routes them here, and the surfaces that used to poll (cron sidebar/page,
-// messaging lists, pet sprite, live session statuses) subscribe to these ticks
-// and refresh — so they move exactly when the backend acts and stay idle
-// otherwise.
+// signatures move (see server._broadcast_watched_changes), the gateway-event
+// lifecycle handler routes them here, and the surfaces that used to poll (cron
+// sidebar/page, messaging lists, pet sprite, live session statuses) subscribe
+// to these ticks and refresh — so they move exactly when the backend acts and
+// stay idle otherwise.
 //
 // `$changeEventsAvailable` is the compat gate: gateway.ready advertises
 // `change_events: true` on backends that broadcast. Consumers keep their old
diff --git a/apps/desktop/src/store/settings-scope.ts b/apps/desktop/src/store/settings-scope.ts
index 0c079bb7ff..c8178f22df 100644
--- a/apps/desktop/src/store/settings-scope.ts
+++ b/apps/desktop/src/store/settings-scope.ts
@@ -8,7 +8,7 @@ import { $activeGatewayProfile, normalizeProfileKey } from '@/store/profile'
 // picking a profile on one page carries to the next instead of resetting per
 // page. `null` means "follow the app's active profile" — the default, which
 // keeps single-profile users on the exact pre-existing code path (requests
-// fall back to the app-wide active profile in hermes.ts `profileScoped`).
+// fall back to the app-wide active profile in api/client.ts `profileScoped`).
 export const $settingsScopeOverride = atom<null | string>(null)
 
 // The profile the settings pages are currently editing (a concrete key).

From 9ab5d92fac2e84021aedb4903c61abcc74daadba Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 19 Aug 2026 02:57:53 -0500
Subject: [PATCH 17/48] fix(desktop): sort translucency named exports for
 eslint

Perfectionist wants values before types in the glass/Windows barrel.
---
 apps/desktop/electron/translucency.test.ts | 6 +++---
 apps/desktop/electron/translucency.ts      | 4 ++--
 apps/shared/src/index.ts                   | 6 +++---
 3 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/apps/desktop/electron/translucency.test.ts b/apps/desktop/electron/translucency.test.ts
index 44f90a2d12..6795fdd5d7 100644
--- a/apps/desktop/electron/translucency.test.ts
+++ b/apps/desktop/electron/translucency.test.ts
@@ -34,10 +34,10 @@ import {
   type TranslucencyState,
   translucencySupportedOn,
   vibrancyFor,
-  WINDOWS_BACKGROUND_MATERIALS,
-  WINDOWS_GLASS_MIN_BUILD,
   windowBackingOptions,
-  windowOpacityFor
+  windowOpacityFor,
+  WINDOWS_BACKGROUND_MATERIALS,
+  WINDOWS_GLASS_MIN_BUILD
 } from './translucency'
 
 /** The linear ramp the curve replaced. Endpoints must still agree with it. */
diff --git a/apps/desktop/electron/translucency.ts b/apps/desktop/electron/translucency.ts
index aefedc21f0..6e524a8d8f 100644
--- a/apps/desktop/electron/translucency.ts
+++ b/apps/desktop/electron/translucency.ts
@@ -37,10 +37,10 @@ export {
   type TranslucencyState,
   translucencySupportedOn,
   vibrancyFor,
+  windowOpacityFor,
   WINDOWS_BACKGROUND_MATERIALS,
   WINDOWS_GLASS_MIN_BUILD,
-  type WindowsBackgroundMaterial,
-  windowOpacityFor
+  type WindowsBackgroundMaterial
 } from '../../shared/src/translucency'
 
 /**
diff --git a/apps/shared/src/index.ts b/apps/shared/src/index.ts
index 7f96081096..1b6ef4558a 100644
--- a/apps/shared/src/index.ts
+++ b/apps/shared/src/index.ts
@@ -71,9 +71,9 @@ export {
   GLASS_SCOPES,
   glassActive,
   type GlassMaterial,
-  type GlassScope,
   glassMaterialForPicker,
   glassMaterialsFor,
+  type GlassScope,
   glassSupportedOn,
   glassSurfaceKeep,
   normalizeMaterial,
@@ -89,10 +89,10 @@ export {
   type TranslucencyState,
   translucencySupportedOn,
   vibrancyFor,
+  windowOpacityFor,
   WINDOWS_BACKGROUND_MATERIALS,
   WINDOWS_GLASS_MIN_BUILD,
-  type WindowsBackgroundMaterial,
-  windowOpacityFor
+  type WindowsBackgroundMaterial
 } from './translucency'
 export {
   buildHermesWebSocketUrl,

From 808fde106dc7f81aec097a98560e14d28d7a966c Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 19 Aug 2026 03:34:50 -0500
Subject: [PATCH 18/48] test(desktop): share the duplicated fixtures
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The same AST sweep over specs found fixtures maintained in parallel
across suites that have no reason to know about each other.

Twenty-one specs each mounted useMessageStream themselves and ten of the
harnesses were byte-identical; twenty now take renderMessageStream, with
overrides for the seams that genuinely vary. The SessionInfo builder was
spelled out field-by-field in seven specs, so a new backend field broke
seven files instead of one. Twenty specs carried their own inert
ResizeObserver and eleven repeated the animation-frame, CSS.escape,
scrollTo and WAAPI stubs the transcript needs to mount at all — split by
scope into src/test/jsdom for what any component might need and the
assistant-ui folder's own kit for the transcript. Plus the window-state
bridge, deferred, the external-store thread runtime, the manual
createRoot harness, and the per-folder caret, env-var, provider and
session fixtures.

Left alone on purpose: the store suites' makePrimary, where the vi.mock
harness around it is the actual duplication and cannot be hoisted out of
a hoisted factory; electron's deferred, where reaching into src/ from
the main process would invert the layering for eight lines; and the two
suites that compose another hook alongside the stream.
---
 apps/desktop/e2e/batch-clarify.spec.ts        |   4 +-
 .../composer/hooks/use-composer-undo.test.tsx |  19 +-
 .../src/app/chat/composer/rich-editor.test.ts |  29 +--
 .../src/app/chat/composer/test-utils.ts       |  14 ++
 .../chat/session-tile-attachments.test.tsx    |  12 +-
 .../sidebar/projects/workspace-groups.test.ts | 178 +++++++++---------
 .../highlight-watcher.test.tsx                |  14 +-
 .../hooks/use-desktop-integrations.test.tsx   |  21 +--
 .../desktop/src/app/cron/cron-actions.test.ts |  12 +-
 .../terminal/persistent.test.tsx              |  97 +++-------
 .../session/hooks/use-cwd-actions.test.tsx    |  12 +-
 .../session/hooks/use-hermes-config.test.ts   |  12 +-
 .../agent-init-error.test.tsx                 |  63 ++-----
 .../approval-mode-event.test.tsx              |  63 ++-----
 .../clarify-hydration.test.tsx                |  90 +++------
 .../compaction-event.test.tsx                 |  54 +-----
 .../composer-model-event.test.tsx             |  59 ++----
 .../use-message-stream/delta-flush.test.tsx   |  62 ++----
 .../interim-sealing.test.tsx                  | 100 ++++------
 .../moa-progress-event.test.tsx               |  87 ++-------
 .../moa-reference-event.test.tsx              |  79 ++------
 .../pet-tool-failure-event.test.tsx           |  54 +-----
 .../provider-wait-event.test.tsx              |  44 +----
 .../session-info-side-effects.test.tsx        |  78 +++-----
 .../session-reclaimed.test.tsx                |  71 ++-----
 .../stale-pending-settle.test.tsx             |  58 +-----
 .../use-message-stream/stream-flush.test.tsx  |  58 +-----
 .../terminal-error-frame.test.tsx             |  66 ++-----
 .../hooks/use-message-stream/test-harness.tsx | 117 ++++++++++++
 .../timeline-events.test.tsx                  |  59 +-----
 .../use-message-stream/todo-cleanup.test.tsx  |  62 ++----
 .../tool-drafting-event.test.tsx              |  59 ++----
 .../hooks/use-message-stream/usage.test.tsx   |  67 ++-----
 .../session/hooks/use-model-controls.test.tsx |  12 +-
 .../hooks/use-prompt-actions/rewind.test.ts   |   4 +-
 .../hooks/use-session-actions.test.tsx        |  11 +-
 .../hooks/use-session-list-actions.test.tsx   |  11 +-
 .../session/workspace-session-target.test.ts  |  12 +-
 .../src/app/settings/keys-settings.test.tsx   |  26 +--
 .../app/settings/searchable-select.test.tsx   |  11 +-
 .../src/app/settings/settings-search.test.ts  |  17 +-
 apps/desktop/src/app/settings/test-utils.ts   |  17 ++
 .../src/app/shell/approval-mode-menu.test.tsx |  14 +-
 .../shell/hooks/use-status-snapshot.test.ts   |  14 +-
 .../app/shell/statusbar-visibility.test.tsx   |  16 +-
 .../components/assistant-ui/test-utils.tsx    |  86 +++++++++
 .../assistant-ui/thread-remount.test.tsx      |  50 +----
 .../thread/assistant-message.test.tsx         |  19 +-
 .../thread/block-direction.test.tsx           |  38 +---
 .../thread/double-click-reaction.test.tsx     |  30 +--
 .../duplicate-activity-indicator.test.tsx     |  53 +-----
 .../assistant-ui/thread/edit-context.test.tsx |  69 +------
 .../thread/status-tail-only.test.tsx          |  61 ++----
 .../assistant-ui/thread/streaming.test.tsx    |  58 ++----
 .../thread/system-message.test.tsx            |  20 +-
 .../thread/turn-gap-indicator.test.tsx        |  65 ++-----
 .../thread/user-message-edit-gesture.test.tsx |  60 +-----
 .../thread/user-message-edit.test.tsx         |  66 +------
 .../assistant-ui/tool/tool-group.test.tsx     |  55 +-----
 .../image-generation-placeholder.test.tsx     |  28 +--
 .../src/components/language-switcher.test.tsx |  16 +-
 .../src/components/onboarding/index.test.tsx  |  29 ++-
 .../tree/renderer/floating-panes.test.tsx     |  46 ++---
 .../tree/renderer/narrow-overlays.test.tsx    |  11 +-
 .../tree/renderer/tool-panel-close.test.tsx   |  14 +-
 .../src/components/pet/pet-sprite.test.tsx    |  85 +++------
 .../src/components/pet/use-pet-roam.test.tsx  |  77 ++------
 .../src/components/ui/status-pulse.test.tsx   |  34 +---
 apps/desktop/src/lib/budgeted-loop.test.ts    |  28 +--
 .../src/lib/session-branch-tree.test.ts       |  19 +-
 .../src/lib/session-date-groups.test.ts       |  19 +-
 apps/desktop/src/store/approval-mode.test.ts  |  14 +-
 .../src/store/cron-model-impact.test.ts       |  12 +-
 apps/desktop/src/store/onboarding.test.ts     |  40 ++--
 .../store/profile-agent-activation.test.ts    |  12 +-
 apps/desktop/src/store/session-color.test.ts  |  45 ++---
 apps/desktop/src/store/session-unread.test.ts |  21 +--
 apps/desktop/src/store/session.test.ts        |  21 +--
 apps/desktop/src/test/deferred.ts             |  16 ++
 apps/desktop/src/test/jsdom.ts                |  26 +++
 apps/desktop/src/test/oauth-provider.ts       |  14 ++
 apps/desktop/src/test/react-root.ts           |  44 +++++
 apps/desktop/src/test/session-info.ts         |  46 +++++
 apps/desktop/src/test/window-state.ts         |  47 +++++
 84 files changed, 1129 insertions(+), 2404 deletions(-)
 create mode 100644 apps/desktop/src/app/chat/composer/test-utils.ts
 create mode 100644 apps/desktop/src/app/session/hooks/use-message-stream/test-harness.tsx
 create mode 100644 apps/desktop/src/app/settings/test-utils.ts
 create mode 100644 apps/desktop/src/components/assistant-ui/test-utils.tsx
 create mode 100644 apps/desktop/src/test/deferred.ts
 create mode 100644 apps/desktop/src/test/jsdom.ts
 create mode 100644 apps/desktop/src/test/oauth-provider.ts
 create mode 100644 apps/desktop/src/test/react-root.ts
 create mode 100644 apps/desktop/src/test/session-info.ts
 create mode 100644 apps/desktop/src/test/window-state.ts

diff --git a/apps/desktop/e2e/batch-clarify.spec.ts b/apps/desktop/e2e/batch-clarify.spec.ts
index 8658bd3b1b..acf97ddb2e 100644
--- a/apps/desktop/e2e/batch-clarify.spec.ts
+++ b/apps/desktop/e2e/batch-clarify.spec.ts
@@ -5,8 +5,8 @@
  * model's tool_call_id while `clarify.request` carries a gateway-generated
  * request_id. A batch payload has no top-level `question`, so the two rows
  * only merge when the correlation key comes from the question list
- * (`batchClarifyMatchValue` in lib/chat-messages.ts). Before that fix this
- * exact flow rendered two identical interactive cards.
+ * (`batchClarifyMatchValue` in lib/chat-messages/tool-parts.ts). Before that
+ * fix this exact flow rendered two identical interactive cards.
  *
  * The flow runs the real chain: composer → gateway → agent → clarify tool →
  * clarify.request event → renderer, against the mock inference server.
diff --git a/apps/desktop/src/app/chat/composer/hooks/use-composer-undo.test.tsx b/apps/desktop/src/app/chat/composer/hooks/use-composer-undo.test.tsx
index bbffc396ec..c687d310e4 100644
--- a/apps/desktop/src/app/chat/composer/hooks/use-composer-undo.test.tsx
+++ b/apps/desktop/src/app/chat/composer/hooks/use-composer-undo.test.tsx
@@ -2,6 +2,8 @@ import { render } from '@testing-library/react'
 import { createRef, type RefObject } from 'react'
 import { describe, expect, it, vi } from 'vitest'
 
+import { placeCaretAtEnd } from '../test-utils'
+
 import { useComposerUndo } from './use-composer-undo'
 
 /** Mount the hook against a real contentEditable, exposing its API. */
@@ -36,19 +38,10 @@ function makeEditor(text: string) {
   return { editor, ref }
 }
 
-const caretAtEnd = (editor: HTMLElement) => {
-  const range = document.createRange()
-  const selection = window.getSelection()!
-  range.selectNodeContents(editor)
-  range.collapse(false)
-  selection.removeAllRanges()
-  selection.addRange(range)
-}
-
 describe('useComposerUndo', () => {
   it('restores the pre-edit text, which is what a paste destroyed', () => {
     const { editor, ref } = makeEditor('before')
-    caretAtEnd(editor)
+    placeCaretAtEnd(editor)
 
     const { api, view } = mountUndo(ref, () => editor.textContent || '')
 
@@ -69,7 +62,7 @@ describe('useComposerUndo', () => {
 
   it('withUndoPoint banks only when the edit actually ran', () => {
     const { editor, ref } = makeEditor('text')
-    caretAtEnd(editor)
+    placeCaretAtEnd(editor)
 
     const { api, view } = mountUndo(ref, () => editor.textContent || '')
 
@@ -95,7 +88,7 @@ describe('useComposerUndo', () => {
   it('claims a native historyUndo aimed at the focused editor', () => {
     const { editor, ref } = makeEditor('kept')
     editor.focus()
-    caretAtEnd(editor)
+    placeCaretAtEnd(editor)
 
     const { api, view } = mountUndo(ref, () => editor.textContent || '')
 
@@ -162,7 +155,7 @@ describe('useComposerUndo', () => {
 
   it('reset drops history so undo cannot cross a draft swap', () => {
     const { editor, ref } = makeEditor('session A')
-    caretAtEnd(editor)
+    placeCaretAtEnd(editor)
 
     const { api, view } = mountUndo(ref, () => editor.textContent || '')
 
diff --git a/apps/desktop/src/app/chat/composer/rich-editor.test.ts b/apps/desktop/src/app/chat/composer/rich-editor.test.ts
index 6c3d2f8733..d3bfd60eed 100644
--- a/apps/desktop/src/app/chat/composer/rich-editor.test.ts
+++ b/apps/desktop/src/app/chat/composer/rich-editor.test.ts
@@ -11,16 +11,7 @@ import {
   replaceBeforeCaret,
   RICH_INPUT_SLOT
 } from './rich-editor'
-
-const caretIn = (editor: HTMLElement) => {
-  const range = document.createRange()
-  const selection = window.getSelection()!
-
-  range.selectNodeContents(editor)
-  range.collapse(false)
-  selection.removeAllRanges()
-  selection.addRange(range)
-}
+import { placeCaretAtEnd } from './test-utils'
 
 describe('renderComposerContents', () => {
   it('renders refs and raw text without interpreting user text as HTML', () => {
@@ -160,7 +151,7 @@ describe('insertInlineRefsIntoEditor', () => {
     editor.dataset.slot = RICH_INPUT_SLOT
     editor.append(document.createTextNode('review'))
     document.body.append(editor)
-    caretIn(editor)
+    placeCaretAtEnd(editor)
 
     expect(insertInlineRefsIntoEditor(editor, ['@file:`src/a.ts`'])).toBe('review @file:`src/a.ts` ')
 
@@ -172,7 +163,7 @@ describe('insertInlineRefsIntoEditor', () => {
     editor.dataset.slot = RICH_INPUT_SLOT
     editor.append(document.createTextNode('review '))
     document.body.append(editor)
-    caretIn(editor)
+    placeCaretAtEnd(editor)
 
     expect(insertInlineRefsIntoEditor(editor, ['@file:`src/a.ts`'])).toBe('review @file:`src/a.ts` ')
 
@@ -185,7 +176,7 @@ describe('insertComposerContentsAtCaret', () => {
     const editor = document.createElement('div')
     editor.dataset.slot = RICH_INPUT_SLOT
     document.body.append(editor)
-    caretIn(editor)
+    placeCaretAtEnd(editor)
 
     insertComposerContentsAtCaret(editor, 'one\ntwo\nthree')
 
@@ -221,7 +212,7 @@ describe('insertComposerContentsAtCaret', () => {
     const editor = document.createElement('div')
     editor.dataset.slot = RICH_INPUT_SLOT
     document.body.append(editor)
-    caretIn(editor)
+    placeCaretAtEnd(editor)
 
     insertComposerContentsAtCaret(editor, 'read @url:`https://example.dev/a` now')
 
@@ -237,7 +228,7 @@ describe('insertComposerContentsAtCaret', () => {
     const editor = document.createElement('div')
     editor.dataset.slot = RICH_INPUT_SLOT
     document.body.append(editor)
-    caretIn(editor)
+    placeCaretAtEnd(editor)
 
     insertComposerContentsAtCaret(editor, '/some-skill')
 
@@ -253,7 +244,7 @@ describe('insertComposerContentsAtCaret', () => {
     const editor = document.createElement('div')
     editor.dataset.slot = RICH_INPUT_SLOT
     document.body.append(editor)
-    caretIn(editor)
+    placeCaretAtEnd(editor)
 
     insertComposerContentsAtCaret(editor, 'clean @file:`a.ts` with /some-skill then ship')
 
@@ -268,7 +259,7 @@ describe('insertComposerContentsAtCaret', () => {
     const editor = document.createElement('div')
     editor.dataset.slot = RICH_INPUT_SLOT
     document.body.append(editor)
-    caretIn(editor)
+    placeCaretAtEnd(editor)
 
     insertComposerContentsAtCaret(editor, 'see /usr/local/bin and /goal ship it')
 
@@ -283,7 +274,7 @@ describe('insertComposerContentsAtCaret', () => {
     editor.dataset.slot = RICH_INPUT_SLOT
     editor.textContent = 'foo'
     document.body.append(editor)
-    caretIn(editor)
+    placeCaretAtEnd(editor)
 
     insertComposerContentsAtCaret(editor, '/some-skill')
 
@@ -298,7 +289,7 @@ describe('insertComposerContentsAtCaret', () => {
     editor.dataset.slot = RICH_INPUT_SLOT
     editor.append(refChipElement('file', '`a.ts`'))
     document.body.append(editor)
-    caretIn(editor)
+    placeCaretAtEnd(editor)
 
     insertComposerContentsAtCaret(editor, '/some-skill')
 
diff --git a/apps/desktop/src/app/chat/composer/test-utils.ts b/apps/desktop/src/app/chat/composer/test-utils.ts
new file mode 100644
index 0000000000..23c71f74d4
--- /dev/null
+++ b/apps/desktop/src/app/chat/composer/test-utils.ts
@@ -0,0 +1,14 @@
+/** Collapse the selection to the end of the editor's contents.
+ *
+ *  The composer's undo stack, ref rendering, and trigger detection all read the
+ *  live selection, and jsdom starts with none — without this they see a caret
+ *  at offset 0 and take the wrong branch. */
+export function placeCaretAtEnd(editor: HTMLElement) {
+  const range = document.createRange()
+  const selection = window.getSelection()!
+
+  range.selectNodeContents(editor)
+  range.collapse(false)
+  selection.removeAllRanges()
+  selection.addRange(range)
+}
diff --git a/apps/desktop/src/app/chat/session-tile-attachments.test.tsx b/apps/desktop/src/app/chat/session-tile-attachments.test.tsx
index b9a97a8611..b756f821e4 100644
--- a/apps/desktop/src/app/chat/session-tile-attachments.test.tsx
+++ b/apps/desktop/src/app/chat/session-tile-attachments.test.tsx
@@ -13,6 +13,8 @@ import {
 import { $connection, $sessions } from '@/store/session'
 import { $sessionStates, type SessionTileDelegate, setSessionTileDelegate } from '@/store/session-states'
 
+import { deferred } from '../../test/deferred'
+
 const requestGateway = vi.fn()
 
 vi.mock('@/app/gateway/hooks/use-gateway-request', () => ({
@@ -44,16 +46,6 @@ const STAGED_PATH = '/root/.hermes/attachments/photo.png'
 const THUMBNAIL = 'data:image/png;base64,dGh1bWJuYWls'
 const FULL_SOURCE = 'data:image/png;base64,b3JpZ2luYWw='
 
-function deferred<T>() {
-  let resolve!: (value: T) => void
-
-  const promise = new Promise<T>(res => {
-    resolve = res
-  })
-
-  return { promise, resolve }
-}
-
 function makeAttachment(occurrenceId = createComposerAttachmentOccurrenceId()): ComposerAttachment {
   return {
     detail: HOST_PATH,
diff --git a/apps/desktop/src/app/chat/sidebar/projects/workspace-groups.test.ts b/apps/desktop/src/app/chat/sidebar/projects/workspace-groups.test.ts
index bd32d4fd4a..c81f1d72b1 100644
--- a/apps/desktop/src/app/chat/sidebar/projects/workspace-groups.test.ts
+++ b/apps/desktop/src/app/chat/sidebar/projects/workspace-groups.test.ts
@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest'
 
 import type { HermesGitWorktree } from '@/global'
+import { makeCwdSession } from '@/test/session-info'
 import type { ProjectInfo, SessionInfo } from '@/types/hermes'
 
 import {
@@ -22,29 +23,6 @@ import {
 // covered by tests/tui_gateway/test_project_tree.py). This file only covers the
 // thin render helpers the desktop still owns + the VISUAL worktree enhancer.
 
-let nextId = 0
-
-function makeSession(cwd: null | string, overrides: Partial<SessionInfo> = {}): SessionInfo {
-  return {
-    archived: false,
-    cwd,
-    ended_at: null,
-    id: `s${nextId++}`,
-    input_tokens: 0,
-    is_active: false,
-    last_active: 1_000,
-    message_count: 1,
-    model: 'claude',
-    output_tokens: 0,
-    preview: null,
-    source: 'cli',
-    started_at: 1_000,
-    title: null,
-    tool_call_count: 0,
-    ...overrides
-  }
-}
-
 const lane = (over: Partial<SidebarSessionGroup> & Pick<SidebarSessionGroup, 'id' | 'label'>): SidebarSessionGroup => ({
   path: null,
   sessions: [],
@@ -76,7 +54,7 @@ describe('kanbanWorktreeDir', () => {
 
 describe('sortWorktreeGroups', () => {
   it('pins trunk to the top, sinks kanban to the bottom, and orders the rest by recency', () => {
-    const at = (t: number) => [makeSession('/x', { last_active: t })]
+    const at = (t: number) => [makeCwdSession('/x', { last_active: t })]
 
     const groups = [
       lane({ id: 'k', label: 'kanban', isKanban: true, sessions: at(999) }),
@@ -92,7 +70,7 @@ describe('sortWorktreeGroups', () => {
 
   it('pins the live home checkout above trunk, even when it has no sessions yet', () => {
     const groups = [
-      lane({ id: 'main', label: 'main', isMain: true, sessions: [makeSession('/x', { last_active: 999 })] }),
+      lane({ id: 'main', label: 'main', isMain: true, sessions: [makeCwdSession('/x', { last_active: 999 })] }),
       lane({ id: 'home', label: 'bb/projects-paradigm', isMain: true, isHome: true })
     ]
 
@@ -150,7 +128,7 @@ describe('mergeRepoWorktreeGroups (visual enhancer)', () => {
           label: 'main',
           isMain: true,
           path: '/repo',
-          sessions: [makeSession('/repo')]
+          sessions: [makeCwdSession('/repo')]
         })
       ]
     }
@@ -176,7 +154,13 @@ describe('mergeRepoWorktreeGroups (visual enhancer)', () => {
 
   it('does not add a second "main" for a linked worktree checked out on main', () => {
     const groups = [
-      lane({ id: '/repo::branch::main', label: 'main', isMain: true, path: '/repo', sessions: [makeSession('/repo')] })
+      lane({
+        id: '/repo::branch::main',
+        label: 'main',
+        isMain: true,
+        path: '/repo',
+        sessions: [makeCwdSession('/repo')]
+      })
     ]
 
     const discovered: HermesGitWorktree[] = [
@@ -216,14 +200,14 @@ describe('mergeRepoWorktreeGroups (visual enhancer)', () => {
           label: 'main',
           isMain: true,
           path: '/repo',
-          sessions: [makeSession('/repo')]
+          sessions: [makeCwdSession('/repo')]
         }),
         lane({
           id: '/repo-ci',
           label: 'hermes-agent-ci',
           isMain: false,
           path: '/repo-ci',
-          sessions: [makeSession('/repo-ci')]
+          sessions: [makeCwdSession('/repo-ci')]
         })
       ]
     }
@@ -256,7 +240,7 @@ describe('mergeRepoWorktreeGroups (visual enhancer)', () => {
           label: 'bb/attempts',
           isMain: false,
           path: '/repo/.worktrees/attempts',
-          sessions: [makeSession('/repo/.worktrees/attempts')]
+          sessions: [makeCwdSession('/repo/.worktrees/attempts')]
         })
       ]
     }
@@ -291,7 +275,7 @@ describe('mergeRepoWorktreeGroups (visual enhancer)', () => {
           label: 'bb/feature',
           isMain: false,
           path: '/repo-feature',
-          sessions: [makeSession('/repo-feature'), makeSession('/repo-feature')]
+          sessions: [makeCwdSession('/repo-feature'), makeCwdSession('/repo-feature')]
         })
       ]
     }
@@ -313,7 +297,13 @@ describe('mergeRepoWorktreeGroups (visual enhancer)', () => {
       id: '/repo',
       path: '/repo',
       groups: [
-        lane({ id: '/repo-ci', label: 'repo-ci', isMain: false, path: '/repo-ci', sessions: [makeSession('/repo-ci')] })
+        lane({
+          id: '/repo-ci',
+          label: 'repo-ci',
+          isMain: false,
+          path: '/repo-ci',
+          sessions: [makeCwdSession('/repo-ci')]
+        })
       ]
     }
 
@@ -334,7 +324,7 @@ describe('mergeRepoWorktreeGroups (visual enhancer)', () => {
           label: 'main',
           isMain: true,
           path: '/repo',
-          sessions: [makeSession('/repo')]
+          sessions: [makeCwdSession('/repo')]
         })
       ]
     }
@@ -366,7 +356,7 @@ describe('mergeRepoWorktreeGroups (visual enhancer)', () => {
           label: 'main',
           isMain: true,
           path: '/repo',
-          sessions: [makeSession('/repo')]
+          sessions: [makeCwdSession('/repo')]
         })
       ]
     }
@@ -391,14 +381,14 @@ describe('mergeRepoWorktreeGroups (visual enhancer)', () => {
           label: 'main',
           isMain: true,
           path: '/repo',
-          sessions: [makeSession('/repo', { id: 'a' })]
+          sessions: [makeCwdSession('/repo', { id: 'a' })]
         }),
         lane({
           id: '/repo::branch::old',
           label: 'old-feature',
           isMain: true,
           path: '/repo',
-          sessions: [makeSession('/repo', { id: 'b' })]
+          sessions: [makeCwdSession('/repo', { id: 'b' })]
         })
       ]
     }
@@ -425,7 +415,7 @@ describe('mergeRepoWorktreeGroups (visual enhancer)', () => {
           label: 'main',
           isMain: true,
           path: '/repo',
-          sessions: [makeSession('/repo')]
+          sessions: [makeCwdSession('/repo')]
         })
       ]
     }
@@ -481,11 +471,11 @@ const homeNode = (sessions: SessionInfo[]): SidebarProjectTree =>
 
 describe('liveSessionProjectId', () => {
   it('maps a brand-new (unpersisted) session to its auto project (the repo root)', () => {
-    expect(liveSessionProjectId(makeSession('/www/app'), [])).toBe('/www/app')
+    expect(liveSessionProjectId(makeCwdSession('/www/app'), [])).toBe('/www/app')
   })
 
   it('routes a session under an explicit project folder to that project', () => {
-    const id = liveSessionProjectId(makeSession('/www/app/src', { git_repo_root: '/www/app', git_branch: 'feat' }), [
+    const id = liveSessionProjectId(makeCwdSession('/www/app/src', { git_repo_root: '/www/app', git_branch: 'feat' }), [
       makeProject('p_app', ['/www/app'])
     ])
 
@@ -495,31 +485,31 @@ describe('liveSessionProjectId', () => {
   it('anchors a cwd-less session on its git_repo_root (backend groups it there too)', () => {
     // Older/imported rows carry only a repo root; the sidebar files them under
     // the repo's project, so membership (and color) must resolve from the root.
-    expect(liveSessionProjectId(makeSession(null, { git_repo_root: '/www/app' }), [])).toBe('/www/app')
+    expect(liveSessionProjectId(makeCwdSession(null, { git_repo_root: '/www/app' }), [])).toBe('/www/app')
     expect(
-      liveSessionProjectId(makeSession(null, { git_repo_root: '/www/app' }), [makeProject('p_app', ['/www/app'])])
+      liveSessionProjectId(makeCwdSession(null, { git_repo_root: '/www/app' }), [makeProject('p_app', ['/www/app'])])
     ).toBe('p_app')
   })
 
   it('skips cwd-less, kanban-task, and out-of-tree (sibling) worktree sessions', () => {
-    expect(liveSessionProjectId(makeSession(null), [])).toBeNull()
+    expect(liveSessionProjectId(makeCwdSession(null), [])).toBeNull()
     // Kanban task worktree → folds into the kanban bucket, not a project preview.
-    expect(liveSessionProjectId(makeSession('/repo/.worktrees/t_aaaaaaaa'), [])).toBeNull()
+    expect(liveSessionProjectId(makeCwdSession('/repo/.worktrees/t_aaaaaaaa'), [])).toBeNull()
     // Sibling worktree OUTSIDE the repo root → project can't be derived from the row.
-    expect(liveSessionProjectId(makeSession('/elsewhere/wt', { git_repo_root: '/repo' }), [])).toBeNull()
+    expect(liveSessionProjectId(makeCwdSession('/elsewhere/wt', { git_repo_root: '/repo' }), [])).toBeNull()
   })
 
   it('places an in-tree worktree session under its repo project (the root is in the path)', () => {
     // "Convert a branch" / "new worktree" land at `<repoRoot>/.worktrees/<slug>`,
     // so they belong to the same auto project as the repo root and must show in
     // the overview at once, not wait for the next backend refresh.
-    expect(liveSessionProjectId(makeSession('/www/app/.worktrees/test1', { git_repo_root: '/www/app' }), [])).toBe(
+    expect(liveSessionProjectId(makeCwdSession('/www/app/.worktrees/test1', { git_repo_root: '/www/app' }), [])).toBe(
       '/www/app'
     )
   })
 
   it('routes an in-tree worktree session to the owning explicit project', () => {
-    const id = liveSessionProjectId(makeSession('/www/app/.worktrees/test1', { git_repo_root: '/www/app' }), [
+    const id = liveSessionProjectId(makeCwdSession('/www/app/.worktrees/test1', { git_repo_root: '/www/app' }), [
       makeProject('p_app', ['/www/app'])
     ])
 
@@ -532,13 +522,13 @@ describe('liveSessionProjectId', () => {
     // only the auto-project (repo root) fallback needs cwd-under-root
     // confidence. Match via the repo root...
     expect(
-      liveSessionProjectId(makeSession('/www/elsewhere', { git_repo_root: '/home/u/proj' }), [
+      liveSessionProjectId(makeCwdSession('/www/elsewhere', { git_repo_root: '/home/u/proj' }), [
         makeProject('p_proj', ['/home/u/proj'])
       ])
     ).toBe('p_proj')
     // ...and via the cwd.
     expect(
-      liveSessionProjectId(makeSession('/www/elsewhere/sub', { git_repo_root: '/home/u/proj' }), [
+      liveSessionProjectId(makeCwdSession('/www/elsewhere/sub', { git_repo_root: '/home/u/proj' }), [
         makeProject('p_www', ['/www/elsewhere'])
       ])
     ).toBe('p_www')
@@ -547,13 +537,13 @@ describe('liveSessionProjectId', () => {
   it('matches a mixed-case/separator Windows cwd to its explicit project in the live overlay', () => {
     // The bug: a fresh Windows session drops into the overlay before the next
     // backend refresh; case-sensitive matching missed its project until then.
-    const id = liveSessionProjectId(makeSession('c:/work/notes/SUB'), [makeProject('p_notes', ['C:\\Work\\Notes'])])
+    const id = liveSessionProjectId(makeCwdSession('c:/work/notes/SUB'), [makeProject('p_notes', ['C:\\Work\\Notes'])])
 
     expect(id).toBe('p_notes')
   })
 
   it('matches a root-relative WSL cwd (single backslash) case-insensitively', () => {
-    const id = liveSessionProjectId(makeSession('//wsl.localhost/Ubuntu/home/alice/PROJ'), [
+    const id = liveSessionProjectId(makeCwdSession('//wsl.localhost/Ubuntu/home/alice/PROJ'), [
       makeProject('p_proj', ['\\wsl.localhost\\Ubuntu\\home\\alice\\proj'])
     ])
 
@@ -562,7 +552,7 @@ describe('liveSessionProjectId', () => {
 
   it('keeps POSIX cwd matching case-sensitive (no false project match)', () => {
     // Distinct case on POSIX is a distinct path → falls back to its own auto id.
-    expect(liveSessionProjectId(makeSession('/work/notes'), [makeProject('p_notes', ['/Work/Notes'])])).toBe(
+    expect(liveSessionProjectId(makeCwdSession('/work/notes'), [makeProject('p_notes', ['/Work/Notes'])])).toBe(
       '/work/notes'
     )
   })
@@ -575,19 +565,19 @@ describe('sessionProjectColor', () => {
   })
 
   it('inherits the color of the explicit project the session belongs to', () => {
-    const session = makeSession('/www/app/src', { git_repo_root: '/www/app' })
+    const session = makeCwdSession('/www/app/src', { git_repo_root: '/www/app' })
 
     expect(sessionProjectColor(session, [colored('p_app', ['/www/app'], '#4a9eff')])).toBe('#4a9eff')
   })
 
   it('returns null when the owning project has no color set', () => {
-    const session = makeSession('/www/app/src', { git_repo_root: '/www/app' })
+    const session = makeCwdSession('/www/app/src', { git_repo_root: '/www/app' })
 
     expect(sessionProjectColor(session, [makeProject('p_app', ['/www/app'])])).toBeNull()
   })
 
   it('colors a cwd-less session by its git_repo_root project (the grouped-but-grey fix)', () => {
-    const session = makeSession(null, { git_repo_root: '/www/app' })
+    const session = makeCwdSession(null, { git_repo_root: '/www/app' })
 
     expect(sessionProjectColor(session, [colored('p_app', ['/www/app'], '#4a9eff')])).toBe('#4a9eff')
   })
@@ -595,7 +585,7 @@ describe('sessionProjectColor', () => {
   it('colors a cwd-outside-root session when an explicit project folder matches', () => {
     // The backend tree groups such a row under the project; the client color
     // derivation must agree instead of leaving the row (and its tab) grey.
-    const session = makeSession('/www/elsewhere', { git_repo_root: '/home/u/proj' })
+    const session = makeCwdSession('/www/elsewhere', { git_repo_root: '/home/u/proj' })
 
     expect(sessionProjectColor(session, [colored('p_proj', ['/home/u/proj'], '#4a9eff')])).toBe('#4a9eff')
   })
@@ -603,15 +593,15 @@ describe('sessionProjectColor', () => {
   it('returns null for a session that only maps to an auto repo root (no explicit project)', () => {
     // liveSessionProjectId falls back to the repo root id, which is not a
     // project row and therefore carries no color.
-    expect(sessionProjectColor(makeSession('/www/app'), [])).toBeNull()
+    expect(sessionProjectColor(makeCwdSession('/www/app'), [])).toBeNull()
   })
 
   it('returns null for an unplaceable (cwd-less) session', () => {
-    expect(sessionProjectColor(makeSession(null), [colored('p_app', ['/www/app'], '#4a9eff')])).toBeNull()
+    expect(sessionProjectColor(makeCwdSession(null), [colored('p_app', ['/www/app'], '#4a9eff')])).toBeNull()
   })
 
   it('uses the longest-prefix project when nested projects both match', () => {
-    const session = makeSession('/www/app/packages/api/src', { git_repo_root: '/www/app' })
+    const session = makeCwdSession('/www/app/packages/api/src', { git_repo_root: '/www/app' })
 
     const projects = [
       colored('p_root', ['/www/app'], '#111111'),
@@ -630,7 +620,7 @@ describe('overlayLiveLanes', () => {
       repos: [{ id: '/www/app', label: 'app', path: '/www/app', sessionCount: 0, groups: [] }]
     })
 
-    const live = [makeSession('/www/app', { id: 'fresh', git_branch: 'main' })]
+    const live = [makeCwdSession('/www/app', { id: 'fresh', git_branch: 'main' })]
 
     const overlaid = overlayLiveLanes(project, live)
     const lane = overlaid.repos[0].groups.find(g => g.label === 'main')
@@ -649,7 +639,7 @@ describe('overlayLiveLanes', () => {
       repos: [{ id: '/www/app', label: 'app', path: '/www/app', sessionCount: 0, groups: [] }]
     })
 
-    const live = [makeSession('/www/app/.worktrees/baby', { id: 'fresh' })]
+    const live = [makeCwdSession('/www/app/.worktrees/baby', { id: 'fresh' })]
 
     const overlaid = overlayLiveLanes(project, live)
     const lane = overlaid.repos[0].groups.find(g => g.id === '/www/app/.worktrees/baby')
@@ -665,7 +655,7 @@ describe('overlayLiveLanes', () => {
       repos: [{ id: '/www/app', label: 'app', path: '/www/app', sessionCount: 0, groups: [] }]
     })
 
-    const live = [makeSession('/www/app/.worktrees/t_abc12345', { id: 'k' })]
+    const live = [makeCwdSession('/www/app/.worktrees/t_abc12345', { id: 'k' })]
 
     const overlaid = overlayLiveLanes(project, live)
     const lane = overlaid.repos[0].groups.find(g => g.isKanban)
@@ -675,7 +665,7 @@ describe('overlayLiveLanes', () => {
   })
 
   it('does not duplicate a session already present in a backend lane', () => {
-    const existing = makeSession('/www/app', { id: 'dup', git_branch: 'main' })
+    const existing = makeCwdSession('/www/app', { id: 'dup', git_branch: 'main' })
 
     const project = projectNode({
       id: '/www/app',
@@ -704,8 +694,8 @@ describe('overlayLiveLanes', () => {
     // and CREATE a second main lane with the same sessions — dual lanes in the
     // project drill-in (e.g. main + codex-research-guardian).
     const root = '/home/hermes/hermes-workspace/codex-research-guardian'
-    const a = makeSession(root, { id: 's1' }) // empty git_branch / git_repo_root
-    const b = makeSession(root, { id: 's2' })
+    const a = makeCwdSession(root, { id: 's1' }) // empty git_branch / git_repo_root
+    const b = makeCwdSession(root, { id: 's2' })
 
     const project = projectNode({
       id: root,
@@ -742,7 +732,7 @@ describe('overlayLiveLanes', () => {
 
   it('joins a fresh live session into an existing non-git workspace lane (no branch id)', () => {
     const root = '/work/notes'
-    const existing = makeSession(root, { id: 'old' })
+    const existing = makeCwdSession(root, { id: 'old' })
 
     const project = projectNode({
       id: root,
@@ -759,7 +749,7 @@ describe('overlayLiveLanes', () => {
       ]
     })
 
-    const fresh = makeSession(root, { id: 'fresh' })
+    const fresh = makeCwdSession(root, { id: 'fresh' })
     const overlaid = overlayLiveLanes(project, [existing, fresh])
     const groups = overlaid.repos[0].groups
 
@@ -769,14 +759,14 @@ describe('overlayLiveLanes', () => {
   })
 
   it('preserves backend recency order when live sessions overlay a lane', () => {
-    const recentlyActive = makeSession('/www/app', {
+    const recentlyActive = makeCwdSession('/www/app', {
       id: 'recently-active',
       git_branch: 'main',
       started_at: 1,
       last_active: 3
     })
 
-    const newlyCreated = makeSession('/www/app', {
+    const newlyCreated = makeCwdSession('/www/app', {
       id: 'newly-created',
       git_branch: 'main',
       started_at: 2,
@@ -816,7 +806,7 @@ describe('overlayLiveLanes', () => {
     // Backend keyed the worktree lane off a branch-style id (no live git probe),
     // but the lane PATH is the worktree dir. A new session under that worktree
     // must join the existing lane, not spawn a twin.
-    const existing = makeSession('/www/app/.worktrees/baby', { id: 'old' })
+    const existing = makeCwdSession('/www/app/.worktrees/baby', { id: 'old' })
 
     const project = projectNode({
       id: '/www/app',
@@ -838,7 +828,7 @@ describe('overlayLiveLanes', () => {
       ]
     })
 
-    const fresh = makeSession('/www/app/.worktrees/baby', { id: 'fresh' })
+    const fresh = makeCwdSession('/www/app/.worktrees/baby', { id: 'fresh' })
 
     const overlaid = overlayLiveLanes(project, [existing, fresh])
     const lanes = overlaid.repos[0].groups.filter(g => g.path === '/www/app/.worktrees/baby')
@@ -850,7 +840,7 @@ describe('overlayLiveLanes', () => {
   it('places a session into an out-of-tree (sibling) worktree lane by its path', () => {
     // `hermes-agent-ci` is a linked worktree living BESIDE the repo, not under
     // it — repo-root nesting fails, but the existing lane carries its real path.
-    const existing = makeSession('/www/app-ci', { id: 'old' })
+    const existing = makeCwdSession('/www/app-ci', { id: 'old' })
 
     const project = projectNode({
       id: '/www/app',
@@ -868,7 +858,7 @@ describe('overlayLiveLanes', () => {
       ]
     })
 
-    const fresh = makeSession('/www/app-ci', { id: 'fresh' })
+    const fresh = makeCwdSession('/www/app-ci', { id: 'fresh' })
 
     const overlaid = overlayLiveLanes(project, [existing, fresh])
     const ci = overlaid.repos[0].groups.find(g => g.path === '/www/app-ci')
@@ -890,7 +880,7 @@ describe('overlayLiveLanes', () => {
       repos: [{ id: '/www/app', label: 'app', path: '/www/app', sessionCount: 0, groups }]
     })
 
-    const fresh = makeSession('/www/app-retry', { id: 'fresh' })
+    const fresh = makeCwdSession('/www/app-retry', { id: 'fresh' })
 
     const overlaid = overlayLiveLanes(project, [fresh])
     const lane = overlaid.repos[0].groups.find(g => g.path === '/www/app-retry')
@@ -899,8 +889,8 @@ describe('overlayLiveLanes', () => {
   })
 
   it('evicts a deleted/archived snapshot row (and drops the lane once empty)', () => {
-    const a = makeSession('/www/app', { id: 'keep', git_branch: 'main' })
-    const b = makeSession('/www/app/.worktrees/baby', { id: 'gone' })
+    const a = makeCwdSession('/www/app', { id: 'keep', git_branch: 'main' })
+    const b = makeCwdSession('/www/app/.worktrees/baby', { id: 'gone' })
 
     const project = projectNode({
       id: '/www/app',
@@ -927,11 +917,11 @@ describe('overlayLiveLanes', () => {
   })
 
   it('adds a brand-new detached chat to Home, and evicts a deleted one', () => {
-    const existing = makeSession(null, { id: 'old', started_at: 1 })
-    const doomed = makeSession(null, { id: 'gone', started_at: 2 })
+    const existing = makeCwdSession(null, { id: 'old', started_at: 1 })
+    const doomed = makeCwdSession(null, { id: 'gone', started_at: 2 })
     const home = homeNode([existing, doomed])
 
-    const overlaid = overlayLiveLanes(home, [makeSession(null, { id: 'fresh', started_at: 9 })], new Set(['gone']))
+    const overlaid = overlayLiveLanes(home, [makeCwdSession(null, { id: 'fresh', started_at: 9 })], new Set(['gone']))
 
     expect(overlaid.repos[0].groups[0].sessions.map(s => s.id)).toEqual(['fresh', 'old'])
     expect(overlaid.sessionCount).toBe(2)
@@ -943,14 +933,14 @@ describe('overlayLiveLanes', () => {
     // and back out on the next snapshot.
     const home = homeNode([])
 
-    expect(overlayLiveLanes(home, [makeSession('/www/app', { id: 'fresh' })])).toBe(home)
+    expect(overlayLiveLanes(home, [makeCwdSession('/www/app', { id: 'fresh' })])).toBe(home)
   })
 
   it('evicts a session from the main lane when the live overlay places it into a worktree lane', () => {
     // Session was in main when the backend tree was captured, but the live
     // $sessions cache now has it under a worktree cwd. The overlay must place
     // it ONLY in the worktree lane — not both.
-    const session = makeSession('/www/app/.worktrees/feature', { id: 'moved', git_branch: 'feature' })
+    const session = makeCwdSession('/www/app/.worktrees/feature', { id: 'moved', git_branch: 'feature' })
 
     const project = projectNode({
       id: '/www/app',
@@ -989,10 +979,10 @@ describe('overlayLivePreviews', () => {
   it('merges live sessions into a project preview, live first, capped to the limit', () => {
     const project = projectNode({
       id: '/www/app',
-      previewSessions: [makeSession('/www/app', { id: 'old', started_at: 1, last_active: 1 })]
+      previewSessions: [makeCwdSession('/www/app', { id: 'old', started_at: 1, last_active: 1 })]
     })
 
-    const live = [makeSession('/www/app', { id: 'fresh', started_at: 99, last_active: 99 })]
+    const live = [makeCwdSession('/www/app', { id: 'fresh', started_at: 99, last_active: 99 })]
 
     const previews = overlayLivePreviews([project], live, [], 3)
 
@@ -1003,8 +993,8 @@ describe('overlayLivePreviews', () => {
     const project = projectNode({
       id: '/www/app',
       previewSessions: [
-        makeSession('/www/app', { id: 'gone', started_at: 5, last_active: 5 }),
-        makeSession('/www/app', { id: 'old', started_at: 1, last_active: 1 })
+        makeCwdSession('/www/app', { id: 'gone', started_at: 5, last_active: 5 }),
+        makeCwdSession('/www/app', { id: 'old', started_at: 1, last_active: 1 })
       ]
     })
 
@@ -1017,9 +1007,9 @@ describe('overlayLivePreviews', () => {
     const project = projectNode({
       id: '/www/app',
       previewSessions: [
-        makeSession('/www/app', { id: 'newest', last_active: 9, started_at: 9 }),
-        makeSession('/www/app', { id: 'cheap', last_active: 8, started_at: 8 }),
-        makeSession('/www/app', { id: 'priciest', last_active: 1, started_at: 1 })
+        makeCwdSession('/www/app', { id: 'newest', last_active: 9, started_at: 9 }),
+        makeCwdSession('/www/app', { id: 'cheap', last_active: 8, started_at: 8 }),
+        makeCwdSession('/www/app', { id: 'priciest', last_active: 1, started_at: 1 })
       ]
     })
 
@@ -1029,7 +1019,7 @@ describe('overlayLivePreviews', () => {
   })
 
   it('previews a detached session under Home, which no cwd could place', () => {
-    const previews = overlayLivePreviews([homeNode([])], [makeSession(null, { id: 'fresh' })], [], 3)
+    const previews = overlayLivePreviews([homeNode([])], [makeCwdSession(null, { id: 'fresh' })], [], 3)
 
     expect(previews[NO_PROJECT_ID].map(s => s.id)).toEqual(['fresh'])
   })
@@ -1037,8 +1027,8 @@ describe('overlayLivePreviews', () => {
 
 describe('excludeProjectSessions', () => {
   it('drops matching rows from every lane and recounts the subtree', () => {
-    const keep = makeSession('/www/app', { id: 'keep' })
-    const pinnedRow = makeSession('/www/app', { id: 'pinned' })
+    const keep = makeCwdSession('/www/app', { id: 'keep' })
+    const pinnedRow = makeCwdSession('/www/app', { id: 'pinned' })
 
     const project = projectNode({
       id: '/www/app',
@@ -1062,7 +1052,7 @@ describe('excludeProjectSessions', () => {
   })
 
   it('keeps a lane the filter emptied — a worktree is structure, not a row', () => {
-    const pinnedRow = makeSession('/www/app/wt', { id: 'pinned' })
+    const pinnedRow = makeCwdSession('/www/app/wt', { id: 'pinned' })
 
     const project = projectNode({
       id: '/www/app',
@@ -1090,7 +1080,7 @@ describe('excludeProjectSessions', () => {
   it('returns the same node when nothing matches (memo-stable)', () => {
     const project = projectNode({
       id: '/www/app',
-      previewSessions: [makeSession('/www/app', { id: 'keep' })],
+      previewSessions: [makeCwdSession('/www/app', { id: 'keep' })],
       repos: [
         {
           id: '/www/app',
@@ -1098,7 +1088,7 @@ describe('excludeProjectSessions', () => {
           path: '/www/app',
           sessionCount: 1,
           groups: [
-            lane({ id: 'main', isMain: true, label: 'main', sessions: [makeSession('/www/app', { id: 'keep' })] })
+            lane({ id: 'main', isMain: true, label: 'main', sessions: [makeCwdSession('/www/app', { id: 'keep' })] })
           ]
         }
       ],
@@ -1111,7 +1101,7 @@ describe('excludeProjectSessions', () => {
   it('survives the live overlay: a lane left empty by the filter is not pruned', () => {
     // The two run in sequence on an entered project (filter, then overlay), and
     // the overlay drops lanes it empties — it must not take the filter's with it.
-    const pinnedRow = makeSession('/www/app/wt', { id: 'pinned' })
+    const pinnedRow = makeCwdSession('/www/app/wt', { id: 'pinned' })
 
     const project = projectNode({
       id: '/www/app',
diff --git a/apps/desktop/src/app/command-palette/highlight-watcher.test.tsx b/apps/desktop/src/app/command-palette/highlight-watcher.test.tsx
index d2929fcc1e..2e92a24678 100644
--- a/apps/desktop/src/app/command-palette/highlight-watcher.test.tsx
+++ b/apps/desktop/src/app/command-palette/highlight-watcher.test.tsx
@@ -9,18 +9,12 @@ import { render } from '@testing-library/react'
 import { Command } from 'cmdk'
 import { describe, expect, it, vi } from 'vitest'
 
+import { stubMenuDomApis, stubResizeObserver } from '@/test/jsdom'
+
 import { HighlightWatcher } from './highlight-watcher'
 
-// cmdk observes group headings with a ResizeObserver, which jsdom lacks.
-class TestResizeObserver {
-  observe() {}
-  unobserve() {}
-  disconnect() {}
-}
-
-vi.stubGlobal('ResizeObserver', TestResizeObserver)
-
-Element.prototype.scrollIntoView = function scrollIntoView() {}
+stubResizeObserver()
+stubMenuDomApis()
 
 const palette = (onValue: (value: string) => void, onRootValueChange?: (value: string) => void) => (
   <Command onValueChange={onRootValueChange}>
diff --git a/apps/desktop/src/app/contrib/hooks/use-desktop-integrations.test.tsx b/apps/desktop/src/app/contrib/hooks/use-desktop-integrations.test.tsx
index 6a6e47397a..5dd54083cf 100644
--- a/apps/desktop/src/app/contrib/hooks/use-desktop-integrations.test.tsx
+++ b/apps/desktop/src/app/contrib/hooks/use-desktop-integrations.test.tsx
@@ -6,6 +6,8 @@ import { _resetLegacyDiscardForTests } from '@/store/session'
 import type * as WindowsStore from '@/store/windows'
 import type { SessionInfo } from '@/types/hermes'
 
+import { makeSessionInfo } from '../../../test/session-info'
+
 import { useDesktopIntegrations } from './use-desktop-integrations'
 
 // Mutable HUD-window flag so the restore tests can flip the window kind the
@@ -36,24 +38,7 @@ vi.mock('@/store/windows', async importOriginal => {
 const desktopWindow = window as unknown as { hermesDesktop?: Window['hermesDesktop'] }
 const initialHermesDesktop = desktopWindow.hermesDesktop
 
-const session = (over: Partial<SessionInfo> = {}): SessionInfo => ({
-  archived: false,
-  cwd: null,
-  ended_at: null,
-  id: 'live',
-  input_tokens: 0,
-  is_active: false,
-  last_active: 0,
-  message_count: 0,
-  model: null,
-  output_tokens: 0,
-  preview: null,
-  source: null,
-  started_at: 0,
-  title: null,
-  tool_call_count: 0,
-  ...over
-})
+const session = (over: Partial<SessionInfo> = {}): SessionInfo => makeSessionInfo({ id: 'live', ...over })
 
 describe('useDesktopIntegrations', () => {
   let navigate: ReturnType<typeof vi.fn<(...args: unknown[]) => void>>
diff --git a/apps/desktop/src/app/cron/cron-actions.test.ts b/apps/desktop/src/app/cron/cron-actions.test.ts
index d79246a69a..f7cbe89755 100644
--- a/apps/desktop/src/app/cron/cron-actions.test.ts
+++ b/apps/desktop/src/app/cron/cron-actions.test.ts
@@ -12,18 +12,10 @@ vi.mock('@/hermes', () => ({
 
 import { beginCronJobsRequest } from '@/store/cron'
 
+import { deferred } from '../../test/deferred'
+
 import { mutateAndRefreshCronJobs, refreshCronJobs, triggerAndRefreshCronJobs } from './cron-actions'
 
-function deferred<T>() {
-  let resolve!: (value: T) => void
-
-  const promise = new Promise<T>(res => {
-    resolve = res
-  })
-
-  return { promise, resolve }
-}
-
 describe('triggerAndRefreshCronJobs', () => {
   beforeEach(() => {
     getApiRequestConnection.mockReset()
diff --git a/apps/desktop/src/app/right-sidebar/terminal/persistent.test.tsx b/apps/desktop/src/app/right-sidebar/terminal/persistent.test.tsx
index a9c013301b..5cf40b6ee6 100644
--- a/apps/desktop/src/app/right-sidebar/terminal/persistent.test.tsx
+++ b/apps/desktop/src/app/right-sidebar/terminal/persistent.test.tsx
@@ -1,10 +1,11 @@
-import { act, type ReactNode } from 'react'
-import { createRoot, type Root } from 'react-dom/client'
+import { act } from 'react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 import { hiddenPaneProps, PANE_HIDDEN_ATTR } from '@/components/pane-shell/pane-visibility'
 import { $paneStates } from '@/store/panes'
+import { reactRoot } from '@/test/react-root'
 
+import { installWindowStateBridge, setDocumentHidden, type WindowStateBridge } from '../../../test/window-state'
 import { $terminalTakeover } from '../store'
 
 import { PersistentTerminal, TerminalSlot } from './persistent'
@@ -24,54 +25,8 @@ vi.mock('./workspace', () => ({
 let resizeObserverCallback: ResizeObserverCallback | null = null
 let mutationObserverCallback: MutationCallback | null = null
 let mutationObserveCalls: Array<{ options?: MutationObserverInit; target: Node }> = []
-let root: Root | null = null
-let container: HTMLDivElement | null = null
-let windowStateCallback: ((payload: { isMinimized?: boolean; isVisible?: boolean }) => void) | null = null
-
-function render(ui: ReactNode) {
-  container = document.createElement('div')
-  document.body.append(container)
-  root = createRoot(container)
-
-  act(() => {
-    root!.render(ui)
-  })
-}
-
-function cleanup() {
-  if (root) {
-    act(() => {
-      root!.unmount()
-    })
-  }
-
-  container?.remove()
-  root = null
-  container = null
-}
-
-function setVisibility(hidden: boolean) {
-  Object.defineProperty(document, 'hidden', { configurable: true, value: hidden })
-  Object.defineProperty(document, 'visibilityState', { configurable: true, value: hidden ? 'hidden' : 'visible' })
-}
-
-function installWindowStateBridge() {
-  windowStateCallback = null
-  Object.defineProperty(window, 'hermesDesktop', {
-    configurable: true,
-    value: {
-      onWindowStateChanged: vi.fn((callback: typeof windowStateCallback) => {
-        windowStateCallback = callback
-
-        return () => {
-          if (windowStateCallback === callback) {
-            windowStateCallback = null
-          }
-        }
-      })
-    }
-  })
-}
+const mount = reactRoot()
+let windowState: WindowStateBridge
 
 function rect(top: number, left: number, width: number, height: number): DOMRect {
   return {
@@ -146,9 +101,9 @@ function HiddenPaneHarness({ hidden }: { hidden: boolean }) {
 describe('PersistentTerminal rect tracking', () => {
   beforeEach(() => {
     ;(globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
-    setVisibility(false)
+    setDocumentHidden(false)
     vi.spyOn(document, 'hasFocus').mockReturnValue(true)
-    installWindowStateBridge()
+    windowState = installWindowStateBridge()
     resizeObserverCallback = null
     mutationObserverCallback = null
     mutationObserveCalls = []
@@ -181,11 +136,11 @@ describe('PersistentTerminal rect tracking', () => {
   })
 
   afterEach(() => {
-    cleanup()
+    mount.unmount()
     $terminalTakeover.set(false)
     vi.unstubAllGlobals()
     vi.restoreAllMocks()
-    setVisibility(false)
+    setDocumentHidden(false)
     delete (window as unknown as { hermesDesktop?: unknown }).hermesDesktop
   })
 
@@ -194,7 +149,7 @@ describe('PersistentTerminal rect tracking', () => {
     let currentRect = rect(10, 20, 200, 100)
     vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(() => currentRect)
 
-    render(<Harness />)
+    mount.render(<Harness />)
 
     expect(raf.request).toHaveBeenCalledTimes(1)
 
@@ -231,7 +186,7 @@ describe('PersistentTerminal rect tracking', () => {
     let currentRect = rect(10, 20, 200, 100)
     vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(() => currentRect)
 
-    render(<Harness />)
+    mount.render(<Harness />)
 
     expect(mutationObserveCalls.length).toBeGreaterThan(0)
     expect(mutationObserveCalls.every(call => call.options?.subtree === false)).toBe(true)
@@ -240,7 +195,7 @@ describe('PersistentTerminal rect tracking', () => {
       raf.runNext()
     })
 
-    const overlay = container!.lastElementChild as HTMLElement
+    const overlay = mount.container!.lastElementChild as HTMLElement
     expect(overlay.style.top).toBe('10px')
     expect(overlay.style.left).toBe('20px')
     expect(raf.pending()).toBe(0)
@@ -271,7 +226,7 @@ describe('PersistentTerminal rect tracking', () => {
     const before = $paneStates.get()
     vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockReturnValue(rect(10, 20, 200, 100))
 
-    render(<Harness />)
+    mount.render(<Harness />)
     raf.runNext()
     expect(raf.pending()).toBe(0)
 
@@ -291,12 +246,12 @@ describe('PersistentTerminal rect tracking', () => {
     const raf = installRaf()
     vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockReturnValue(rect(10, 20, 200, 100))
 
-    render(<Harness />)
+    mount.render(<Harness />)
 
     expect(raf.request).toHaveBeenCalledTimes(1)
 
     act(() => {
-      windowStateCallback?.({ isMinimized: true, isVisible: false })
+      windowState.emit({ isMinimized: true, isVisible: false })
     })
 
     expect(raf.cancel).toHaveBeenCalledTimes(1)
@@ -309,7 +264,7 @@ describe('PersistentTerminal rect tracking', () => {
     expect(raf.request).toHaveBeenCalledTimes(1)
 
     act(() => {
-      windowStateCallback?.({ isMinimized: false, isVisible: true })
+      windowState.emit({ isMinimized: false, isVisible: true })
     })
 
     expect(raf.request).toHaveBeenCalledTimes(2)
@@ -319,7 +274,7 @@ describe('PersistentTerminal rect tracking', () => {
     const raf = installRaf()
     vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockReturnValue(rect(10, 20, 200, 100))
 
-    render(<Harness />)
+    mount.render(<Harness />)
     expect(raf.pending()).toBe(1)
 
     act(() => window.dispatchEvent(new Event('blur')))
@@ -328,7 +283,7 @@ describe('PersistentTerminal rect tracking', () => {
     act(() => window.dispatchEvent(new Event('focus')))
     expect(raf.pending()).toBe(1)
 
-    cleanup()
+    mount.unmount()
     expect(raf.pending()).toBe(0)
 
     act(() => {
@@ -344,7 +299,7 @@ describe('PersistentTerminal rect tracking', () => {
     vi.mocked(document.hasFocus).mockReturnValue(false)
     vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockReturnValue(rect(10, 20, 200, 100))
 
-    render(<Harness />)
+    mount.render(<Harness />)
 
     expect(raf.request).not.toHaveBeenCalled()
 
@@ -358,10 +313,10 @@ describe('PersistentTerminal rect tracking', () => {
     vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockReturnValue(rect(10, 20, 200, 100))
     $terminalTakeover.set(true)
 
-    render(<HiddenPaneHarness hidden={false} />)
+    mount.render(<HiddenPaneHarness hidden={false} />)
 
-    const overlay = container!.lastElementChild as HTMLElement
-    const workspace = container!.querySelector('[data-testid="terminal-workspace"]')
+    const overlay = mount.container!.lastElementChild as HTMLElement
+    const workspace = mount.container!.querySelector('[data-testid="terminal-workspace"]')
 
     expect(overlay.style.visibility).toBe('visible')
     expect(overlay.style.opacity).toBe('1')
@@ -377,7 +332,7 @@ describe('PersistentTerminal rect tracking', () => {
     expect(raf.pending()).toBe(0)
 
     act(() => {
-      root!.render(<HiddenPaneHarness hidden />)
+      mount.root!.render(<HiddenPaneHarness hidden />)
       mutationObserverCallback?.([], {} as MutationObserver)
     })
     expect(raf.pending()).toBe(1)
@@ -389,7 +344,7 @@ describe('PersistentTerminal rect tracking', () => {
     expect(overlay.style.visibility).toBe('hidden')
     expect(overlay.style.opacity).toBe('0')
     expect(overlay.style.pointerEvents).toBe('none')
-    expect(container!.querySelector('[data-testid="terminal-workspace"]')).toBe(workspace)
+    expect(mount.container!.querySelector('[data-testid="terminal-workspace"]')).toBe(workspace)
 
     act(() => {
       raf.runNext()
@@ -397,7 +352,7 @@ describe('PersistentTerminal rect tracking', () => {
     expect(raf.pending()).toBe(0)
 
     act(() => {
-      root!.render(<HiddenPaneHarness hidden={false} />)
+      mount.root!.render(<HiddenPaneHarness hidden={false} />)
       mutationObserverCallback?.([], {} as MutationObserver)
     })
 
@@ -408,6 +363,6 @@ describe('PersistentTerminal rect tracking', () => {
     expect(overlay.style.visibility).toBe('visible')
     expect(overlay.style.opacity).toBe('1')
     expect(overlay.style.pointerEvents).toBe('auto')
-    expect(container!.querySelector('[data-testid="terminal-workspace"]')).toBe(workspace)
+    expect(mount.container!.querySelector('[data-testid="terminal-workspace"]')).toBe(workspace)
   })
 })
diff --git a/apps/desktop/src/app/session/hooks/use-cwd-actions.test.tsx b/apps/desktop/src/app/session/hooks/use-cwd-actions.test.tsx
index 213c5d2054..964fe142f8 100644
--- a/apps/desktop/src/app/session/hooks/use-cwd-actions.test.tsx
+++ b/apps/desktop/src/app/session/hooks/use-cwd-actions.test.tsx
@@ -13,20 +13,12 @@ import {
   setNewChatWorkspaceTarget
 } from '@/store/session'
 
+import { deferred } from '../../../test/deferred'
+
 import { useCwdActions } from './use-cwd-actions'
 
 type CwdActionsHandle = ReturnType<typeof useCwdActions>
 
-function deferred<T>() {
-  let resolve!: (value: T) => void
-
-  const promise = new Promise<T>(done => {
-    resolve = done
-  })
-
-  return { promise, resolve }
-}
-
 function Harness({
   activeSessionIdRef,
   onReady,
diff --git a/apps/desktop/src/app/session/hooks/use-hermes-config.test.ts b/apps/desktop/src/app/session/hooks/use-hermes-config.test.ts
index ca0ca4dc0a..9003ad3491 100644
--- a/apps/desktop/src/app/session/hooks/use-hermes-config.test.ts
+++ b/apps/desktop/src/app/session/hooks/use-hermes-config.test.ts
@@ -18,6 +18,8 @@ import {
   setDefaultReasoningEffort
 } from '@/store/session'
 
+import { deferred } from '../../../test/deferred'
+
 import { useHermesConfig } from './use-hermes-config'
 
 vi.mock('@/hermes', () => ({
@@ -27,16 +29,6 @@ vi.mock('@/hermes', () => ({
 
 const WORKSPACE_CWD_KEY = 'hermes.desktop.workspace-cwd'
 
-function deferred<T>() {
-  let resolve!: (value: T | PromiseLike<T>) => void
-
-  const promise = new Promise<T>(done => {
-    resolve = done
-  })
-
-  return { promise, resolve }
-}
-
 const mockConfig = (config: Record<string, unknown>) =>
   vi.mocked(getHermesConfig).mockResolvedValue(config as Awaited<ReturnType<typeof getHermesConfig>>)
 
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/agent-init-error.test.tsx b/apps/desktop/src/app/session/hooks/use-message-stream/agent-init-error.test.tsx
index 86875e42f3..3be0467bd8 100644
--- a/apps/desktop/src/app/session/hooks/use-message-stream/agent-init-error.test.tsx
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/agent-init-error.test.tsx
@@ -1,59 +1,24 @@
-import { QueryClient } from '@tanstack/react-query'
-import { act, cleanup, render, waitFor } from '@testing-library/react'
-import { useEffect, useRef } from 'react'
+import { act, cleanup } from '@testing-library/react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
-import type { ClientSessionState } from '@/app/types'
 import { textPart } from '@/lib/chat-messages'
 import { createClientSessionState } from '@/lib/chat-runtime'
 import { $notifications, clearNotifications } from '@/store/notifications'
-import type { RpcEvent } from '@/types/hermes'
 
-import { useMessageStream } from './index'
+import { type MessageStreamHarness, renderMessageStream } from './test-harness'
 
 const SID = 'rt-new-session'
 
-let handleEvent: ((event: RpcEvent) => void) | null = null
-let sessionStates: Map<string, ClientSessionState> | null = null
+let stream: MessageStreamHarness
 
-function Harness() {
-  const activeSessionIdRef = useRef<string | null>(SID)
-  const sessionStateByRuntimeIdRef = useRef(new Map<string, ClientSessionState>())
-  const queryClientRef = useRef(new QueryClient())
-
-  const stream = useMessageStream({
-    activeSessionIdRef,
-    hydrateFromStoredSession: vi.fn(async () => undefined),
-    queryClient: queryClientRef.current,
-    refreshHermesConfig: vi.fn(async () => undefined),
-    refreshSessions: vi.fn(async () => undefined),
-    sessionStateByRuntimeIdRef,
-    updateSessionState: (sessionId, updater) => {
-      const current = sessionStateByRuntimeIdRef.current.get(sessionId) ?? createClientSessionState()
-      const next = updater(current)
-      sessionStateByRuntimeIdRef.current.set(sessionId, next)
-
-      return next
-    }
-  })
-
-  useEffect(() => {
-    handleEvent = stream.handleGatewayEvent
-    sessionStates = sessionStateByRuntimeIdRef.current
-  }, [stream.handleGatewayEvent])
-
-  return null
-}
-
-async function mountStream() {
-  render(<Harness />)
-  await waitFor(() => expect(handleEvent).not.toBeNull())
+function mountStream() {
+  stream = renderMessageStream(SID)
 }
 
 /** Seed the session as it looks right after a first-message submit: the
  *  optimistic user row is present, the turn is awaiting its response. */
 function seedOptimisticFirstMessage() {
-  sessionStates!.set(SID, {
+  stream.states.set(SID, {
     ...createClientSessionState('stored-new-session', [
       { id: 'user-123-abc', role: 'user', parts: [textPart('first message of a new chat')] }
     ]),
@@ -64,8 +29,6 @@ function seedOptimisticFirstMessage() {
 
 describe('useMessageStream agent-init error surfacing (#63078)', () => {
   beforeEach(() => {
-    handleEvent = null
-    sessionStates = null
     clearNotifications()
   })
 
@@ -76,11 +39,11 @@ describe('useMessageStream agent-init error surfacing (#63078)', () => {
   })
 
   it('renders an agent-init failure as a visible in-transcript error and keeps the optimistic first message', async () => {
-    await mountStream()
+    mountStream()
     seedOptimisticFirstMessage()
 
     act(() =>
-      handleEvent!({
+      stream.handleEvent({
         payload: {
           message:
             'agent initialization timed out after 601s — your message was not sent; retry once the session is ready'
@@ -90,7 +53,7 @@ describe('useMessageStream agent-init error surfacing (#63078)', () => {
       })
     )
 
-    const state = sessionStates!.get(SID)!
+    const state = stream.state()
 
     // The user's optimistic first message must survive — the failure mode of
     // #63078 was the message silently vanishing into a blank session.
@@ -111,19 +74,19 @@ describe('useMessageStream agent-init error surfacing (#63078)', () => {
     expect($notifications.get().some(n => n.kind === 'error' && n.message?.includes('was not sent'))).toBe(true)
   })
 
-  it('renders the pre-ready cancel error event (#65567 server emit) visibly', async () => {
-    await mountStream()
+  it('renders the pre-ready cancel error event (#65567 server emit) visibly', () => {
+    mountStream()
     seedOptimisticFirstMessage()
 
     act(() =>
-      handleEvent!({
+      stream.handleEvent({
         payload: { message: 'Turn cancelled before the agent was ready' },
         session_id: SID,
         type: 'error'
       })
     )
 
-    const state = sessionStates!.get(SID)!
+    const state = stream.state()
     expect(state.messages.some(m => m.role === 'assistant' && m.error?.includes('cancelled'))).toBe(true)
     expect(state.messages.some(m => m.id === 'user-123-abc')).toBe(true)
     expect(state.busy).toBe(false)
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/approval-mode-event.test.tsx b/apps/desktop/src/app/session/hooks/use-message-stream/approval-mode-event.test.tsx
index a8d7fdb551..fcd5126104 100644
--- a/apps/desktop/src/app/session/hooks/use-message-stream/approval-mode-event.test.tsx
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/approval-mode-event.test.tsx
@@ -1,55 +1,20 @@
-import { QueryClient } from '@tanstack/react-query'
-import { act, cleanup, render, waitFor } from '@testing-library/react'
-import { useEffect, useRef } from 'react'
+import { act, cleanup } from '@testing-library/react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
-import type { ClientSessionState } from '@/app/types'
-import { createClientSessionState } from '@/lib/chat-runtime'
 import { $approvalModes, approvalModeForProfile } from '@/store/approval-mode'
 import { $activeGatewayProfile } from '@/store/profile'
-import type { RpcEvent } from '@/types/hermes'
 
-import { useMessageStream } from './index'
+import { type MessageStreamHarness, renderMessageStream } from './test-harness'
 
 const ACTIVE_SID = 'session-active'
-let handleEvent: ((event: RpcEvent) => void) | null = null
+let stream: MessageStreamHarness
 
-function Harness() {
-  const activeSessionIdRef = useRef<string | null>(ACTIVE_SID)
-  const sessionStateByRuntimeIdRef = useRef(new Map<string, ClientSessionState>())
-  const queryClientRef = useRef(new QueryClient())
-
-  const stream = useMessageStream({
-    activeSessionIdRef,
-    hydrateFromStoredSession: vi.fn(async () => undefined),
-    queryClient: queryClientRef.current,
-    refreshHermesConfig: vi.fn(async () => undefined),
-    refreshSessions: vi.fn(async () => undefined),
-    sessionStateByRuntimeIdRef,
-    updateSessionState: (sessionId, updater) => {
-      const current = sessionStateByRuntimeIdRef.current.get(sessionId) ?? createClientSessionState()
-      const next = updater(current)
-      sessionStateByRuntimeIdRef.current.set(sessionId, next)
-
-      return next
-    }
-  })
-
-  useEffect(() => {
-    handleEvent = stream.handleGatewayEvent
-  }, [stream.handleGatewayEvent])
-
-  return null
-}
-
-async function mountStream() {
-  render(<Harness />)
-  await waitFor(() => expect(handleEvent).not.toBeNull())
+function mountStream() {
+  stream = renderMessageStream(ACTIVE_SID)
 }
 
 describe('live session.info approval mode reconciliation', () => {
   beforeEach(() => {
-    handleEvent = null
     $approvalModes.set({})
     $activeGatewayProfile.set('work')
   })
@@ -59,11 +24,11 @@ describe('live session.info approval mode reconciliation', () => {
     vi.restoreAllMocks()
   })
 
-  it('reconciles an active-session event under its source gateway profile', async () => {
-    await mountStream()
+  it('reconciles an active-session event under its source gateway profile', () => {
+    mountStream()
 
     act(() =>
-      handleEvent!({
+      stream.handleEvent({
         payload: { approval_mode: 'off' },
         profile: 'work',
         session_id: ACTIVE_SID,
@@ -75,11 +40,11 @@ describe('live session.info approval mode reconciliation', () => {
     expect(approvalModeForProfile('default')).toBe('smart')
   })
 
-  it('ignores stale session.info from a non-active session on the active gateway', async () => {
-    await mountStream()
+  it('ignores stale session.info from a non-active session on the active gateway', () => {
+    mountStream()
 
     act(() =>
-      handleEvent!({
+      stream.handleEvent({
         payload: { approval_mode: 'off' },
         profile: 'work',
         session_id: 'session-stale',
@@ -90,11 +55,11 @@ describe('live session.info approval mode reconciliation', () => {
     expect(approvalModeForProfile('work')).toBe('smart')
   })
 
-  it('does not cache an event under a different active profile when its source profile is absent', async () => {
-    await mountStream()
+  it('does not cache an event under a different active profile when its source profile is absent', () => {
+    mountStream()
     $activeGatewayProfile.set('personal')
 
-    act(() => handleEvent!({ payload: { approval_mode: 'off' }, session_id: ACTIVE_SID, type: 'session.info' }))
+    act(() => stream.handleEvent({ payload: { approval_mode: 'off' }, session_id: ACTIVE_SID, type: 'session.info' }))
 
     expect(approvalModeForProfile('personal')).toBe('smart')
     expect(approvalModeForProfile('work')).toBe('smart')
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/clarify-hydration.test.tsx b/apps/desktop/src/app/session/hooks/use-message-stream/clarify-hydration.test.tsx
index b64171cc7e..8f2fe2defc 100644
--- a/apps/desktop/src/app/session/hooks/use-message-stream/clarify-hydration.test.tsx
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/clarify-hydration.test.tsx
@@ -1,15 +1,10 @@
-import { QueryClient } from '@tanstack/react-query'
-import { act, cleanup, render, waitFor } from '@testing-library/react'
-import { type MutableRefObject, useEffect, useRef } from 'react'
+import { act, cleanup } from '@testing-library/react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
-import type { ClientSessionState } from '@/app/types'
-import { createClientSessionState } from '@/lib/chat-runtime'
 import { $clarifyRequests, clearClarifyRequest } from '@/store/clarify'
 import { onScrollToBottomRequest } from '@/store/thread-scroll'
-import type { RpcEvent } from '@/types/hermes'
 
-import { useMessageStream } from './index'
+import { type MessageStreamHarness, renderMessageStream } from './test-harness'
 
 // A `clarify.request` must leave an answerable inline row even when the
 // `tool.start` that normally mounts it was missed (stream reconnect /
@@ -18,62 +13,29 @@ import { useMessageStream } from './index'
 
 const SID = 'session-1'
 
-let handleEvent: ((event: RpcEvent) => void) | null = null
-let stateRef: MutableRefObject<Map<string, ClientSessionState>> | null = null
+let stream: MessageStreamHarness
 let stopScrollListener: (() => void) | null = null
 
 const scrollToBottom = vi.fn()
 
-function Harness() {
-  const activeSessionIdRef = useRef<string | null>(SID)
-  const sessionStateByRuntimeIdRef = useRef(new Map<string, ClientSessionState>())
-  const queryClientRef = useRef(new QueryClient())
-
-  const stream = useMessageStream({
-    activeSessionIdRef,
-    hydrateFromStoredSession: vi.fn(async () => undefined),
-    queryClient: queryClientRef.current,
-    refreshHermesConfig: vi.fn(async () => undefined),
-    refreshSessions: vi.fn(async () => undefined),
-    sessionStateByRuntimeIdRef,
-    updateSessionState: (sessionId, updater) => {
-      const current = sessionStateByRuntimeIdRef.current.get(sessionId) ?? createClientSessionState()
-      const next = updater(current)
-      sessionStateByRuntimeIdRef.current.set(sessionId, next)
-
-      return next
-    }
-  })
-
-  useEffect(() => {
-    handleEvent = stream.handleGatewayEvent
-    stateRef = sessionStateByRuntimeIdRef
-  }, [stream.handleGatewayEvent])
-
-  return null
-}
-
-async function mountStream() {
-  render(<Harness />)
-  await waitFor(() => expect(handleEvent).not.toBeNull())
+function mountStream() {
+  stream = renderMessageStream(SID)
 }
 
 const clarifyRequest = (payload: Record<string, unknown>) =>
-  act(() => handleEvent!({ payload, session_id: SID, type: 'clarify.request' }))
+  act(() => stream.handleEvent({ payload, session_id: SID, type: 'clarify.request' }))
 
 const toolStart = (payload: Record<string, unknown>) =>
-  act(() => handleEvent!({ payload, session_id: SID, type: 'tool.start' }))
+  act(() => stream.handleEvent({ payload, session_id: SID, type: 'tool.start' }))
 
 function clarifyParts() {
-  const messages = stateRef?.current.get(SID)?.messages ?? []
+  const messages = stream.state().messages ?? []
 
   return messages.flatMap(m => m.parts).filter(p => p.type === 'tool-call' && p.toolName === 'clarify')
 }
 
 describe('clarify.request stream hydration', () => {
   beforeEach(() => {
-    handleEvent = null
-    stateRef = null
     clearClarifyRequest()
     scrollToBottom.mockClear()
     stopScrollListener = onScrollToBottomRequest(scrollToBottom)
@@ -87,8 +49,8 @@ describe('clarify.request stream hydration', () => {
     vi.restoreAllMocks()
   })
 
-  it('mounts an answerable clarify row when the tool.start row was missed', async () => {
-    await mountStream()
+  it('mounts an answerable clarify row when the tool.start row was missed', () => {
+    mountStream()
 
     clarifyRequest({ choices: ['yes', 'no'], question: 'Ship it?', request_id: 'req-1' })
 
@@ -101,19 +63,19 @@ describe('clarify.request stream hydration', () => {
     })
   })
 
-  it('reveals a clarify prompt raised by the active session', async () => {
-    await mountStream()
+  it('reveals a clarify prompt raised by the active session', () => {
+    mountStream()
 
     clarifyRequest({ choices: ['yes', 'no'], question: 'Ship it?', request_id: 'req-reveal' })
 
     expect(scrollToBottom).toHaveBeenCalledOnce()
   })
 
-  it('does not move the active thread for a background session clarify', async () => {
-    await mountStream()
+  it('does not move the active thread for a background session clarify', () => {
+    mountStream()
 
     act(() =>
-      handleEvent!({
+      stream.handleEvent({
         payload: { choices: ['yes', 'no'], question: 'Ship it?', request_id: 'req-background' },
         session_id: 'session-background',
         type: 'clarify.request'
@@ -123,8 +85,8 @@ describe('clarify.request stream hydration', () => {
     expect(scrollToBottom).not.toHaveBeenCalled()
   })
 
-  it('preserves multi-select through the store and hydrated tool row', async () => {
-    await mountStream()
+  it('preserves multi-select through the store and hydrated tool row', () => {
+    mountStream()
 
     clarifyRequest({
       choices: ['read', 'write'],
@@ -149,8 +111,8 @@ describe('clarify.request stream hydration', () => {
     })
   })
 
-  it('merges with the real tool.start row even though its id differs from the request id', async () => {
-    await mountStream()
+  it('merges with the real tool.start row even though its id differs from the request id', () => {
+    mountStream()
 
     // Reality: tool.start carries the model's tool_call_id, clarify.request a
     // separately-generated request_id. They must still collapse to ONE card
@@ -161,8 +123,8 @@ describe('clarify.request stream hydration', () => {
     expect(clarifyParts()).toHaveLength(1)
   })
 
-  it('does not duplicate when clarify.request arrives before the tool.start row', async () => {
-    await mountStream()
+  it('does not duplicate when clarify.request arrives before the tool.start row', () => {
+    mountStream()
 
     clarifyRequest({ choices: ['a'], question: 'Pick', request_id: 'req-3' })
     toolStart({ args: { choices: ['a'], question: 'Pick' }, name: 'clarify', tool_id: 'call-xyz' })
@@ -170,8 +132,8 @@ describe('clarify.request stream hydration', () => {
     expect(clarifyParts()).toHaveLength(1)
   })
 
-  it('merges a BATCH tool.start row with its clarify.request (no top-level question)', async () => {
-    await mountStream()
+  it('merges a BATCH tool.start row with its clarify.request (no top-level question)', () => {
+    mountStream()
 
     // The batch shape: tool args carry `questions`, no top-level `question`.
     // The correlation key must come from the question list, or the two ids
@@ -190,10 +152,11 @@ describe('clarify.request stream hydration', () => {
     })
 
     expect(clarifyParts()).toHaveLength(1)
+    expect($clarifyRequests.get()[SID]?.questions).toHaveLength(2)
   })
 
-  it('does not duplicate when the batch clarify.request arrives before tool.start', async () => {
-    await mountStream()
+  it('does not duplicate when the batch clarify.request arrives before tool.start', () => {
+    mountStream()
 
     clarifyRequest({
       questions: [
@@ -209,5 +172,6 @@ describe('clarify.request stream hydration', () => {
     })
 
     expect(clarifyParts()).toHaveLength(1)
+    expect($clarifyRequests.get()[SID]?.questions).toHaveLength(2)
   })
 })
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/compaction-event.test.tsx b/apps/desktop/src/app/session/hooks/use-message-stream/compaction-event.test.tsx
index 9fcabadcd1..0343dd37e3 100644
--- a/apps/desktop/src/app/session/hooks/use-message-stream/compaction-event.test.tsx
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/compaction-event.test.tsx
@@ -1,59 +1,25 @@
-import { QueryClient } from '@tanstack/react-query'
-import { act, cleanup, render, waitFor } from '@testing-library/react'
-import { useEffect, useRef } from 'react'
+import { act, cleanup } from '@testing-library/react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
-import type { ClientSessionState } from '@/app/types'
-import { createClientSessionState } from '@/lib/chat-runtime'
 import { $compactingSessions, setSessionCompacting } from '@/store/compaction'
 import type { RpcEvent } from '@/types/hermes'
 
-import { useMessageStream } from './index'
+import { type MessageStreamHarness, renderMessageStream } from './test-harness'
 
 const SID = 'session-1'
 const OTHER_SID = 'session-2'
-let handleEvent: ((event: RpcEvent) => void) | null = null
+let stream: MessageStreamHarness
 
-function Harness() {
-  const activeSessionIdRef = useRef<string | null>(SID)
-  const sessionStateByRuntimeIdRef = useRef(new Map<string, ClientSessionState>())
-  const queryClientRef = useRef(new QueryClient())
-
-  const stream = useMessageStream({
-    activeSessionIdRef,
-    hydrateFromStoredSession: vi.fn(async () => undefined),
-    queryClient: queryClientRef.current,
-    refreshHermesConfig: vi.fn(async () => undefined),
-    refreshSessions: vi.fn(async () => undefined),
-    sessionStateByRuntimeIdRef,
-    updateSessionState: (sessionId, updater) => {
-      const current = sessionStateByRuntimeIdRef.current.get(sessionId) ?? createClientSessionState()
-      const next = updater(current)
-      sessionStateByRuntimeIdRef.current.set(sessionId, next)
-
-      return next
-    }
-  })
-
-  useEffect(() => {
-    handleEvent = stream.handleGatewayEvent
-  }, [stream.handleGatewayEvent])
-
-  return null
-}
-
-async function mountStream() {
-  render(<Harness />)
-  await waitFor(() => expect(handleEvent).not.toBeNull())
+function mountStream() {
+  stream = renderMessageStream(SID)
 }
 
 function emit(type: RpcEvent['type'], payload: RpcEvent['payload'] = {}) {
-  act(() => handleEvent!({ payload, session_id: SID, type }))
+  act(() => stream.handleEvent({ payload, session_id: SID, type }))
 }
 
 describe('useMessageStream compaction lifecycle', () => {
   beforeEach(() => {
-    handleEvent = null
     $compactingSessions.set({})
   })
 
@@ -68,8 +34,8 @@ describe('useMessageStream compaction lifecycle', () => {
     ['thinking.delta', { text: 'still working' }],
     ['reasoning.delta', { text: 'thinking again' }],
     ['tool.start', { name: 'terminal', tool_id: 'tool-1' }]
-  ] as const)('clears the stale compaction phase when %s resumes the turn', async (type, payload) => {
-    await mountStream()
+  ] as const)('clears the stale compaction phase when %s resumes the turn', (type, payload) => {
+    mountStream()
     setSessionCompacting(OTHER_SID, true)
 
     emit('status.update', { kind: 'compacting' })
@@ -80,8 +46,8 @@ describe('useMessageStream compaction lifecycle', () => {
     expect($compactingSessions.get()).toEqual({ [OTHER_SID]: true })
   })
 
-  it('clears the compaction phase on the structured completion edge', async () => {
-    await mountStream()
+  it('clears the compaction phase on the structured completion edge', () => {
+    mountStream()
     setSessionCompacting(OTHER_SID, true)
 
     emit('status.update', { kind: 'compacting' })
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/composer-model-event.test.tsx b/apps/desktop/src/app/session/hooks/use-message-stream/composer-model-event.test.tsx
index 7d8e4f69aa..245b168a4e 100644
--- a/apps/desktop/src/app/session/hooks/use-message-stream/composer-model-event.test.tsx
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/composer-model-event.test.tsx
@@ -1,10 +1,6 @@
-import { QueryClient } from '@tanstack/react-query'
-import { act, cleanup, render, waitFor } from '@testing-library/react'
-import { useEffect, useRef } from 'react'
+import { act, cleanup } from '@testing-library/react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
-import type { ClientSessionState } from '@/app/types'
-import { createClientSessionState } from '@/lib/chat-runtime'
 import {
   $currentModel,
   $currentProvider,
@@ -12,50 +8,17 @@ import {
   setCurrentModelSource,
   setCurrentProvider
 } from '@/store/session'
-import type { RpcEvent } from '@/types/hermes'
 
-import { useMessageStream } from './index'
+import { type MessageStreamHarness, renderMessageStream } from './test-harness'
 
-let handleEvent: ((event: RpcEvent) => void) | null = null
+let stream: MessageStreamHarness
 
-function Harness({ activeSessionId }: { activeSessionId: string | null }) {
-  const sessionIdRef = useRef<string | null>(activeSessionId)
-  const sessionStateByRuntimeIdRef = useRef(new Map<string, ClientSessionState>())
-  const queryClientRef = useRef(new QueryClient())
-
-  sessionIdRef.current = activeSessionId
-
-  const stream = useMessageStream({
-    activeSessionIdRef: sessionIdRef,
-    hydrateFromStoredSession: vi.fn(async () => undefined),
-    queryClient: queryClientRef.current,
-    refreshHermesConfig: vi.fn(async () => undefined),
-    refreshSessions: vi.fn(async () => undefined),
-    sessionStateByRuntimeIdRef,
-    updateSessionState: (sessionId, updater) => {
-      const current = sessionStateByRuntimeIdRef.current.get(sessionId) ?? createClientSessionState()
-      const next = updater(current)
-      sessionStateByRuntimeIdRef.current.set(sessionId, next)
-
-      return next
-    }
-  })
-
-  useEffect(() => {
-    handleEvent = stream.handleGatewayEvent
-  }, [stream.handleGatewayEvent])
-
-  return null
-}
-
-async function mountStream(activeSessionId: string | null) {
-  render(<Harness activeSessionId={activeSessionId} />)
-  await waitFor(() => expect(handleEvent).not.toBeNull())
+function mountStream(activeSessionId: string | null) {
+  stream = renderMessageStream(activeSessionId)
 }
 
 describe('session.info does not clobber composer model selection', () => {
   beforeEach(() => {
-    handleEvent = null
     setCurrentModel('deepseek-v4-flash')
     setCurrentProvider('deepseek')
     setCurrentModelSource('manual')
@@ -69,11 +32,11 @@ describe('session.info does not clobber composer model selection', () => {
     setCurrentModelSource('')
   })
 
-  it('keeps a sticky manual pick when a global session.info carries the profile default', async () => {
-    await mountStream(null)
+  it('keeps a sticky manual pick when a global session.info carries the profile default', () => {
+    mountStream(null)
 
     act(() =>
-      handleEvent!({
+      stream.handleEvent({
         payload: { model: 'deepseek-chat', provider: 'deepseek' },
         type: 'session.info'
       })
@@ -83,11 +46,11 @@ describe('session.info does not clobber composer model selection', () => {
     expect($currentProvider.get()).toBe('deepseek')
   })
 
-  it('keeps the composer pick when an unscoped session.info arrives with no live session', async () => {
-    await mountStream(null)
+  it('keeps the composer pick when an unscoped session.info arrives with no live session', () => {
+    mountStream(null)
 
     act(() =>
-      handleEvent!({
+      stream.handleEvent({
         payload: { cwd: '/tmp/project', model: 'deepseek-chat', provider: 'deepseek' },
         type: 'session.info'
       })
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/delta-flush.test.tsx b/apps/desktop/src/app/session/hooks/use-message-stream/delta-flush.test.tsx
index a630d9dcf3..73d2c7e65d 100644
--- a/apps/desktop/src/app/session/hooks/use-message-stream/delta-flush.test.tsx
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/delta-flush.test.tsx
@@ -9,10 +9,12 @@ import { createClientSessionState } from '@/lib/chat-runtime'
 
 import { useSessionStateCache } from '../use-session-state-cache'
 
+import { type MessageStreamHarness, renderMessageStream } from './test-harness'
+
 import { useMessageStream } from './index'
 
 const SID = 'session-1'
-let appendAssistantDelta: ((sessionId: string, delta: string) => void) | null = null
+let stream: MessageStreamHarness
 let states: Map<string, ClientSessionState>
 type UpdateSessionState = (
   sessionId: string,
@@ -21,44 +23,17 @@ type UpdateSessionState = (
 ) => ClientSessionState
 let updateSessionState: ReturnType<typeof vi.fn<UpdateSessionState>>
 
-function Harness() {
-  const activeSessionIdRef = useRef<string | null>(SID)
-  const sessionStateByRuntimeIdRef = useRef(states)
-  const queryClientRef = useRef(new QueryClient())
-
-  const stream = useMessageStream({
-    activeSessionIdRef,
-    hydrateFromStoredSession: vi.fn(async () => undefined),
-    queryClient: queryClientRef.current,
-    refreshHermesConfig: vi.fn(async () => undefined),
-    refreshSessions: vi.fn(async () => undefined),
-    sessionStateByRuntimeIdRef,
-    updateSessionState
-  })
-
-  useEffect(() => {
-    appendAssistantDelta = stream.appendAssistantDelta
-  }, [stream.appendAssistantDelta])
-
-  return null
-}
-
+/** The shared harness, but writing through a spy so the unmount test can count
+ *  the writes that happen after teardown. */
 function mountStream() {
-  render(<Harness />)
-  expect(appendAssistantDelta).not.toBeNull()
+  stream = renderMessageStream(SID, { states, updateSessionState })
 }
 
-function assistantText() {
-  const message = states.get(SID)?.messages.at(-1)
-  const part = message?.parts.at(-1)
-
-  return part?.type === 'text' ? part.text : ''
-}
+const assistantText = () => stream.text()
 
 describe('useMessageStream delta flush scheduling', () => {
   beforeEach(() => {
     vi.useFakeTimers()
-    appendAssistantDelta = null
     states = new Map()
     updateSessionState = vi.fn((sessionId: string, updater: (state: ClientSessionState) => ClientSessionState) => {
       const next = updater(states.get(sessionId) ?? createClientSessionState())
@@ -81,7 +56,7 @@ describe('useMessageStream delta flush scheduling', () => {
   it('flushes streaming text on a bounded timer while the window is unfocused', async () => {
     mountStream()
 
-    act(() => appendAssistantDelta!(SID, 'still streaming'))
+    act(() => stream.appendDelta(SID, 'still streaming'))
 
     expect(window.requestAnimationFrame).not.toHaveBeenCalled()
     expect(assistantText()).toBe('')
@@ -97,7 +72,7 @@ describe('useMessageStream delta flush scheduling', () => {
     vi.mocked(performance.now).mockReturnValue(0)
     mountStream()
 
-    act(() => appendAssistantDelta!(SID, 'caught up on focus'))
+    act(() => stream.appendDelta(SID, 'caught up on focus'))
     expect(assistantText()).toBe('')
     expect(vi.getTimerCount()).toBe(1)
 
@@ -120,7 +95,7 @@ describe('useMessageStream delta flush scheduling', () => {
     })
     mountStream()
 
-    act(() => appendAssistantDelta!(SID, 'focused without visibility change'))
+    act(() => stream.appendDelta(SID, 'focused without visibility change'))
     expect(assistantText()).toBe('')
     expect(vi.getTimerCount()).toBe(1)
 
@@ -133,7 +108,7 @@ describe('useMessageStream delta flush scheduling', () => {
     vi.mocked(performance.now).mockReturnValue(0)
     mountStream()
 
-    act(() => appendAssistantDelta!(SID, 'final delta'))
+    act(() => stream.appendDelta(SID, 'final delta'))
     expect(vi.getTimerCount()).toBe(1)
 
     cleanup()
@@ -164,7 +139,7 @@ describe('useMessageStream delta flush scheduling', () => {
 
     mountStream()
 
-    act(() => appendAssistantDelta!(SID, 'first'))
+    act(() => stream.appendDelta(SID, 'first'))
     await act(async () => {
       await vi.advanceTimersByTimeAsync(0)
     })
@@ -177,7 +152,7 @@ describe('useMessageStream delta flush scheduling', () => {
     now = 1100
     act(() => rafCallbacks[0](1040))
 
-    act(() => appendAssistantDelta!(SID, 'second'))
+    act(() => stream.appendDelta(SID, 'second'))
     await act(async () => {
       await vi.advanceTimersByTimeAsync(79)
     })
@@ -201,7 +176,7 @@ describe('useMessageStream delta flush scheduling', () => {
 
     mountStream()
 
-    act(() => appendAssistantDelta!(SID, 'first'))
+    act(() => stream.appendDelta(SID, 'first'))
     await act(async () => {
       await vi.advanceTimersByTimeAsync(0)
     })
@@ -210,7 +185,7 @@ describe('useMessageStream delta flush scheduling', () => {
 
     // 100ms later (well past the 33ms floor): the next flush is immediate.
     now = 1100
-    act(() => appendAssistantDelta!(SID, 'second'))
+    act(() => stream.appendDelta(SID, 'second'))
     await act(async () => {
       await vi.advanceTimersByTimeAsync(0)
     })
@@ -230,14 +205,14 @@ describe('useMessageStream delta flush scheduling', () => {
 
     mountStream()
 
-    act(() => appendAssistantDelta!(SID, 'a'))
+    act(() => stream.appendDelta(SID, 'a'))
     await act(async () => {
       await vi.advanceTimersByTimeAsync(0)
     })
 
     // A second flush starts before the first flush's frame lands.
     now = 1010
-    act(() => appendAssistantDelta!(SID, 'b'))
+    act(() => stream.appendDelta(SID, 'b'))
     await act(async () => {
       await vi.advanceTimersByTimeAsync(23)
     })
@@ -250,7 +225,7 @@ describe('useMessageStream delta flush scheduling', () => {
     now = 1030
     act(() => rafCallbacks[0](1000))
 
-    act(() => appendAssistantDelta!(SID, 'c'))
+    act(() => stream.appendDelta(SID, 'c'))
     await act(async () => {
       await vi.advanceTimersByTimeAsync(13)
     })
@@ -267,6 +242,7 @@ describe('useMessageStream composed with the real useSessionStateCache', () => {
   // measured frame cost includes the deferred $messages commit it adapts to.
   let cache: ReturnType<typeof useSessionStateCache> | null = null
   let published: ChatMessage[]
+  let appendAssistantDelta: ((sessionId: string, delta: string) => void) | null = null
 
   function ComposedHarness() {
     const busyRef: MutableRefObject<boolean> = { current: false }
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/interim-sealing.test.tsx b/apps/desktop/src/app/session/hooks/use-message-stream/interim-sealing.test.tsx
index 0aa549ec50..1f84dc0e7f 100644
--- a/apps/desktop/src/app/session/hooks/use-message-stream/interim-sealing.test.tsx
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/interim-sealing.test.tsx
@@ -1,72 +1,41 @@
-import { QueryClient } from '@tanstack/react-query'
-import { act, cleanup, render, waitFor } from '@testing-library/react'
-import { useEffect, useRef } from 'react'
+import { act, cleanup } from '@testing-library/react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 import type { ClientSessionState } from '@/app/types'
 import { chatMessageText } from '@/lib/chat-messages'
-import { createClientSessionState } from '@/lib/chat-runtime'
 import { clearSessionTodos } from '@/store/todos'
 import type { RpcEvent } from '@/types/hermes'
 
-import { useMessageStream } from './index'
+import { type MessageStreamHarness, renderMessageStream } from './test-harness'
 
 const SID = 'session-1'
 
-let handleEvent: ((event: RpcEvent) => void) | null = null
-let sessionStates: Map<string, ClientSessionState>
+let stream: MessageStreamHarness
 let mockCompleteSound: ReturnType<typeof vi.fn>
 let mockHaptic: ReturnType<typeof vi.fn>
 
-function Harness() {
-  const activeSessionIdRef = useRef<string | null>(SID)
-  const sessionStateByRuntimeIdRef = useRef(new Map<string, ClientSessionState>())
-  const queryClientRef = useRef(new QueryClient())
-
-  const stream = useMessageStream({
-    activeSessionIdRef,
-    hydrateFromStoredSession: vi.fn(async () => undefined),
-    queryClient: queryClientRef.current,
-    refreshHermesConfig: vi.fn(async () => undefined),
-    refreshSessions: vi.fn(async () => undefined),
-    sessionStateByRuntimeIdRef,
-    updateSessionState: (sessionId, updater) => {
-      const current = sessionStateByRuntimeIdRef.current.get(sessionId) ?? createClientSessionState()
-      const next = updater(current)
-      sessionStateByRuntimeIdRef.current.set(sessionId, next)
-      sessionStates.set(sessionId, next)
-
-      return next
-    }
-  })
-
-  useEffect(() => {
-    handleEvent = stream.handleGatewayEvent
-  }, [stream.handleGatewayEvent])
-
-  return null
+function mountStream() {
+  stream = renderMessageStream(SID)
 }
 
-async function mountStream() {
-  sessionStates = new Map()
-  render(<Harness />)
-  await waitFor(() => expect(handleEvent).not.toBeNull())
-}
+const start = () => act(() => stream.handleEvent({ payload: {}, session_id: SID, type: 'message.start' }))
 
-const start = () => act(() => handleEvent!({ payload: {}, session_id: SID, type: 'message.start' }))
-const delta = (text: string) => act(() => handleEvent!({ payload: { text }, session_id: SID, type: 'message.delta' }))
+const delta = (text: string) =>
+  act(() => stream.handleEvent({ payload: { text }, session_id: SID, type: 'message.delta' }))
 
 const interim = (text: string) =>
-  act(() => handleEvent!({ payload: { text, already_streamed: true }, session_id: SID, type: 'message.interim' }))
+  act(() => stream.handleEvent({ payload: { text, already_streamed: true }, session_id: SID, type: 'message.interim' }))
 
 const complete = (text: string) =>
-  act(() => handleEvent!({ payload: { text }, session_id: SID, type: 'message.complete' }))
+  act(() => stream.handleEvent({ payload: { text }, session_id: SID, type: 'message.complete' }))
 
 const completePreviewed = (text: string) =>
-  act(() => handleEvent!({ payload: { text, response_previewed: true }, session_id: SID, type: 'message.complete' }))
+  act(() =>
+    stream.handleEvent({ payload: { text, response_previewed: true }, session_id: SID, type: 'message.complete' })
+  )
 
 function getState(): ClientSessionState {
-  return sessionStates.get(SID) ?? createClientSessionState()
+  return stream.state()
 }
 
 function assistantText(): string {
@@ -87,7 +56,6 @@ function assistantMessages(): string[] {
 
 describe('useMessageStream interim text sealing', () => {
   beforeEach(() => {
-    handleEvent = null
     clearSessionTodos(SID)
   })
 
@@ -98,7 +66,7 @@ describe('useMessageStream interim text sealing', () => {
   })
 
   it('preserves interim text that the final response does not include', async () => {
-    await mountStream()
+    mountStream()
     await start()
 
     await delta('awaaaaa clean!! tsc zero errors')
@@ -112,7 +80,7 @@ describe('useMessageStream interim text sealing', () => {
   })
 
   it('marks sealed interim bubbles interim and leaves the final reply unmarked', async () => {
-    await mountStream()
+    mountStream()
     await start()
 
     await delta('Let me check the files.')
@@ -130,7 +98,7 @@ describe('useMessageStream interim text sealing', () => {
   })
 
   it('clears the interim mark when a previewed final settles onto the interim bubble', async () => {
-    await mountStream()
+    mountStream()
     await start()
 
     await interim('same reply')
@@ -142,7 +110,7 @@ describe('useMessageStream interim text sealing', () => {
   })
 
   it('dedupes interim text when the final response includes it', async () => {
-    await mountStream()
+    mountStream()
     await start()
 
     await delta('Let me check the files.')
@@ -156,7 +124,7 @@ describe('useMessageStream interim text sealing', () => {
   })
 
   it('clears interimBoundaryPending at turn end so the next turn starts clean', async () => {
-    await mountStream()
+    mountStream()
     await start()
 
     await delta('interim text')
@@ -175,7 +143,7 @@ describe('useMessageStream interim text sealing', () => {
   })
 
   it('finalizes an interim segment without settling the turn', async () => {
-    await mountStream()
+    mountStream()
     await start()
 
     await delta('streaming text')
@@ -187,7 +155,7 @@ describe('useMessageStream interim text sealing', () => {
   })
 
   it('settles an identical final onto a non-previewed interim (tool-call turn) instead of duplicating (#63679)', async () => {
-    await mountStream()
+    mountStream()
     await start()
 
     // A plain tool-call turn: the streamed text is sealed as an interim at the
@@ -203,7 +171,7 @@ describe('useMessageStream interim text sealing', () => {
   })
 
   it('settles a prefix-extended final onto a non-previewed interim (streamed + trailing delta)', async () => {
-    await mountStream()
+    mountStream()
     await start()
 
     // The stream dropped/settled early at the tool boundary; the final adds a
@@ -218,7 +186,7 @@ describe('useMessageStream interim text sealing', () => {
   })
 
   it('settles final onto interim even after message.start reset the boundary flag (#74560)', async () => {
-    await mountStream()
+    mountStream()
     await start()
     await delta('partial')
     await interim('partial')
@@ -235,12 +203,12 @@ describe('useMessageStream interim text sealing', () => {
   })
 
   it('appends a distinct previewed final after a message.start reset instead of overwriting the interim', async () => {
-    await mountStream()
+    mountStream()
     await start()
     await interim('old interim text')
     // A genuinely new turn begins — message.start resets interimBoundaryPending.
     // Production ordering: mid-turn compaction-resume events do NOT include
-    // message.start (COMPACTION_RESUME_EVENT_TYPES in gateway-event.ts), and
+    // message.start (COMPACTION_RESUME_EVENT_TYPES in gateway-event/index.ts), and
     // the TUI gateway emits message.complete BEFORE goal-followup starts
     // (tui_gateway/server.py), so a previewed final arriving after the reset
     // is a DISTINCT reply, not a rewrite of the interim. It must append its
@@ -255,7 +223,7 @@ describe('useMessageStream interim text sealing', () => {
   })
 
   it('appends a genuinely different final as its own bubble (two real assistant segments)', async () => {
-    await mountStream()
+    mountStream()
     await start()
 
     // The interim is one segment (pre-tool commentary); the final is different
@@ -271,7 +239,7 @@ describe('useMessageStream interim text sealing', () => {
   })
 
   it('settles an identical final completion onto the interim when response_previewed', async () => {
-    await mountStream()
+    mountStream()
     await start()
 
     await interim('same reply')
@@ -285,7 +253,7 @@ describe('useMessageStream interim text sealing', () => {
   })
 
   it('settles a prefix-matched final onto the interim when response_previewed', async () => {
-    await mountStream()
+    mountStream()
     await start()
 
     // Interim text is a PREFIX of the final — the model streamed part of
@@ -302,7 +270,7 @@ describe('useMessageStream interim text sealing', () => {
   })
 
   it('dedupes partial-stream-then-nudge: streamed prefix + interim + previewed final settles to one bubble', async () => {
-    await mountStream()
+    mountStream()
     await start()
 
     // The model streamed part of its answer via message.delta, then the
@@ -319,16 +287,16 @@ describe('useMessageStream interim text sealing', () => {
   })
 
   it('ignores malformed message.interim payload', async () => {
-    await mountStream()
+    mountStream()
     await start()
 
     // No payload at all
-    await act(() => handleEvent!({ type: 'message.interim' } as RpcEvent))
+    await act(() => stream.handleEvent({ type: 'message.interim' } as RpcEvent))
     // Empty text
-    await act(() => handleEvent!({ payload: { text: '' }, session_id: SID, type: 'message.interim' } as RpcEvent))
+    await act(() => stream.handleEvent({ payload: { text: '' }, session_id: SID, type: 'message.interim' } as RpcEvent))
     // Undefined text
     await act(() =>
-      handleEvent!({ payload: { text: undefined }, session_id: SID, type: 'message.interim' } as RpcEvent)
+      stream.handleEvent({ payload: { text: undefined }, session_id: SID, type: 'message.interim' } as RpcEvent)
     )
 
     // Turn continues without finalizing or throwing
@@ -337,7 +305,7 @@ describe('useMessageStream interim text sealing', () => {
   })
 
   it('clears interimBoundaryPending on message.start', async () => {
-    await mountStream()
+    mountStream()
     await start()
 
     await delta('interim text')
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/moa-progress-event.test.tsx b/apps/desktop/src/app/session/hooks/use-message-stream/moa-progress-event.test.tsx
index 1e4c0d3786..73de97db07 100644
--- a/apps/desktop/src/app/session/hooks/use-message-stream/moa-progress-event.test.tsx
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/moa-progress-event.test.tsx
@@ -1,88 +1,41 @@
-import { QueryClient } from '@tanstack/react-query'
-import { act, cleanup, render, waitFor } from '@testing-library/react'
-import { useEffect, useRef } from 'react'
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 
-import type { ClientSessionState } from '@/app/types'
-import { createClientSessionState } from '@/lib/chat-runtime'
 import type { RpcEvent } from '@/types/hermes'
 
-import { useMessageStream } from './index'
+import { type MessageStreamHarness, renderMessageStream } from './test-harness'
 
 const SID = 'session-1'
-let handleEvent: ((event: RpcEvent) => void) | null = null
-let latestState: ClientSessionState | null = null
+let stream: MessageStreamHarness
 
-function Harness() {
-  const activeSessionIdRef = useRef<string | null>(SID)
-  const sessionStateByRuntimeIdRef = useRef(new Map<string, ClientSessionState>())
-  const queryClientRef = useRef(new QueryClient())
-
-  const stream = useMessageStream({
-    activeSessionIdRef,
-    hydrateFromStoredSession: vi.fn(async () => undefined),
-    queryClient: queryClientRef.current,
-    refreshHermesConfig: vi.fn(async () => undefined),
-    refreshSessions: vi.fn(async () => undefined),
-    sessionStateByRuntimeIdRef,
-    updateSessionState: (sessionId, updater) => {
-      const current = sessionStateByRuntimeIdRef.current.get(sessionId) ?? createClientSessionState()
-      const next = updater(current)
-      sessionStateByRuntimeIdRef.current.set(sessionId, next)
-      latestState = next
-
-      return next
-    }
-  })
-
-  useEffect(() => {
-    handleEvent = stream.handleGatewayEvent
-  }, [stream.handleGatewayEvent])
-
-  return null
-}
-
-async function mountStream() {
-  render(<Harness />)
-  await waitFor(() => expect(handleEvent).not.toBeNull())
+function mountStream() {
+  stream = renderMessageStream(SID)
 }
 
 function emit(type: RpcEvent['type'], payload: RpcEvent['payload'] = {}) {
-  act(() => handleEvent!({ payload, session_id: SID, type }))
+  act(() => stream.handleEvent({ payload, session_id: SID, type }))
 }
 
-function reasoningText(): string {
-  const message = latestState?.messages.at(-1)
-  const part = message?.parts.find(p => p.type === 'reasoning')
-
-  return part?.type === 'reasoning' ? part.text : ''
-}
-
-beforeEach(() => {
-  handleEvent = null
-  latestState = null
-})
-
 afterEach(() => {
   cleanup()
   vi.restoreAllMocks()
 })
 
 describe('useMessageStream moa.progress / moa.phase surfacing', () => {
-  it('shows refs k/n lines in the reasoning block as references complete', async () => {
-    await mountStream()
+  it('shows refs k/n lines in the reasoning block as references complete', () => {
+    mountStream()
 
     emit('message.start')
     emit('moa.progress', { label: 'model-a', refs_done: 1, refs_total: 3 })
     emit('moa.progress', { label: 'model-b', refs_done: 2, refs_total: 3 })
 
-    const text = reasoningText()
+    const text = stream.reasoningText()
     expect(text).toContain('MoA refs 1/3 — model-a')
     expect(text).toContain('MoA refs 2/3 — model-b')
   })
 
-  it('restarts the progress block on the first ref of a new fan-out', async () => {
-    await mountStream()
+  it('restarts the progress block on the first ref of a new fan-out', () => {
+    mountStream()
 
     emit('message.start')
     emit('moa.progress', { label: 'stale', refs_done: 1, refs_total: 2 })
@@ -90,32 +43,32 @@ describe('useMessageStream moa.progress / moa.phase surfacing', () => {
     // A later turn's fan-out starts over at 1/N — old lines must not linger.
     emit('moa.progress', { label: 'fresh', refs_done: 1, refs_total: 2 })
 
-    const text = reasoningText()
+    const text = stream.reasoningText()
     expect(text).toContain('MoA refs 1/2 — fresh')
     expect(text).not.toContain('stale')
   })
 
-  it('appends the aggregating marker on moa.phase and ignores unknown phases', async () => {
-    await mountStream()
+  it('appends the aggregating marker on moa.phase and ignores unknown phases', () => {
+    mountStream()
 
     emit('message.start')
     emit('moa.progress', { label: 'model-a', refs_done: 1, refs_total: 1 })
     emit('moa.phase', { phase: 'reference', refs_done: 1, refs_total: 1 })
-    expect(reasoningText()).not.toContain('aggregating')
+    expect(stream.reasoningText()).not.toContain('aggregating')
 
     emit('moa.phase', { aggregator: 'agg-model', phase: 'aggregator', refs_done: 1, refs_total: 1 })
-    expect(reasoningText()).toContain('MoA aggregating…')
+    expect(stream.reasoningText()).toContain('MoA aggregating…')
   })
 
-  it('a following moa.reference replaces the progress trail (self-cleaning)', async () => {
-    await mountStream()
+  it('a following moa.reference replaces the progress trail (self-cleaning)', () => {
+    mountStream()
 
     emit('message.start')
     emit('moa.progress', { label: 'model-a', refs_done: 1, refs_total: 1 })
     emit('moa.phase', { phase: 'aggregator', refs_done: 1, refs_total: 1 })
     emit('moa.reference', { count: 1, index: 1, label: 'model-a', text: 'advice-a' })
 
-    const text = reasoningText()
+    const text = stream.reasoningText()
     expect(text).toContain('Reference 1/1 — model-a')
     expect(text).not.toContain('MoA refs')
     expect(text).not.toContain('aggregating')
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/moa-reference-event.test.tsx b/apps/desktop/src/app/session/hooks/use-message-stream/moa-reference-event.test.tsx
index ce3afeef67..2bbb4c3325 100644
--- a/apps/desktop/src/app/session/hooks/use-message-stream/moa-reference-event.test.tsx
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/moa-reference-event.test.tsx
@@ -1,81 +1,34 @@
-import { QueryClient } from '@tanstack/react-query'
-import { act, cleanup, render, waitFor } from '@testing-library/react'
-import { useEffect, useRef } from 'react'
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 
-import type { ClientSessionState } from '@/app/types'
-import { createClientSessionState } from '@/lib/chat-runtime'
 import type { RpcEvent } from '@/types/hermes'
 
-import { useMessageStream } from './index'
+import { type MessageStreamHarness, renderMessageStream } from './test-harness'
 
 const SID = 'session-1'
-let handleEvent: ((event: RpcEvent) => void) | null = null
-let latestState: ClientSessionState | null = null
+let stream: MessageStreamHarness
 
-function Harness() {
-  const activeSessionIdRef = useRef<string | null>(SID)
-  const sessionStateByRuntimeIdRef = useRef(new Map<string, ClientSessionState>())
-  const queryClientRef = useRef(new QueryClient())
-
-  const stream = useMessageStream({
-    activeSessionIdRef,
-    hydrateFromStoredSession: vi.fn(async () => undefined),
-    queryClient: queryClientRef.current,
-    refreshHermesConfig: vi.fn(async () => undefined),
-    refreshSessions: vi.fn(async () => undefined),
-    sessionStateByRuntimeIdRef,
-    updateSessionState: (sessionId, updater) => {
-      const current = sessionStateByRuntimeIdRef.current.get(sessionId) ?? createClientSessionState()
-      const next = updater(current)
-      sessionStateByRuntimeIdRef.current.set(sessionId, next)
-      latestState = next
-
-      return next
-    }
-  })
-
-  useEffect(() => {
-    handleEvent = stream.handleGatewayEvent
-  }, [stream.handleGatewayEvent])
-
-  return null
-}
-
-async function mountStream() {
-  render(<Harness />)
-  await waitFor(() => expect(handleEvent).not.toBeNull())
+function mountStream() {
+  stream = renderMessageStream(SID)
 }
 
 function emit(type: RpcEvent['type'], payload: RpcEvent['payload'] = {}) {
-  act(() => handleEvent!({ payload, session_id: SID, type }))
-}
-
-function reasoningText(): string {
-  const message = latestState?.messages.at(-1)
-  const part = message?.parts.find(p => p.type === 'reasoning')
-
-  return part?.type === 'reasoning' ? part.text : ''
+  act(() => stream.handleEvent({ payload, session_id: SID, type }))
 }
 
 describe('useMessageStream moa.reference accumulation (#64658)', () => {
-  beforeEach(() => {
-    handleEvent = null
-    latestState = null
-  })
-
   afterEach(() => {
     cleanup()
     vi.restoreAllMocks()
   })
 
-  it('keeps every reference model labelled block instead of only the latest one', async () => {
-    await mountStream()
+  it('keeps every reference model labelled block instead of only the latest one', () => {
+    mountStream()
 
     emit('moa.reference', { count: 2, index: 1, label: 'model-a', text: 'advice-a' })
     emit('moa.reference', { count: 2, index: 2, label: 'model-b', text: 'advice-b' })
 
-    const text = reasoningText()
+    const text = stream.reasoningText()
 
     expect(text).toContain('model-a')
     expect(text).toContain('advice-a')
@@ -83,25 +36,25 @@ describe('useMessageStream moa.reference accumulation (#64658)', () => {
     expect(text).toContain('advice-b')
   })
 
-  it('handles a single-reference MoA turn (count=1) without regression', async () => {
-    await mountStream()
+  it('handles a single-reference MoA turn (count=1) without regression', () => {
+    mountStream()
 
     emit('moa.reference', { count: 1, index: 1, label: 'model-a', text: 'only-advice' })
 
-    const text = reasoningText()
+    const text = stream.reasoningText()
 
     expect(text).toContain('model-a')
     expect(text).toContain('only-advice')
   })
 
-  it('accumulates three or more references in order', async () => {
-    await mountStream()
+  it('accumulates three or more references in order', () => {
+    mountStream()
 
     emit('moa.reference', { count: 3, index: 1, label: 'model-a', text: 'advice-a' })
     emit('moa.reference', { count: 3, index: 2, label: 'model-b', text: 'advice-b' })
     emit('moa.reference', { count: 3, index: 3, label: 'model-c', text: 'advice-c' })
 
-    const text = reasoningText()
+    const text = stream.reasoningText()
 
     const orderOk =
       text.indexOf('advice-a') < text.indexOf('advice-b') && text.indexOf('advice-b') < text.indexOf('advice-c')
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/pet-tool-failure-event.test.tsx b/apps/desktop/src/app/session/hooks/use-message-stream/pet-tool-failure-event.test.tsx
index 452164b6c5..f508e7501f 100644
--- a/apps/desktop/src/app/session/hooks/use-message-stream/pet-tool-failure-event.test.tsx
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/pet-tool-failure-event.test.tsx
@@ -1,60 +1,26 @@
-import { QueryClient } from '@tanstack/react-query'
-import { act, cleanup, render, waitFor } from '@testing-library/react'
-import { useEffect, useRef } from 'react'
+import { act, cleanup } from '@testing-library/react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
-import type { ClientSessionState } from '@/app/types'
-import { createClientSessionState } from '@/lib/chat-runtime'
 import { $petActivity, $petState, setPetActivity } from '@/store/pet'
 import type { RpcEvent } from '@/types/hermes'
 
-import { useMessageStream } from './index'
+import { type MessageStreamHarness, renderMessageStream } from './test-harness'
 
 const SID = 'session-1'
 const OTHER_SID = 'session-2'
 
-let handleEvent: ((event: RpcEvent) => void) | null = null
+let stream: MessageStreamHarness
 
-function Harness() {
-  const activeSessionIdRef = useRef<string | null>(SID)
-  const sessionStateByRuntimeIdRef = useRef(new Map<string, ClientSessionState>())
-  const queryClientRef = useRef(new QueryClient())
-
-  const stream = useMessageStream({
-    activeSessionIdRef,
-    hydrateFromStoredSession: vi.fn(async () => undefined),
-    queryClient: queryClientRef.current,
-    refreshHermesConfig: vi.fn(async () => undefined),
-    refreshSessions: vi.fn(async () => undefined),
-    sessionStateByRuntimeIdRef,
-    updateSessionState: (sessionId, updater) => {
-      const current = sessionStateByRuntimeIdRef.current.get(sessionId) ?? createClientSessionState()
-      const next = updater(current)
-      sessionStateByRuntimeIdRef.current.set(sessionId, next)
-
-      return next
-    }
-  })
-
-  useEffect(() => {
-    handleEvent = stream.handleGatewayEvent
-  }, [stream.handleGatewayEvent])
-
-  return null
-}
-
-async function mountStream() {
-  render(<Harness />)
-  await waitFor(() => expect(handleEvent).not.toBeNull())
+function mountStream() {
+  stream = renderMessageStream(SID)
 }
 
 function emit(type: RpcEvent['type'], payload: RpcEvent['payload'] = {}, sessionId = SID) {
-  act(() => handleEvent!({ payload, session_id: sessionId, type }))
+  act(() => stream.handleEvent({ payload, session_id: sessionId, type }))
 }
 
 describe('pet tool-failure reaction', () => {
   beforeEach(() => {
-    handleEvent = null
     setPetActivity({
       busy: false,
       awaitingInput: false,
@@ -72,8 +38,8 @@ describe('pet tool-failure reaction', () => {
     vi.restoreAllMocks()
   })
 
-  it('briefly shows failed when the active session has an isolated tool error', async () => {
-    await mountStream()
+  it('briefly shows failed when the active session has an isolated tool error', () => {
+    mountStream()
 
     emit('tool.start', { name: 'terminal', tool_id: 'tool-1' })
     emit('tool.complete', { name: 'terminal', tool_id: 'tool-1', error: 'exit code 1' })
@@ -82,8 +48,8 @@ describe('pet tool-failure reaction', () => {
     expect($petState.get()).toBe('failed')
   })
 
-  it('does not show failed for a successful tool or a background-session failure', async () => {
-    await mountStream()
+  it('does not show failed for a successful tool or a background-session failure', () => {
+    mountStream()
 
     emit('tool.complete', { name: 'terminal', tool_id: 'tool-1' })
     expect($petActivity.get().error).toBe(false)
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/provider-wait-event.test.tsx b/apps/desktop/src/app/session/hooks/use-message-stream/provider-wait-event.test.tsx
index 584a058ab7..1136a14119 100644
--- a/apps/desktop/src/app/session/hooks/use-message-stream/provider-wait-event.test.tsx
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/provider-wait-event.test.tsx
@@ -1,57 +1,23 @@
-import { QueryClient } from '@tanstack/react-query'
-import { act, cleanup, render, waitFor } from '@testing-library/react'
-import { useEffect, useRef } from 'react'
+import { act, cleanup } from '@testing-library/react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
-import type { ClientSessionState } from '@/app/types'
-import { createClientSessionState } from '@/lib/chat-runtime'
 import { $providerWaitSessions } from '@/store/provider-wait'
 import { clearAllSessionStates, dropSessionState } from '@/store/session-states'
 import type { RpcEvent } from '@/types/hermes'
 
-import { useMessageStream } from './index'
+import { type MessageStreamHarness, renderMessageStream } from './test-harness'
 
 const SID = 'session-1'
-let handleEvent: ((event: RpcEvent) => void) | null = null
-
-function Harness() {
-  const activeSessionIdRef = useRef<string | null>(SID)
-  const sessionStateByRuntimeIdRef = useRef(new Map<string, ClientSessionState>())
-  const queryClientRef = useRef(new QueryClient())
-
-  const stream = useMessageStream({
-    activeSessionIdRef,
-    hydrateFromStoredSession: vi.fn(async () => undefined),
-    queryClient: queryClientRef.current,
-    refreshHermesConfig: vi.fn(async () => undefined),
-    refreshSessions: vi.fn(async () => undefined),
-    sessionStateByRuntimeIdRef,
-    updateSessionState: (sessionId, updater) => {
-      const current = sessionStateByRuntimeIdRef.current.get(sessionId) ?? createClientSessionState()
-      const next = updater(current)
-      sessionStateByRuntimeIdRef.current.set(sessionId, next)
-
-      return next
-    }
-  })
-
-  useEffect(() => {
-    handleEvent = stream.handleGatewayEvent
-  }, [stream.handleGatewayEvent])
-
-  return null
-}
+let stream: MessageStreamHarness
 
 function emit(type: RpcEvent['type'], payload: RpcEvent['payload'] = {}) {
-  act(() => handleEvent!({ payload, session_id: SID, type }))
+  act(() => stream.handleEvent({ payload, session_id: SID, type }))
 }
 
 describe('provider wait visibility', () => {
   beforeEach(async () => {
-    handleEvent = null
     $providerWaitSessions.set({})
-    render(<Harness />)
-    await waitFor(() => expect(handleEvent).not.toBeNull())
+    stream = renderMessageStream(SID)
   })
 
   afterEach(() => {
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/session-info-side-effects.test.tsx b/apps/desktop/src/app/session/hooks/use-message-stream/session-info-side-effects.test.tsx
index a60e72d40f..bbc760a677 100644
--- a/apps/desktop/src/app/session/hooks/use-message-stream/session-info-side-effects.test.tsx
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/session-info-side-effects.test.tsx
@@ -1,6 +1,5 @@
 import { QueryClient } from '@tanstack/react-query'
-import { act, cleanup, render, waitFor } from '@testing-library/react'
-import { useEffect, useRef } from 'react'
+import { act, cleanup } from '@testing-library/react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 import { isTargetSessionBusy } from '@/app/session/hooks/use-prompt-actions/utils'
@@ -8,12 +7,10 @@ import type { ClientSessionState } from '@/app/types'
 import { createClientSessionState } from '@/lib/chat-runtime'
 import { modelOptionsQueryKey } from '@/lib/model-options'
 import { setCurrentModel, setCurrentProvider } from '@/store/session'
-import type { RpcEvent } from '@/types/hermes'
 
+import { type MessageStreamHarness, renderMessageStream } from './test-harness'
 import { PRE_TURN_LIVE_SETTLE_GRACE_MS } from './utils'
 
-import { useMessageStream } from './index'
-
 // Per-turn REST amplification guards: session.info must not refetch config for
 // background sessions nor invalidate the model-options catalog when the model
 // string is merely PRESENT (the backend stamps it on every event) rather than
@@ -21,53 +18,28 @@ import { useMessageStream } from './index'
 
 const ACTIVE_SID = 'session-active'
 const ACTIVE_PROFILE = 'compass'
-let handleEvent: ((event: RpcEvent) => void) | null = null
+let stream: MessageStreamHarness
 let refreshHermesConfig: ReturnType<typeof vi.fn<() => Promise<void>>>
 let refreshSessions: ReturnType<typeof vi.fn<() => Promise<void>>>
 let hydrateFromStoredSession: ReturnType<typeof vi.fn<() => Promise<void>>>
 let queryClient: QueryClient
 let sessionStates: Map<string, ClientSessionState> | null = null
 
-function Harness() {
-  const activeSessionIdRef = useRef<string | null>(ACTIVE_SID)
-  const sessionStateByRuntimeIdRef = useRef(new Map<string, ClientSessionState>())
-
-  sessionStates = sessionStateByRuntimeIdRef.current
-
-  const stream = useMessageStream({
+function mountStream() {
+  stream = renderMessageStream(ACTIVE_SID, {
     activeGatewayProfile: ACTIVE_PROFILE,
-    activeSessionIdRef,
     hydrateFromStoredSession,
     queryClient,
     refreshHermesConfig,
-    refreshSessions,
-    sessionStateByRuntimeIdRef,
-    updateSessionState: (sessionId, updater) => {
-      const current = sessionStateByRuntimeIdRef.current.get(sessionId) ?? createClientSessionState()
-      const next = updater(current)
-      sessionStateByRuntimeIdRef.current.set(sessionId, next)
-
-      return next
-    }
+    refreshSessions
   })
-
-  useEffect(() => {
-    handleEvent = stream.handleGatewayEvent
-  }, [stream.handleGatewayEvent])
-
-  return null
-}
-
-async function mountStream() {
-  render(<Harness />)
-  await waitFor(() => expect(handleEvent).not.toBeNull())
+  sessionStates = stream.states
 }
 
 const sessionInfo = (sessionId: string, payload: Record<string, unknown>) =>
-  act(() => handleEvent!({ payload, session_id: sessionId, type: 'session.info' }))
+  act(() => stream.handleEvent({ payload, session_id: sessionId, type: 'session.info' }))
 
 beforeEach(() => {
-  handleEvent = null
   sessionStates = null
   refreshHermesConfig = vi.fn<() => Promise<void>>(async () => undefined)
   refreshSessions = vi.fn<() => Promise<void>>(async () => undefined)
@@ -88,7 +60,7 @@ afterEach(() => {
 describe('session.info config refetch gating', () => {
   it('coalesces active-session bursts into one trailing config fetch', async () => {
     // Mount under real timers (waitFor), then freeze time for the debounce.
-    await mountStream()
+    mountStream()
     vi.useFakeTimers()
 
     sessionInfo(ACTIVE_SID, { model: 'm1', running: true })
@@ -105,7 +77,7 @@ describe('session.info config refetch gating', () => {
   })
 
   it('never fetches config for a background session heartbeat', async () => {
-    await mountStream()
+    mountStream()
     vi.useFakeTimers()
 
     sessionInfo('session-background', { model: 'm1', running: true })
@@ -120,8 +92,8 @@ describe('session.info config refetch gating', () => {
 })
 
 describe('session.info model-options invalidation gating', () => {
-  it('skips invalidation when model/provider merely restate the known values', async () => {
-    await mountStream()
+  it('skips invalidation when model/provider merely restate the known values', () => {
+    mountStream()
     const invalidate = vi.spyOn(queryClient, 'invalidateQueries')
 
     // Seed the session's cached runtime state.
@@ -135,8 +107,8 @@ describe('session.info model-options invalidation gating', () => {
     expect(invalidate).not.toHaveBeenCalled()
   })
 
-  it('invalidates when the session model actually changes', async () => {
-    await mountStream()
+  it('invalidates when the session model actually changes', () => {
+    mountStream()
     const invalidate = vi.spyOn(queryClient, 'invalidateQueries')
 
     sessionInfo(ACTIVE_SID, { model: 'm1', provider: 'p1', running: true })
@@ -159,10 +131,10 @@ describe('session.info settles a turn that produced no assistant payload', () =>
   const busyFor = (sessionId: string) => isTargetSessionBusy(Object.fromEntries(sessionStates!), sessionId, false)
 
   const startTurn = (sessionId: string) =>
-    act(() => handleEvent!({ payload: {}, session_id: sessionId, type: 'message.start' }))
+    act(() => stream.handleEvent({ payload: {}, session_id: sessionId, type: 'message.start' }))
 
   it('leaves the session sendable after a started turn ends with no payload', async () => {
-    await mountStream()
+    mountStream()
 
     startTurn(ACTIVE_SID)
     expect(busyFor(ACTIVE_SID)).toBe(true)
@@ -179,7 +151,7 @@ describe('session.info settles a turn that produced no assistant payload', () =>
   })
 
   it('keeps waiting when running=false lands before the turn ever started', async () => {
-    await mountStream()
+    mountStream()
 
     // submit arms busy/awaitingResponse optimistically — and seeds the visible
     // turn clock (turnStartedAt) at Enter — so this heartbeat is the pre-start
@@ -213,7 +185,7 @@ describe('session.info settles a turn that produced no assistant payload', () =>
   // never fires. Only an app restart cleared it. Past the grace window the
   // gateway's running=false is authoritative and must settle the session.
   it('settles an armed-but-never-live turn once the pre-start grace expires (#86795)', async () => {
-    await mountStream()
+    mountStream()
 
     act(() => {
       sessionStates!.set(ACTIVE_SID, {
@@ -240,7 +212,7 @@ describe('session.info settles a turn that produced no assistant payload', () =>
   // one — submit and the rewind optimistic transforms both seed the clock —
   // but a regression that forgets the seed must fail open, not latch).
   it('settles an armed turn with no clock instead of latching busy (#86795)', async () => {
-    await mountStream()
+    mountStream()
 
     act(() => {
       sessionStates!.set(ACTIVE_SID, {
@@ -258,8 +230,8 @@ describe('session.info settles a turn that produced no assistant payload', () =>
     expect(busyFor(ACTIVE_SID)).toBe(false)
   })
 
-  it('un-latches a background session but does not hydrate its transcript', async () => {
-    await mountStream()
+  it('un-latches a background session but does not hydrate its transcript', () => {
+    mountStream()
 
     startTurn('session-background')
     sessionInfo('session-background', { running: false })
@@ -273,7 +245,7 @@ describe('session.info settles a turn that produced no assistant payload', () =>
   })
 
   it('hydrates the foreground transcript once and coalesces the sidebar refresh', async () => {
-    await mountStream()
+    mountStream()
 
     startTurn(ACTIVE_SID)
     vi.useFakeTimers()
@@ -294,11 +266,11 @@ describe('session.info settles a turn that produced no assistant payload', () =>
 
 describe('message.complete sidebar refresh coalescing', () => {
   it('collapses near-simultaneous completions into one refresh', async () => {
-    await mountStream()
+    mountStream()
     vi.useFakeTimers()
 
-    act(() => handleEvent!({ payload: { text: 'a' }, session_id: 's1', type: 'message.complete' }))
-    act(() => handleEvent!({ payload: { text: 'b' }, session_id: 's2', type: 'message.complete' }))
+    act(() => stream.handleEvent({ payload: { text: 'a' }, session_id: 's1', type: 'message.complete' }))
+    act(() => stream.handleEvent({ payload: { text: 'b' }, session_id: 's2', type: 'message.complete' }))
 
     expect(refreshSessions).not.toHaveBeenCalled()
 
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/session-reclaimed.test.tsx b/apps/desktop/src/app/session/hooks/use-message-stream/session-reclaimed.test.tsx
index 2c865923ee..7fd8473e16 100644
--- a/apps/desktop/src/app/session/hooks/use-message-stream/session-reclaimed.test.tsx
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/session-reclaimed.test.tsx
@@ -1,6 +1,5 @@
 import { QueryClient } from '@tanstack/react-query'
-import { act, cleanup, render, waitFor } from '@testing-library/react'
-import { useEffect, useRef } from 'react'
+import { act, cleanup } from '@testing-library/react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 import type { ClientSessionState } from '@/app/types'
@@ -8,7 +7,7 @@ import { createClientSessionState } from '@/lib/chat-runtime'
 import { $sessionStates, $sessionTiles, publishSessionState } from '@/store/session-states'
 import type { RpcEvent } from '@/types/hermes'
 
-import { useMessageStream } from './index'
+import { type MessageStreamHarness, renderMessageStream } from './test-harness'
 
 // `session.reclaimed`: the backend tore down a live session we're still
 // holding (idle TTL, LRU cap, WS-orphan reap). Before this event the runtime id
@@ -17,48 +16,18 @@ import { useMessageStream } from './index'
 
 const ACTIVE_SID = 'session-active'
 const ACTIVE_PROFILE = 'compass'
-let handleEvent: ((event: RpcEvent) => void) | null = null
+let stream: MessageStreamHarness
 let queryClient: QueryClient
 let wiringCache: Map<string, ClientSessionState>
 
-function Harness() {
-  const activeSessionIdRef = useRef<string | null>(ACTIVE_SID)
-  const sessionStateByRuntimeIdRef = useRef(new Map<string, ClientSessionState>())
-
-  wiringCache = sessionStateByRuntimeIdRef.current
-
-  const stream = useMessageStream({
-    activeGatewayProfile: ACTIVE_PROFILE,
-    activeSessionIdRef,
-    hydrateFromStoredSession: vi.fn(async () => undefined),
-    queryClient,
-    refreshHermesConfig: vi.fn<() => Promise<void>>(async () => undefined),
-    refreshSessions: vi.fn<() => Promise<void>>(async () => undefined),
-    sessionStateByRuntimeIdRef,
-    updateSessionState: (sessionId, updater) => {
-      const current = sessionStateByRuntimeIdRef.current.get(sessionId) ?? createClientSessionState()
-      const next = updater(current)
-      sessionStateByRuntimeIdRef.current.set(sessionId, next)
-
-      return next
-    }
-  })
-
-  useEffect(() => {
-    handleEvent = stream.handleGatewayEvent
-  }, [stream.handleGatewayEvent])
-
-  return null
-}
-
-async function mountStream() {
-  render(<Harness />)
-  await waitFor(() => expect(handleEvent).not.toBeNull())
+function mountStream() {
+  stream = renderMessageStream(ACTIVE_SID, { activeGatewayProfile: ACTIVE_PROFILE, queryClient })
+  wiringCache = stream.states
 }
 
 const reclaim = (sessionId: string, reason = 'ws_orphan_reap') =>
   act(() =>
-    handleEvent!({
+    stream.handleEvent({
       payload: { reason, session_id: sessionId, stored_session_id: 'stored-1' },
       session_id: '',
       type: 'session.reclaimed'
@@ -66,7 +35,6 @@ const reclaim = (sessionId: string, reason = 'ws_orphan_reap') =>
   )
 
 beforeEach(() => {
-  handleEvent = null
   queryClient = new QueryClient()
   $sessionStates.set({})
   $sessionTiles.set([])
@@ -80,8 +48,8 @@ afterEach(() => {
 })
 
 describe('session.reclaimed', () => {
-  it('drops the cached state for the reclaimed runtime', async () => {
-    await mountStream()
+  it('drops the cached state for the reclaimed runtime', () => {
+    mountStream()
     publishSessionState('live-gone', createClientSessionState())
     expect($sessionStates.get()['live-gone']).toBeDefined()
 
@@ -90,8 +58,8 @@ describe('session.reclaimed', () => {
     expect($sessionStates.get()['live-gone']).toBeUndefined()
   })
 
-  it('leaves every other live session alone', async () => {
-    await mountStream()
+  it('leaves every other live session alone', () => {
+    mountStream()
     publishSessionState('live-gone', createClientSessionState())
     publishSessionState('live-kept', createClientSessionState())
 
@@ -103,8 +71,8 @@ describe('session.reclaimed', () => {
     expect($sessionStates.get()['live-kept']).toBeDefined()
   })
 
-  it('ignores a payload with no runtime id instead of clearing everything', async () => {
-    await mountStream()
+  it('ignores a payload with no runtime id instead of clearing everything', () => {
+    mountStream()
     publishSessionState('live-a', createClientSessionState())
     publishSessionState('live-b', createClientSessionState())
 
@@ -114,12 +82,11 @@ describe('session.reclaimed', () => {
     expect(Object.keys($sessionStates.get()).sort()).toEqual(['live-a', 'live-b'])
   })
 
-  it('drops the runtime regardless of which reclaim reason fired', async () => {
+  it('drops the runtime regardless of which reclaim reason fired', () => {
     for (const reason of ['idle_timeout', 'lru_evict', 'ws_orphan_reap']) {
       $sessionStates.set({})
       cleanup()
-      handleEvent = null
-      await mountStream()
+      mountStream()
       publishSessionState('live-gone', createClientSessionState())
 
       reclaim('live-gone', reason)
@@ -132,8 +99,8 @@ describe('session.reclaimed', () => {
   // state drop above empties the tile's view, but with `runtimeId` still set
   // the tile's resume effect (gated on !runtimeId) never refires — an empty
   // transcript under live chrome, unrecoverable without closing the tab.
-  it('unbinds a tile holding the reclaimed runtime so its resume can refire', async () => {
-    await mountStream()
+  it('unbinds a tile holding the reclaimed runtime so its resume can refire', () => {
+    mountStream()
     publishSessionState('live-gone', createClientSessionState('stored-1'))
     $sessionTiles.set([
       { runtimeId: 'live-gone', storedSessionId: 'stored-1' },
@@ -152,8 +119,8 @@ describe('session.reclaimed', () => {
   // The wiring cache is resumeTile's warm path: a leftover entry for the dead
   // runtime would be handed straight back on the re-resume, rebinding the tile
   // to the same reclaimed id the backend just forgot.
-  it('purges the wiring cache entry for the reclaimed runtime', async () => {
-    await mountStream()
+  it('purges the wiring cache entry for the reclaimed runtime', () => {
+    mountStream()
     wiringCache.set('live-gone', createClientSessionState('stored-1'))
     wiringCache.set('live-kept', createClientSessionState('stored-2'))
 
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/stale-pending-settle.test.tsx b/apps/desktop/src/app/session/hooks/use-message-stream/stale-pending-settle.test.tsx
index 52973d7fde..568d39f02f 100644
--- a/apps/desktop/src/app/session/hooks/use-message-stream/stale-pending-settle.test.tsx
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/stale-pending-settle.test.tsx
@@ -4,56 +4,21 @@
 // mid-transcript — the dither block anywhere but the tail. session.info
 // running=false is the turn's finally-block signal and the only settle edge
 // those paths still emit, so it must finalize the bubble.
-import { QueryClient } from '@tanstack/react-query'
-import { act, cleanup, render } from '@testing-library/react'
-import { useEffect, useRef } from 'react'
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 
-import type { ClientSessionState } from '@/app/types'
-import { createClientSessionState } from '@/lib/chat-runtime'
 import type { RpcEvent } from '@/types/hermes'
 
+import { type MessageStreamHarness, renderMessageStream } from './test-harness'
 import { STREAM_DELTA_FLUSH_MS } from './utils'
 
-import { useMessageStream } from './index'
-
 const SID = 'stale-pending-session'
 
-let handleEvent: ((event: RpcEvent) => void) | null = null
-let states: Map<string, ClientSessionState>
-
-function Harness() {
-  const activeSessionIdRef = useRef<string | null>(SID)
-  const sessionStateByRuntimeIdRef = useRef(new Map<string, ClientSessionState>())
-  const queryClientRef = useRef(new QueryClient())
-
-  const stream = useMessageStream({
-    activeSessionIdRef,
-    hydrateFromStoredSession: vi.fn(async () => undefined),
-    queryClient: queryClientRef.current,
-    refreshHermesConfig: vi.fn(async () => undefined),
-    refreshSessions: vi.fn(async () => undefined),
-    sessionStateByRuntimeIdRef,
-    updateSessionState: (sessionId, updater) => {
-      const current = sessionStateByRuntimeIdRef.current.get(sessionId) ?? createClientSessionState()
-      const next = updater(current)
-      sessionStateByRuntimeIdRef.current.set(sessionId, next)
-
-      return next
-    }
-  })
-
-  useEffect(() => {
-    handleEvent = stream.handleGatewayEvent
-    states = sessionStateByRuntimeIdRef.current
-  }, [stream.handleGatewayEvent])
-
-  return null
-}
+let stream: MessageStreamHarness
 
 async function mountHarness() {
   vi.useFakeTimers()
-  render(<Harness />)
+  stream = renderMessageStream(SID)
   await act(async () => {
     await Promise.resolve()
   })
@@ -65,14 +30,9 @@ const flushDeltas = async () => {
   })
 }
 
-const emit = (event: RpcEvent) => act(() => handleEvent?.(event))
+const emit = (event: RpcEvent) => act(() => stream.handleEvent(event))
 
 describe('turn end without message.complete (session.info running=false)', () => {
-  beforeEach(() => {
-    handleEvent = null
-    states = new Map()
-  })
-
   afterEach(() => {
     cleanup()
     vi.useRealTimers()
@@ -86,11 +46,11 @@ describe('turn end without message.complete (session.info running=false)', () =>
     emit({ payload: { text: 'partial answer' }, session_id: SID, type: 'message.delta' })
     await flushDeltas()
 
-    expect(states.get(SID)?.messages.at(-1)?.pending).toBe(true)
+    expect(stream.state()?.messages.at(-1)?.pending).toBe(true)
 
     emit({ payload: { running: false }, session_id: SID, type: 'session.info' })
 
-    const state = states.get(SID)
+    const state = stream.state()
     const tail = state?.messages.at(-1)
 
     expect(tail?.role).toBe('assistant')
@@ -118,7 +78,7 @@ describe('turn end without message.complete (session.info running=false)', () =>
 
     emit({ payload: { running: false }, session_id: SID, type: 'session.info' })
 
-    const state = states.get(SID)
+    const state = stream.state()
 
     // Same math as Stop: an empty-text placeholder is dropped, nothing stays
     // pending, and the stream binding is released.
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/stream-flush.test.tsx b/apps/desktop/src/app/session/hooks/use-message-stream/stream-flush.test.tsx
index d14f0f4fe9..31da62b1eb 100644
--- a/apps/desktop/src/app/session/hooks/use-message-stream/stream-flush.test.tsx
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/stream-flush.test.tsx
@@ -1,56 +1,14 @@
-import { QueryClient } from '@tanstack/react-query'
-import { act, cleanup, render } from '@testing-library/react'
-import { useEffect, useRef } from 'react'
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-
-import type { ClientSessionState } from '@/app/types'
-import { createClientSessionState } from '@/lib/chat-runtime'
-import type { RpcEvent } from '@/types/hermes'
+import { act, cleanup } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 
+import { type MessageStreamHarness, renderMessageStream } from './test-harness'
 import { STREAM_DELTA_FLUSH_MS } from './utils'
 
-import { useMessageStream } from './index'
-
 const SID = 'stream-session'
 
-let handleEvent: ((event: RpcEvent) => void) | null = null
-let states: Map<string, ClientSessionState>
-
-function Harness() {
-  const activeSessionIdRef = useRef<string | null>(SID)
-  const sessionStateByRuntimeIdRef = useRef(new Map<string, ClientSessionState>())
-  const queryClientRef = useRef(new QueryClient())
-
-  const stream = useMessageStream({
-    activeSessionIdRef,
-    hydrateFromStoredSession: vi.fn(async () => undefined),
-    queryClient: queryClientRef.current,
-    refreshHermesConfig: vi.fn(async () => undefined),
-    refreshSessions: vi.fn(async () => undefined),
-    sessionStateByRuntimeIdRef,
-    updateSessionState: (sessionId, updater) => {
-      const current = sessionStateByRuntimeIdRef.current.get(sessionId) ?? createClientSessionState()
-      const next = updater(current)
-      sessionStateByRuntimeIdRef.current.set(sessionId, next)
-
-      return next
-    }
-  })
-
-  useEffect(() => {
-    handleEvent = stream.handleGatewayEvent
-    states = sessionStateByRuntimeIdRef.current
-  }, [stream.handleGatewayEvent])
-
-  return null
-}
+let stream: MessageStreamHarness
 
 describe('stream delta delivery', () => {
-  beforeEach(() => {
-    handleEvent = null
-    states = new Map()
-  })
-
   afterEach(() => {
     cleanup()
     vi.useRealTimers()
@@ -64,7 +22,7 @@ describe('stream delta delivery', () => {
     const rafSpy = vi.spyOn(window, 'requestAnimationFrame').mockImplementation(() => 1)
     vi.useFakeTimers()
 
-    render(<Harness />)
+    stream = renderMessageStream(SID)
     await act(async () => {
       await Promise.resolve()
     })
@@ -72,7 +30,7 @@ describe('stream delta delivery', () => {
     // Reach the frame-gated branch: it is only taken once the coalescing floor
     // has already elapsed since the previous flush. Send one delta, let it
     // flush, then idle past the floor so the NEXT delta schedules immediately.
-    act(() => handleEvent?.({ payload: { text: 'first ' }, session_id: SID, type: 'message.delta' }))
+    act(() => stream.handleEvent({ payload: { text: 'first ' }, session_id: SID, type: 'message.delta' }))
     await act(async () => {
       await vi.advanceTimersByTimeAsync(STREAM_DELTA_FLUSH_MS)
     })
@@ -80,13 +38,13 @@ describe('stream delta delivery', () => {
       await vi.advanceTimersByTimeAsync(STREAM_DELTA_FLUSH_MS * 2)
     })
 
-    act(() => handleEvent?.({ payload: { text: 'and the rest' }, session_id: SID, type: 'message.delta' }))
+    act(() => stream.handleEvent({ payload: { text: 'and the rest' }, session_id: SID, type: 'message.delta' }))
 
     await act(async () => {
       await vi.advanceTimersByTimeAsync(STREAM_DELTA_FLUSH_MS)
     })
 
-    expect(states.get(SID)?.messages.at(-1)?.parts).toMatchObject([{ type: 'text', text: 'first and the rest' }])
+    expect(stream.state()?.messages.at(-1)?.parts).toMatchObject([{ type: 'text', text: 'first and the rest' }])
     // The flush must not have depended on a frame: this mock parks every rAF
     // callback, yet the text arrived. runFlush still registers its
     // adaptive-floor measurement callback here; that one is allowed to wait
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/terminal-error-frame.test.tsx b/apps/desktop/src/app/session/hooks/use-message-stream/terminal-error-frame.test.tsx
index a2c775a912..303cf10a2e 100644
--- a/apps/desktop/src/app/session/hooks/use-message-stream/terminal-error-frame.test.tsx
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/terminal-error-frame.test.tsx
@@ -1,63 +1,29 @@
-import { QueryClient } from '@tanstack/react-query'
-import { act, cleanup, render, waitFor } from '@testing-library/react'
-import { useEffect, useRef } from 'react'
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 
 import type { ClientSessionState } from '@/app/types'
 import { chatMessageText } from '@/lib/chat-messages'
-import { createClientSessionState } from '@/lib/chat-runtime'
-import type { RpcEvent } from '@/types/hermes'
 
-import { useMessageStream } from './index'
+import { type MessageStreamHarness, renderMessageStream } from './test-harness'
 
 const SID = 'session-1'
 
-let handleEvent: ((event: RpcEvent) => void) | null = null
-let sessionStates: Map<string, ClientSessionState>
+let stream: MessageStreamHarness
 
-function Harness() {
-  const activeSessionIdRef = useRef<string | null>(SID)
-  const sessionStateByRuntimeIdRef = useRef(new Map<string, ClientSessionState>())
-  const queryClientRef = useRef(new QueryClient())
-
-  const stream = useMessageStream({
-    activeSessionIdRef,
-    hydrateFromStoredSession: vi.fn(async () => undefined),
-    queryClient: queryClientRef.current,
-    refreshHermesConfig: vi.fn(async () => undefined),
-    refreshSessions: vi.fn(async () => undefined),
-    sessionStateByRuntimeIdRef,
-    updateSessionState: (sessionId, updater) => {
-      const current = sessionStateByRuntimeIdRef.current.get(sessionId) ?? createClientSessionState()
-      const next = updater(current)
-      sessionStateByRuntimeIdRef.current.set(sessionId, next)
-      sessionStates.set(sessionId, next)
-
-      return next
-    }
-  })
-
-  useEffect(() => {
-    handleEvent = stream.handleGatewayEvent
-  }, [stream.handleGatewayEvent])
-
-  return null
+function mountStream() {
+  stream = renderMessageStream(SID)
 }
 
-async function mountStream() {
-  sessionStates = new Map()
-  render(<Harness />)
-  await waitFor(() => expect(handleEvent).not.toBeNull())
-}
+const start = () => act(() => stream.handleEvent({ payload: {}, session_id: SID, type: 'message.start' }))
 
-const start = () => act(() => handleEvent!({ payload: {}, session_id: SID, type: 'message.start' }))
-const delta = (text: string) => act(() => handleEvent!({ payload: { text }, session_id: SID, type: 'message.delta' }))
+const delta = (text: string) =>
+  act(() => stream.handleEvent({ payload: { text }, session_id: SID, type: 'message.delta' }))
 
 const completeWithError = (payload: Record<string, unknown>) =>
-  act(() => handleEvent!({ payload: { status: 'error', ...payload }, session_id: SID, type: 'message.complete' }))
+  act(() => stream.handleEvent({ payload: { status: 'error', ...payload }, session_id: SID, type: 'message.complete' }))
 
 function getState(): ClientSessionState {
-  return sessionStates.get(SID) ?? createClientSessionState()
+  return stream.state()
 }
 
 function lastAssistant() {
@@ -65,17 +31,13 @@ function lastAssistant() {
 }
 
 describe('terminal error message.complete frames', () => {
-  beforeEach(() => {
-    handleEvent = null
-  })
-
   afterEach(() => {
     cleanup()
     vi.restoreAllMocks()
   })
 
   it('marks the bubble failed from the structured error field, not the text heuristic', async () => {
-    await mountStream()
+    mountStream()
     await start()
     await delta('…')
 
@@ -89,7 +51,7 @@ describe('terminal error message.complete frames', () => {
   })
 
   it('keeps streamed partial text visible on a partial failure', async () => {
-    await mountStream()
+    mountStream()
     await start()
     await delta('half an ans')
 
@@ -107,7 +69,7 @@ describe('terminal error message.complete frames', () => {
   })
 
   it('falls back to the frame text when no error field is present', async () => {
-    await mountStream()
+    mountStream()
     await start()
     await delta('…')
 
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/test-harness.tsx b/apps/desktop/src/app/session/hooks/use-message-stream/test-harness.tsx
new file mode 100644
index 0000000000..4104bd5e87
--- /dev/null
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/test-harness.tsx
@@ -0,0 +1,117 @@
+import { QueryClient } from '@tanstack/react-query'
+import { render } from '@testing-library/react'
+import { useEffect, useRef } from 'react'
+import { vi } from 'vitest'
+
+import type { ClientSessionState } from '@/app/types'
+import { createClientSessionState } from '@/lib/chat-runtime'
+import type { RpcEvent } from '@/types/hermes'
+
+import { useMessageStream } from './index'
+
+export interface MessageStreamHarnessOptions extends Partial<Parameters<typeof useMessageStream>[0]> {
+  /** Session-state map to mount with, for tests that seed state up front. */
+  states?: Map<string, ClientSessionState>
+}
+
+export interface MessageStreamHarness {
+  /** Feed a gateway event into the mounted hook. */
+  handleEvent: (event: RpcEvent) => void
+  /** Push streaming assistant text, bypassing the event envelope. For the specs
+   *  about flush scheduling rather than about a particular event. */
+  appendDelta: (sessionId: string, delta: string) => void
+  /** The hook's session-state map, so callers can seed or inspect it directly. */
+  states: Map<string, ClientSessionState>
+  /** State for a session, blank before the hook has written any. */
+  state: (sessionId?: string) => ClientSessionState
+  /** Last state written for any session — for assertions about the write itself. */
+  latest: () => ClientSessionState | null
+  /** Text of the trailing text part on a session's newest message, '' when the
+   *  tail is not text. What streamed deltas accumulate into. */
+  text: (sessionId?: string) => string
+  /** Text of the reasoning part on the newest message, '' when there is none.
+   *  MoA events land there, so the moa specs read the stream through it. */
+  reasoningText: () => string
+}
+
+/** Mount `useMessageStream` with inert dependencies and hand back the event sink
+ *  plus the state it produces.
+ *
+ *  Every event test needs the same wiring — the real hook, stubbed refresh and
+ *  hydrate callbacks, a session-state map it owns — and differs only in which
+ *  events it sends and what it asserts. `overrides` takes any of the hook's own
+ *  options for the tests that need a seeded state map, a shared query client, a
+ *  named gateway profile, or a callback they can assert against. Callers still
+ *  own `cleanup()`. */
+export function renderMessageStream(
+  sessionId: string | null,
+  { states = new Map<string, ClientSessionState>(), ...overrides }: MessageStreamHarnessOptions = {}
+): MessageStreamHarness {
+  let dispatch: ((event: RpcEvent) => void) | null = null
+  let appendDelta: ((sessionId: string, delta: string) => void) | null = null
+  let latest: ClientSessionState | null = null
+
+  function Harness() {
+    const activeSessionIdRef = useRef<string | null>(sessionId)
+    const sessionStateByRuntimeIdRef = useRef(states)
+    const queryClientRef = useRef(new QueryClient())
+
+    const stream = useMessageStream({
+      activeSessionIdRef,
+      hydrateFromStoredSession: vi.fn(async () => undefined),
+      queryClient: queryClientRef.current,
+      refreshHermesConfig: vi.fn(async () => undefined),
+      refreshSessions: vi.fn(async () => undefined),
+      sessionStateByRuntimeIdRef,
+      updateSessionState: (id, updater) => {
+        const next = updater(states.get(id) ?? createClientSessionState())
+        states.set(id, next)
+        latest = next
+
+        return next
+      },
+      ...overrides
+    })
+
+    useEffect(() => {
+      dispatch = stream.handleGatewayEvent
+      appendDelta = stream.appendAssistantDelta
+    }, [stream.appendAssistantDelta, stream.handleGatewayEvent])
+
+    return null
+  }
+
+  render(<Harness />)
+
+  const state = (id = sessionId ?? '') => states.get(id) ?? createClientSessionState()
+
+  return {
+    handleEvent: event => {
+      if (!dispatch) {
+        throw new Error('renderMessageStream: the hook never mounted')
+      }
+
+      dispatch(event)
+    },
+    appendDelta: (id, delta) => {
+      if (!appendDelta) {
+        throw new Error('renderMessageStream: the hook never mounted')
+      }
+
+      appendDelta(id, delta)
+    },
+    states,
+    state,
+    latest: () => latest,
+    text: id => {
+      const part = state(id).messages.at(-1)?.parts.at(-1)
+
+      return part?.type === 'text' ? part.text : ''
+    },
+    reasoningText: () => {
+      const part = latest?.messages.at(-1)?.parts.find(p => p.type === 'reasoning')
+
+      return part?.type === 'reasoning' ? part.text : ''
+    }
+  }
+}
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/timeline-events.test.tsx b/apps/desktop/src/app/session/hooks/use-message-stream/timeline-events.test.tsx
index cfeccbc0c5..07d45ca56a 100644
--- a/apps/desktop/src/app/session/hooks/use-message-stream/timeline-events.test.tsx
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/timeline-events.test.tsx
@@ -1,57 +1,18 @@
-import { QueryClient } from '@tanstack/react-query'
-import { act, cleanup, render, waitFor } from '@testing-library/react'
-import { useEffect, useRef } from 'react'
+import { act, cleanup } from '@testing-library/react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
-import type { ClientSessionState } from '@/app/types'
-import { createClientSessionState } from '@/lib/chat-runtime'
-import type { RpcEvent } from '@/types/hermes'
-
-import { useMessageStream } from './index'
+import { type MessageStreamHarness, renderMessageStream } from './test-harness'
 
 const SID = 'timeline-session'
 
-let handleEvent: ((event: RpcEvent) => void) | null = null
-let states: Map<string, ClientSessionState>
-
-function Harness() {
-  const activeSessionIdRef = useRef<string | null>(SID)
-  const sessionStateByRuntimeIdRef = useRef(new Map<string, ClientSessionState>())
-  const queryClientRef = useRef(new QueryClient())
-
-  const stream = useMessageStream({
-    activeSessionIdRef,
-    hydrateFromStoredSession: vi.fn(async () => undefined),
-    queryClient: queryClientRef.current,
-    refreshHermesConfig: vi.fn(async () => undefined),
-    refreshSessions: vi.fn(async () => undefined),
-    sessionStateByRuntimeIdRef,
-    updateSessionState: (sessionId, updater) => {
-      const current = sessionStateByRuntimeIdRef.current.get(sessionId) ?? createClientSessionState()
-      const next = updater(current)
-      sessionStateByRuntimeIdRef.current.set(sessionId, next)
-      states.set(sessionId, next)
-
-      return next
-    }
-  })
-
-  useEffect(() => {
-    handleEvent = stream.handleGatewayEvent
-  }, [stream.handleGatewayEvent])
-
-  return null
-}
+let stream: MessageStreamHarness
 
 const event = (type: string, timestamp: number, payload: Record<string, unknown> = {}) =>
-  act(() => handleEvent?.({ payload: { ...payload, timestamp }, session_id: SID, type }))
+  act(() => stream.handleEvent({ payload: { ...payload, timestamp }, session_id: SID, type }))
 
 describe('live transcript timeline events', () => {
   beforeEach(async () => {
-    handleEvent = null
-    states = new Map()
-    render(<Harness />)
-    await waitFor(() => expect(handleEvent).not.toBeNull())
+    stream = renderMessageStream(SID)
   })
 
   afterEach(() => {
@@ -68,7 +29,7 @@ describe('live transcript timeline events', () => {
     event('message.delta', 105.625, { text: 'The file looks good.' })
     event('message.complete', 106.875, { text: 'The file looks good.' })
 
-    const assistants = states.get(SID)?.messages.filter(message => message.role === 'assistant') ?? []
+    const assistants = stream.state(SID).messages.filter(message => message.role === 'assistant') ?? []
 
     expect(assistants).toHaveLength(2)
     expect([assistants[0].timestamp, assistants[0].completedAt]).toEqual([101.125, 101.75])
@@ -88,7 +49,7 @@ describe('live transcript timeline events', () => {
     event('message.delta', 202.25, { text: 'Then speaking.' })
     event('tool.start', 203.5, { args: {}, name: 'terminal', tool_id: 'call-2' })
 
-    const assistant = states.get(SID)?.messages.find(message => message.role === 'assistant')
+    const assistant = stream.state(SID).messages.find(message => message.role === 'assistant')
 
     expect(assistant?.parts.map(part => part.type)).toEqual(['reasoning', 'text', 'tool-call'])
     expect(assistant?.parts.map(part => part.timestamp)).toEqual([201.125, 202.25, 203.5])
@@ -98,7 +59,7 @@ describe('live transcript timeline events', () => {
     event('message.start', 300)
     event('error', 301.875, { error: 'provider failed' })
 
-    const assistant = states.get(SID)?.messages.find(message => message.role === 'assistant')
+    const assistant = stream.state(SID).messages.find(message => message.role === 'assistant')
 
     expect(assistant?.error).toBeTruthy()
     expect([assistant?.timestamp, assistant?.completedAt]).toEqual([301.875, 301.875])
@@ -107,7 +68,7 @@ describe('live transcript timeline events', () => {
   it('uses the gateway event time for a review summary system row', () => {
     event('review.summary', 401.625, { text: 'Review saved.' })
 
-    const system = states.get(SID)?.messages.find(message => message.role === 'system')
+    const system = stream.state(SID).messages.find(message => message.role === 'system')
 
     expect(system?.timestamp).toBe(401.625)
     expect(system?.parts[0].timestamp).toBe(401.625)
@@ -118,7 +79,7 @@ describe('live transcript timeline events', () => {
     event('tool.start', 501, { args: {}, name: 'terminal', tool_id: 'call-3' })
     event('session.info', 502.75, { running: false })
 
-    const assistant = states.get(SID)?.messages.find(message => message.role === 'assistant')
+    const assistant = stream.state(SID).messages.find(message => message.role === 'assistant')
 
     expect(assistant?.completedAt).toBe(502.75)
     expect(assistant?.parts[0].completedAt).toBe(502.75)
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/todo-cleanup.test.tsx b/apps/desktop/src/app/session/hooks/use-message-stream/todo-cleanup.test.tsx
index 6b676976e5..d56f639d69 100644
--- a/apps/desktop/src/app/session/hooks/use-message-stream/todo-cleanup.test.tsx
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/todo-cleanup.test.tsx
@@ -1,59 +1,25 @@
-import { QueryClient } from '@tanstack/react-query'
-import { act, cleanup, render, waitFor } from '@testing-library/react'
-import { useEffect, useRef } from 'react'
+import { act, cleanup } from '@testing-library/react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
-import type { ClientSessionState } from '@/app/types'
-import { createClientSessionState } from '@/lib/chat-runtime'
 import type { TodoItem } from '@/lib/todos'
 import { $todosBySession, clearSessionTodos, setSessionTodos } from '@/store/todos'
-import type { RpcEvent } from '@/types/hermes'
 
-import { useMessageStream } from './index'
+import { type MessageStreamHarness, renderMessageStream } from './test-harness'
 
 const SID = 'session-1'
 const todo = (id: string, status: TodoItem['status']): TodoItem => ({ content: `task ${id}`, id, status })
 
-let handleEvent: ((event: RpcEvent) => void) | null = null
+let stream: MessageStreamHarness
 
-function Harness() {
-  const activeSessionIdRef = useRef<string | null>(SID)
-  const sessionStateByRuntimeIdRef = useRef(new Map<string, ClientSessionState>())
-  const queryClientRef = useRef(new QueryClient())
-
-  const stream = useMessageStream({
-    activeSessionIdRef,
-    hydrateFromStoredSession: vi.fn(async () => undefined),
-    queryClient: queryClientRef.current,
-    refreshHermesConfig: vi.fn(async () => undefined),
-    refreshSessions: vi.fn(async () => undefined),
-    sessionStateByRuntimeIdRef,
-    updateSessionState: (sessionId, updater) => {
-      const current = sessionStateByRuntimeIdRef.current.get(sessionId) ?? createClientSessionState()
-      const next = updater(current)
-      sessionStateByRuntimeIdRef.current.set(sessionId, next)
-
-      return next
-    }
-  })
-
-  useEffect(() => {
-    handleEvent = stream.handleGatewayEvent
-  }, [stream.handleGatewayEvent])
-
-  return null
+function mountStream() {
+  stream = renderMessageStream(SID)
 }
 
-async function mountStream() {
-  render(<Harness />)
-  await waitFor(() => expect(handleEvent).not.toBeNull())
-}
-
-const complete = () => act(() => handleEvent!({ payload: { text: 'done' }, session_id: SID, type: 'message.complete' }))
+const complete = () =>
+  act(() => stream.handleEvent({ payload: { text: 'done' }, session_id: SID, type: 'message.complete' }))
 
 describe('useMessageStream turn-end todo cleanup', () => {
   beforeEach(() => {
-    handleEvent = null
     clearSessionTodos(SID)
   })
 
@@ -63,8 +29,8 @@ describe('useMessageStream turn-end todo cleanup', () => {
     vi.restoreAllMocks()
   })
 
-  it('drops a still-active task list when the turn completes', async () => {
-    await mountStream()
+  it('drops a still-active task list when the turn completes', () => {
+    mountStream()
     setSessionTodos(SID, [todo('a', 'completed'), todo('b', 'in_progress')])
 
     complete()
@@ -72,8 +38,8 @@ describe('useMessageStream turn-end todo cleanup', () => {
     expect($todosBySession.get()[SID]).toBeUndefined()
   })
 
-  it('keeps a finished list on completion so its linger shows the final checkmarks', async () => {
-    await mountStream()
+  it('keeps a finished list on completion so its linger shows the final checkmarks', () => {
+    mountStream()
     setSessionTodos(SID, [todo('a', 'completed')])
 
     complete()
@@ -82,11 +48,11 @@ describe('useMessageStream turn-end todo cleanup', () => {
     expect($todosBySession.get()[SID]).toHaveLength(1)
   })
 
-  it('drops a still-active task list when the turn errors out', async () => {
-    await mountStream()
+  it('drops a still-active task list when the turn errors out', () => {
+    mountStream()
     setSessionTodos(SID, [todo('a', 'in_progress')])
 
-    act(() => handleEvent!({ payload: { message: 'boom' }, session_id: SID, type: 'error' }))
+    act(() => stream.handleEvent({ payload: { message: 'boom' }, session_id: SID, type: 'error' }))
 
     expect($todosBySession.get()[SID]).toBeUndefined()
   })
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/tool-drafting-event.test.tsx b/apps/desktop/src/app/session/hooks/use-message-stream/tool-drafting-event.test.tsx
index 57d5c5b1ce..119c5b5cae 100644
--- a/apps/desktop/src/app/session/hooks/use-message-stream/tool-drafting-event.test.tsx
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/tool-drafting-event.test.tsx
@@ -1,6 +1,4 @@
-import { QueryClient } from '@tanstack/react-query'
-import { act, cleanup, render, waitFor } from '@testing-library/react'
-import { useEffect, useRef } from 'react'
+import { act, cleanup } from '@testing-library/react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 import type { ClientSessionState } from '@/app/types'
@@ -8,7 +6,7 @@ import { createClientSessionState } from '@/lib/chat-runtime'
 import { $draftingToolSessions } from '@/store/tool-drafting'
 import type { RpcEvent } from '@/types/hermes'
 
-import { useMessageStream } from './index'
+import { type MessageStreamHarness, renderMessageStream } from './test-harness'
 
 const SID = 'session-1'
 const OTHER_SID = 'session-2'
@@ -16,42 +14,14 @@ const OTHER_SID = 'session-2'
 // Module-scoped so a test can seed session state (e.g. interrupted) before the
 // handler reads it — `sessionInterrupted` resolves against this map.
 const sessionStates = new Map<string, ClientSessionState>()
-let handleEvent: ((event: RpcEvent) => void) | null = null
+let stream: MessageStreamHarness
 
-function Harness() {
-  const activeSessionIdRef = useRef<string | null>(SID)
-  const sessionStateByRuntimeIdRef = useRef(sessionStates)
-  const queryClientRef = useRef(new QueryClient())
-
-  const stream = useMessageStream({
-    activeSessionIdRef,
-    hydrateFromStoredSession: vi.fn(async () => undefined),
-    queryClient: queryClientRef.current,
-    refreshHermesConfig: vi.fn(async () => undefined),
-    refreshSessions: vi.fn(async () => undefined),
-    sessionStateByRuntimeIdRef,
-    updateSessionState: (sessionId, updater) => {
-      const next = updater(sessionStates.get(sessionId) ?? createClientSessionState())
-      sessionStates.set(sessionId, next)
-
-      return next
-    }
-  })
-
-  useEffect(() => {
-    handleEvent = stream.handleGatewayEvent
-  }, [stream.handleGatewayEvent])
-
-  return null
-}
-
-async function mountStream() {
-  render(<Harness />)
-  await waitFor(() => expect(handleEvent).not.toBeNull())
+function mountStream() {
+  stream = renderMessageStream(SID, { states: sessionStates })
 }
 
 function emit(type: RpcEvent['type'], payload: RpcEvent['payload'] = {}, sessionId = SID) {
-  act(() => handleEvent!({ payload, session_id: sessionId, type }))
+  act(() => stream.handleEvent({ payload, session_id: sessionId, type }))
 }
 
 function draftedTool(sessionId = SID) {
@@ -60,7 +30,6 @@ function draftedTool(sessionId = SID) {
 
 describe('drafting-tool label lifecycle', () => {
   beforeEach(() => {
-    handleEvent = null
     sessionStates.clear()
     $draftingToolSessions.set({})
   })
@@ -72,8 +41,8 @@ describe('drafting-tool label lifecycle', () => {
     vi.restoreAllMocks()
   })
 
-  it('names the tool the model is drafting', async () => {
-    await mountStream()
+  it('names the tool the model is drafting', () => {
+    mountStream()
 
     emit('tool.generating', { name: 'write_file' })
 
@@ -92,8 +61,8 @@ describe('drafting-tool label lifecycle', () => {
     ['tool.complete', { name: 'terminal', tool_id: 'tool-1' }],
     ['message.complete', { text: 'done' }],
     ['error', { message: 'boom' }]
-  ] as const)('retires the label when %s proves the model moved on', async (type, payload) => {
-    await mountStream()
+  ] as const)('retires the label when %s proves the model moved on', (type, payload) => {
+    mountStream()
     emit('tool.generating', { name: 'write_file' })
 
     emit(type, payload)
@@ -101,8 +70,8 @@ describe('drafting-tool label lifecycle', () => {
     expect(draftedTool()).toBeUndefined()
   })
 
-  it('leaves another session’s label alone', async () => {
-    await mountStream()
+  it('leaves another session’s label alone', () => {
+    mountStream()
     emit('tool.generating', { name: 'patch' }, OTHER_SID)
     emit('tool.generating', { name: 'write_file' })
 
@@ -113,9 +82,9 @@ describe('drafting-tool label lifecycle', () => {
   })
 
   // A stopped turn can still emit a frame or two before the backend notices.
-  it('ignores a tool announced after the user hit stop', async () => {
+  it('ignores a tool announced after the user hit stop', () => {
     sessionStates.set(SID, { ...createClientSessionState(), interrupted: true })
-    await mountStream()
+    mountStream()
 
     emit('tool.generating', { name: 'write_file' })
 
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/usage.test.tsx b/apps/desktop/src/app/session/hooks/use-message-stream/usage.test.tsx
index 924e845dd0..a610d316c7 100644
--- a/apps/desktop/src/app/session/hooks/use-message-stream/usage.test.tsx
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/usage.test.tsx
@@ -1,59 +1,26 @@
-import { QueryClient } from '@tanstack/react-query'
-import { act, cleanup, render, waitFor } from '@testing-library/react'
-import { useEffect, useRef } from 'react'
+import { act, cleanup } from '@testing-library/react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 import type { ClientSessionState } from '@/app/types'
 import { createClientSessionState } from '@/lib/chat-runtime'
 import { $currentUsage } from '@/store/session'
-import type { RpcEvent } from '@/types/hermes'
 
-import { useMessageStream } from './index'
+import { type MessageStreamHarness, renderMessageStream } from './test-harness'
 
 const SID = 'session-1'
 // $currentUsage mirrors the primary session; ClientSessionState.usage drives
 // the same status bar when a secondary tile is focused.
 const BASELINE = { calls: 2, input: 500, output: 40, total: 540 }
 
-let handleEvent: ((event: RpcEvent) => void) | null = null
+let stream: MessageStreamHarness
 let sessionStates = new Map<string, ClientSessionState>()
 
-function Harness() {
-  const activeSessionIdRef = useRef<string | null>(SID)
-  const sessionStateByRuntimeIdRef = useRef(sessionStates)
-  const queryClientRef = useRef(new QueryClient())
-
-  const stream = useMessageStream({
-    activeSessionIdRef,
-    hydrateFromStoredSession: vi.fn(async () => undefined),
-    queryClient: queryClientRef.current,
-    refreshHermesConfig: vi.fn(async () => undefined),
-    refreshSessions: vi.fn(async () => undefined),
-    sessionStateByRuntimeIdRef,
-    updateSessionState: (sessionId, updater) => {
-      const current = sessionStateByRuntimeIdRef.current.get(sessionId) ?? createClientSessionState()
-      const next = updater(current)
-      sessionStateByRuntimeIdRef.current.set(sessionId, next)
-
-      return next
-    }
-  })
-
-  useEffect(() => {
-    handleEvent = stream.handleGatewayEvent
-  }, [stream.handleGatewayEvent])
-
-  return null
-}
-
-async function mountStream() {
-  render(<Harness />)
-  await waitFor(() => expect(handleEvent).not.toBeNull())
+function mountStream() {
+  stream = renderMessageStream(SID, { states: sessionStates })
 }
 
 describe('useMessageStream status-bar usage scoping', () => {
   beforeEach(() => {
-    handleEvent = null
     sessionStates = new Map([[SID, { ...createClientSessionState(), usage: { ...BASELINE } }]])
     $currentUsage.set({ ...BASELINE })
   })
@@ -63,11 +30,11 @@ describe('useMessageStream status-bar usage scoping', () => {
     vi.restoreAllMocks()
   })
 
-  it('merges a live session.usage tick from the focused session', async () => {
-    await mountStream()
+  it('merges a live session.usage tick from the focused session', () => {
+    mountStream()
 
     act(() =>
-      handleEvent!({
+      stream.handleEvent({
         payload: { usage: { context_percent: 42, input: 1200, total: 1280 } },
         session_id: SID,
         type: 'session.usage'
@@ -84,11 +51,11 @@ describe('useMessageStream status-bar usage scoping', () => {
     })
   })
 
-  it('caches a background session.usage tick without overwriting the primary status bar', async () => {
-    await mountStream()
+  it('caches a background session.usage tick without overwriting the primary status bar', () => {
+    mountStream()
 
     act(() =>
-      handleEvent!({
+      stream.handleEvent({
         payload: { usage: { input: 9999, total: 9999 } },
         session_id: 'background-session',
         type: 'session.usage'
@@ -104,11 +71,11 @@ describe('useMessageStream status-bar usage scoping', () => {
     })
   })
 
-  it('applies message.complete usage from the focused session', async () => {
-    await mountStream()
+  it('applies message.complete usage from the focused session', () => {
+    mountStream()
 
     act(() =>
-      handleEvent!({
+      stream.handleEvent({
         payload: { text: 'done', usage: { calls: 3, input: 1500, output: 90, total: 1590 } },
         session_id: SID,
         type: 'message.complete'
@@ -118,11 +85,11 @@ describe('useMessageStream status-bar usage scoping', () => {
     expect($currentUsage.get()).toEqual({ calls: 3, input: 1500, output: 90, total: 1590 })
   })
 
-  it('ignores message.complete usage from a background session', async () => {
-    await mountStream()
+  it('ignores message.complete usage from a background session', () => {
+    mountStream()
 
     act(() =>
-      handleEvent!({
+      stream.handleEvent({
         payload: { text: 'done', usage: { calls: 9, input: 9999, output: 999, total: 9999 } },
         session_id: 'background-session',
         type: 'message.complete'
diff --git a/apps/desktop/src/app/session/hooks/use-model-controls.test.tsx b/apps/desktop/src/app/session/hooks/use-model-controls.test.tsx
index 71296aa8f3..f3b9c5e020 100644
--- a/apps/desktop/src/app/session/hooks/use-model-controls.test.tsx
+++ b/apps/desktop/src/app/session/hooks/use-model-controls.test.tsx
@@ -16,21 +16,13 @@ import {
 } from '@/store/session'
 import type * as SessionStates from '@/store/session-states'
 
+import { deferred } from '../../../test/deferred'
+
 import { useModelControls } from './use-model-controls'
 
 const setGlobalModel = vi.fn()
 const notifyError = vi.fn()
 
-function deferred<T>() {
-  let resolve!: (value: T | PromiseLike<T>) => void
-
-  const promise = new Promise<T>(done => {
-    resolve = done
-  })
-
-  return { promise, resolve }
-}
-
 vi.mock('@/hermes', () => ({
   getGlobalModelInfo: vi.fn(),
   setApiRequestProfile: vi.fn(),
diff --git a/apps/desktop/src/app/session/hooks/use-prompt-actions/rewind.test.ts b/apps/desktop/src/app/session/hooks/use-prompt-actions/rewind.test.ts
index a7b785bad4..43d16f79a2 100644
--- a/apps/desktop/src/app/session/hooks/use-prompt-actions/rewind.test.ts
+++ b/apps/desktop/src/app/session/hooks/use-prompt-actions/rewind.test.ts
@@ -139,7 +139,7 @@ describe('truncateSubmitParams', () => {
   })
 
   it('drops renderer-synthetic message ids but keeps durable row ids', () => {
-    // chat-messages.ts: `${timestamp}-${index}-${role}`
+    // chat-messages/hydration.ts: `${timestamp}-${index}-${role}`
     expect(truncateSubmitParams(1, '1723456789-0-user', 456)).toEqual({
       confirm_truncate: true,
       truncate_before_user_ordinal: 1,
@@ -490,7 +490,7 @@ describe('runRewindSubmit durable-address discipline (#87059)', () => {
 })
 
 describe('optimistic rewind/reload turn-clock seeding (#86795)', () => {
-  // The no-payload settle gate in gateway-event.ts holds a running=false
+  // The no-payload settle gate in gateway-event/session-info.ts holds a running=false
   // heartbeat off while an optimistically armed turn waits for the backend —
   // but only for a bounded grace window measured from turnStartedAt. These
   // transforms are the arm sites for restore/edit/regenerate, so they must
diff --git a/apps/desktop/src/app/session/hooks/use-session-actions.test.tsx b/apps/desktop/src/app/session/hooks/use-session-actions.test.tsx
index 5a0c89a754..1ab86bcb92 100644
--- a/apps/desktop/src/app/session/hooks/use-session-actions.test.tsx
+++ b/apps/desktop/src/app/session/hooks/use-session-actions.test.tsx
@@ -49,6 +49,7 @@ import {
 import { $sessionTiles } from '@/store/session-states'
 
 import sessionResumeActiveTurn from '../../../../../../tests/fixtures/session-resume-active-turn.json'
+import { deferred } from '../../../test/deferred'
 import { sessionRoute } from '../../routes'
 import type { ClientSessionState } from '../../types'
 
@@ -79,16 +80,6 @@ vi.mock('@/components/pane-shell/tree/store', async importOriginal => ({
 
 const RUNTIME_SESSION_ID = 'rt-new-001'
 
-function deferred<T>() {
-  let resolve!: (value: T | PromiseLike<T>) => void
-
-  const promise = new Promise<T>(done => {
-    resolve = done
-  })
-
-  return { promise, resolve }
-}
-
 type HarnessHandle = Pick<
   ReturnType<typeof useSessionActions>,
   'createBackendSessionForSend' | 'selectSidebarItem' | 'startFreshSessionDraft'
diff --git a/apps/desktop/src/app/session/hooks/use-session-list-actions.test.tsx b/apps/desktop/src/app/session/hooks/use-session-list-actions.test.tsx
index a78dc433cb..79456f627b 100644
--- a/apps/desktop/src/app/session/hooks/use-session-list-actions.test.tsx
+++ b/apps/desktop/src/app/session/hooks/use-session-list-actions.test.tsx
@@ -18,6 +18,8 @@ import {
   setSessionsLoading
 } from '@/store/session'
 
+import { deferred } from '../../../test/deferred'
+
 import { useSessionListActions } from './use-session-list-actions'
 
 // Sidebar refresh hygiene: a content-identical refresh (turn complete,
@@ -68,15 +70,6 @@ interface Deferred<T> {
 }
 
 /** Create a promise whose completion order the stale-response tests control. */
-function deferred<T>(): Deferred<T> {
-  let resolve!: (value: T) => void
-
-  const promise = new Promise<T>(done => {
-    resolve = done
-  })
-
-  return { promise, resolve }
-}
 
 vi.mock('@/hermes', async importOriginal => ({
   ...(await importOriginal<Record<string, unknown>>()),
diff --git a/apps/desktop/src/app/session/workspace-session-target.test.ts b/apps/desktop/src/app/session/workspace-session-target.test.ts
index 3a83f605a3..4a3ff10d4b 100644
--- a/apps/desktop/src/app/session/workspace-session-target.test.ts
+++ b/apps/desktop/src/app/session/workspace-session-target.test.ts
@@ -9,18 +9,10 @@ import {
   setNewChatWorkspaceTarget
 } from '@/store/session'
 
+import { deferred } from '../../test/deferred'
+
 import { startWorkspaceSession } from './workspace-session-target'
 
-function deferred<T>() {
-  let resolve!: (value: T) => void
-
-  const promise = new Promise<T>(done => {
-    resolve = done
-  })
-
-  return { promise, resolve }
-}
-
 describe('startWorkspaceSession', () => {
   afterEach(() => {
     setCurrentBranch('')
diff --git a/apps/desktop/src/app/settings/keys-settings.test.tsx b/apps/desktop/src/app/settings/keys-settings.test.tsx
index 483be4eb33..87217b2e15 100644
--- a/apps/desktop/src/app/settings/keys-settings.test.tsx
+++ b/apps/desktop/src/app/settings/keys-settings.test.tsx
@@ -2,17 +2,13 @@ import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-libra
 import { MemoryRouter, useNavigate } from 'react-router'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
-import type { EnvVarInfo } from '@/types/hermes'
+import { stubResizeObserver } from '@/test/jsdom'
+
+import { envVar } from './test-utils'
 
 const getEnvVars = vi.fn()
 
-class TestResizeObserver {
-  observe() {}
-  unobserve() {}
-  disconnect() {}
-}
-
-vi.stubGlobal('ResizeObserver', TestResizeObserver)
+stubResizeObserver()
 
 vi.mock('@/hermes', () => ({
   deleteEnvVar: vi.fn(),
@@ -22,20 +18,6 @@ vi.mock('@/hermes', () => ({
   setEnvVar: vi.fn()
 }))
 
-function envVar(category: string, patch: Partial<EnvVarInfo> = {}): EnvVarInfo {
-  return {
-    advanced: false,
-    category,
-    description: '',
-    is_password: true,
-    is_set: false,
-    redacted_value: null,
-    tools: [],
-    url: '',
-    ...patch
-  }
-}
-
 beforeEach(() => {
   getEnvVars.mockResolvedValue({})
   Object.defineProperty(Element.prototype, 'scrollIntoView', {
diff --git a/apps/desktop/src/app/settings/searchable-select.test.tsx b/apps/desktop/src/app/settings/searchable-select.test.tsx
index 2e87c15c92..61f0d77ffa 100644
--- a/apps/desktop/src/app/settings/searchable-select.test.tsx
+++ b/apps/desktop/src/app/settings/searchable-select.test.tsx
@@ -1,21 +1,14 @@
 import { cleanup, fireEvent, render, screen } from '@testing-library/react'
 import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest'
 
+import { stubResizeObserver } from '@/test/jsdom'
 import type { ConfigFieldSchema } from '@/types/hermes'
 
 import { ConfigField } from './config-field'
 import { rankSearchOption, SearchableSelect } from './searchable-select'
 
-// Radix Popover + cmdk call scrollIntoView / pointer-capture / ResizeObserver
-// APIs jsdom lacks.
-class TestResizeObserver {
-  disconnect() {}
-  observe() {}
-  unobserve() {}
-}
-
 beforeAll(() => {
-  vi.stubGlobal('ResizeObserver', TestResizeObserver)
+  stubResizeObserver()
   Element.prototype.scrollIntoView = vi.fn()
   Element.prototype.hasPointerCapture = vi.fn(() => false)
   Element.prototype.releasePointerCapture = vi.fn()
diff --git a/apps/desktop/src/app/settings/settings-search.test.ts b/apps/desktop/src/app/settings/settings-search.test.ts
index 051a9a643b..34935cc9b7 100644
--- a/apps/desktop/src/app/settings/settings-search.test.ts
+++ b/apps/desktop/src/app/settings/settings-search.test.ts
@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest'
 
 import { Settings2, Wrench } from '@/lib/icons'
-import type { ConfigFieldSchema, EnvVarInfo, HermesConfigRecord } from '@/types/hermes'
+import type { ConfigFieldSchema, HermesConfigRecord } from '@/types/hermes'
 
 import {
   buildConfigSearchEntries,
@@ -9,20 +9,7 @@ import {
   credentialSettingsView,
   filterSettingsSearchEntries
 } from './settings-search'
-
-function envVar(category: string, patch: Partial<EnvVarInfo> = {}): EnvVarInfo {
-  return {
-    advanced: false,
-    category,
-    description: '',
-    is_password: true,
-    is_set: false,
-    redacted_value: null,
-    tools: [],
-    url: '',
-    ...patch
-  }
-}
+import { envVar } from './test-utils'
 
 const searchCopy = {
   fieldDescriptions: {
diff --git a/apps/desktop/src/app/settings/test-utils.ts b/apps/desktop/src/app/settings/test-utils.ts
new file mode 100644
index 0000000000..92f8eab966
--- /dev/null
+++ b/apps/desktop/src/app/settings/test-utils.ts
@@ -0,0 +1,17 @@
+import type { EnvVarInfo } from '@/types/hermes'
+
+/** An unset secret in `category`. The Keys tab and the settings search both
+ *  bucket by category and branch on `is_set`, so those are what tests vary. */
+export function envVar(category: string, patch: Partial<EnvVarInfo> = {}): EnvVarInfo {
+  return {
+    advanced: false,
+    category,
+    description: '',
+    is_password: true,
+    is_set: false,
+    redacted_value: null,
+    tools: [],
+    url: '',
+    ...patch
+  }
+}
diff --git a/apps/desktop/src/app/shell/approval-mode-menu.test.tsx b/apps/desktop/src/app/shell/approval-mode-menu.test.tsx
index 040471a19e..4702fc7abd 100644
--- a/apps/desktop/src/app/shell/approval-mode-menu.test.tsx
+++ b/apps/desktop/src/app/shell/approval-mode-menu.test.tsx
@@ -5,21 +5,13 @@ import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest'
 import { StatusbarControls } from '@/app/shell/statusbar-controls'
 import { I18nProvider } from '@/i18n'
 import { $approvalModes } from '@/store/approval-mode'
+import { stubMenuDomApis, stubResizeObserver } from '@/test/jsdom'
 
 import { useApprovalModeStatusbarItem } from './approval-mode-menu'
 
-class TestResizeObserver {
-  observe() {}
-  unobserve() {}
-  disconnect() {}
-}
-
 beforeAll(() => {
-  vi.stubGlobal('ResizeObserver', TestResizeObserver)
-  Element.prototype.hasPointerCapture ??= () => false
-  Element.prototype.setPointerCapture ??= () => undefined
-  Element.prototype.releasePointerCapture ??= () => undefined
-  HTMLElement.prototype.scrollIntoView ??= () => undefined
+  stubResizeObserver()
+  stubMenuDomApis()
 })
 
 afterEach(() => {
diff --git a/apps/desktop/src/app/shell/hooks/use-status-snapshot.test.ts b/apps/desktop/src/app/shell/hooks/use-status-snapshot.test.ts
index 547fef6876..94859b09ad 100644
--- a/apps/desktop/src/app/shell/hooks/use-status-snapshot.test.ts
+++ b/apps/desktop/src/app/shell/hooks/use-status-snapshot.test.ts
@@ -3,6 +3,8 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 import { getStatus } from '@/hermes'
 
+import { deferred } from '../../../test/deferred'
+
 import { useStatusSnapshot } from './use-status-snapshot'
 
 vi.mock('@/hermes', () => ({
@@ -11,18 +13,6 @@ vi.mock('@/hermes', () => ({
 
 type GatewayRequester = <T = unknown>(method: string, params?: Record<string, unknown>) => Promise<T>
 
-function deferred<T>() {
-  let resolve: (value: T) => void = () => undefined
-  let reject: (reason?: unknown) => void = () => undefined
-
-  const promise = new Promise<T>((nextResolve, nextReject) => {
-    resolve = nextResolve
-    reject = nextReject
-  })
-
-  return { promise, reject, resolve }
-}
-
 async function flushAsync() {
   await act(async () => {
     await vi.advanceTimersByTimeAsync(0)
diff --git a/apps/desktop/src/app/shell/statusbar-visibility.test.tsx b/apps/desktop/src/app/shell/statusbar-visibility.test.tsx
index e65f272e05..d558c11d11 100644
--- a/apps/desktop/src/app/shell/statusbar-visibility.test.tsx
+++ b/apps/desktop/src/app/shell/statusbar-visibility.test.tsx
@@ -1,6 +1,6 @@
 import { cleanup, fireEvent, render, screen, within } from '@testing-library/react'
 import { MemoryRouter } from 'react-router'
-import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest'
+import { afterEach, beforeAll, describe, expect, it } from 'vitest'
 
 import { StatusbarControls, type StatusbarItem } from '@/app/shell/statusbar-controls'
 import {
@@ -9,19 +9,11 @@ import {
   STATUSBAR_HIDDEN_BY_DEFAULT,
   toggleStatusbarVisible
 } from '@/store/statusbar-prefs'
-
-class TestResizeObserver {
-  observe() {}
-  unobserve() {}
-  disconnect() {}
-}
+import { stubMenuDomApis, stubResizeObserver } from '@/test/jsdom'
 
 beforeAll(() => {
-  vi.stubGlobal('ResizeObserver', TestResizeObserver)
-  Element.prototype.hasPointerCapture ??= () => false
-  Element.prototype.setPointerCapture ??= () => undefined
-  Element.prototype.releasePointerCapture ??= () => undefined
-  HTMLElement.prototype.scrollIntoView ??= () => undefined
+  stubResizeObserver()
+  stubMenuDomApis()
 })
 
 afterEach(() => {
diff --git a/apps/desktop/src/components/assistant-ui/test-utils.tsx b/apps/desktop/src/components/assistant-ui/test-utils.tsx
new file mode 100644
index 0000000000..f17284ec0a
--- /dev/null
+++ b/apps/desktop/src/components/assistant-ui/test-utils.tsx
@@ -0,0 +1,86 @@
+import { AssistantRuntimeProvider, type ThreadMessage, useExternalStoreRuntime } from '@assistant-ui/react'
+import type { ReactNode } from 'react'
+import { vi } from 'vitest'
+
+import { stubResizeObserver } from '@/test/jsdom'
+
+/** Fixed clock for message fixtures, so nothing sorts by "now". */
+export const createdAt = new Date('2026-05-01T00:00:00.000Z')
+
+/** The browser APIs the transcript renders against — a resize observer,
+ *  animation frames, `CSS.escape` for its selector lookups, and the scroll and
+ *  WAAPI calls the message list makes on mount. jsdom has none of them, and a
+ *  thread that cannot mount fails every assertion in the file for the wrong
+ *  reason. */
+export function stubThreadEnvironment() {
+  stubResizeObserver()
+
+  vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) =>
+    window.setTimeout(() => callback(performance.now()), 0)
+  )
+  vi.stubGlobal('cancelAnimationFrame', (id: number) => window.clearTimeout(id))
+  vi.stubGlobal('CSS', { escape: (value: string) => value })
+
+  Element.prototype.scrollTo = function scrollTo() {}
+
+  Element.prototype.animate = function animate() {
+    return { cancel() {}, finished: Promise.resolve() } as unknown as Animation
+  }
+}
+
+/** Give jsdom a viewport that the thread's virtualizer treats as scrollable.
+ *
+ *  jsdom reports every `offsetWidth`/`offsetHeight` as 0, which makes the
+ *  message list measure itself as having no room and skip the rendering paths
+ *  these tests are about. The stub falls through to a real value when one
+ *  exists, so a test that sets its own dimensions still wins. */
+export function stubThreadViewportSize() {
+  const stub = (prop: 'offsetHeight' | 'offsetWidth', clientProp: 'clientHeight' | 'clientWidth', fallback: number) => {
+    const previous = Object.getOwnPropertyDescriptor(HTMLElement.prototype, prop)
+
+    Object.defineProperty(HTMLElement.prototype, prop, {
+      configurable: true,
+      get() {
+        return previous?.get?.call(this) || (this as HTMLElement)[clientProp] || fallback
+      }
+    })
+  }
+
+  stub('offsetWidth', 'clientWidth', 800)
+  stub('offsetHeight', 'clientHeight', 600)
+}
+
+/** Wrap a transcript subtree in a runtime driven by a fixed message list, the
+ *  way the app's external store drives it: the thread is running while the tail
+ *  message is. */
+export function ThreadRuntime({ children, messages }: { children: ReactNode; messages: ThreadMessage[] }) {
+  const runtime = useExternalStoreRuntime<ThreadMessage>({
+    messages,
+    isRunning: messages.at(-1)?.status?.type === 'running',
+    onNew: async () => {}
+  })
+
+  return <AssistantRuntimeProvider runtime={runtime}>{children}</AssistantRuntimeProvider>
+}
+
+export function userMessage(id = 'user-1', text = 'edit me please'): ThreadMessage {
+  return {
+    id,
+    role: 'user',
+    content: [{ type: 'text', text }],
+    attachments: [],
+    createdAt,
+    metadata: { custom: {} }
+  } as ThreadMessage
+}
+
+export function assistantMessage(): ThreadMessage {
+  return {
+    id: 'assistant-1',
+    role: 'assistant',
+    content: [{ type: 'text', text: 'done' }],
+    status: { type: 'complete', reason: 'stop' },
+    createdAt,
+    metadata: { unstable_state: null, unstable_annotations: [], unstable_data: [], steps: [], custom: {} }
+  } as ThreadMessage
+}
diff --git a/apps/desktop/src/components/assistant-ui/thread-remount.test.tsx b/apps/desktop/src/components/assistant-ui/thread-remount.test.tsx
index 88454751e1..5ec52f4c75 100644
--- a/apps/desktop/src/components/assistant-ui/thread-remount.test.tsx
+++ b/apps/desktop/src/components/assistant-ui/thread-remount.test.tsx
@@ -1,54 +1,12 @@
 import { AssistantRuntimeProvider, type ThreadMessage, useExternalStoreRuntime } from '@assistant-ui/react'
 import { act, render, screen, waitFor } from '@testing-library/react'
-import { describe, expect, it, vi } from 'vitest'
+import { describe, expect, it } from 'vitest'
 
+import { createdAt, stubThreadEnvironment, stubThreadViewportSize } from './test-utils'
 import { Thread } from './thread'
 
-class NoopResizeObserver {
-  observe() {}
-
-  unobserve() {}
-
-  disconnect() {}
-}
-
-vi.stubGlobal('ResizeObserver', NoopResizeObserver)
-vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) =>
-  window.setTimeout(() => callback(performance.now()), 0)
-)
-vi.stubGlobal('cancelAnimationFrame', (id: number) => window.clearTimeout(id))
-
-Element.prototype.scrollTo = function scrollTo() {}
-
-Element.prototype.animate = function animate() {
-  return {
-    cancel: () => {},
-    finished: Promise.resolve()
-  } as unknown as Animation
-}
-
-// jsdom returns 0 for offset*; the virtualizer reads those to size its
-// viewport. Fall through to client* or a sane default so virtualized
-// items render (same stub as streaming.test.tsx).
-function stubOffsetDimension(
-  prop: 'offsetHeight' | 'offsetWidth',
-  clientProp: 'clientHeight' | 'clientWidth',
-  fallback: number
-) {
-  const previous = Object.getOwnPropertyDescriptor(HTMLElement.prototype, prop)
-
-  Object.defineProperty(HTMLElement.prototype, prop, {
-    configurable: true,
-    get() {
-      return previous?.get?.call(this) || (this as HTMLElement)[clientProp] || fallback
-    }
-  })
-}
-
-stubOffsetDimension('offsetWidth', 'clientWidth', 800)
-stubOffsetDimension('offsetHeight', 'clientHeight', 600)
-
-const createdAt = new Date('2026-05-01T00:00:00.000Z')
+stubThreadEnvironment()
+stubThreadViewportSize()
 
 const MESSAGES: ThreadMessage[] = [
   {
diff --git a/apps/desktop/src/components/assistant-ui/thread/assistant-message.test.tsx b/apps/desktop/src/components/assistant-ui/thread/assistant-message.test.tsx
index 986c4a4248..82f1f44b54 100644
--- a/apps/desktop/src/components/assistant-ui/thread/assistant-message.test.tsx
+++ b/apps/desktop/src/components/assistant-ui/thread/assistant-message.test.tsx
@@ -6,10 +6,12 @@
 // supplied, matching how onDismissError/onRestoreToMessage already behave.
 import { AssistantRuntimeProvider, type ThreadMessage, useExternalStoreRuntime } from '@assistant-ui/react'
 import { cleanup, render, screen } from '@testing-library/react'
-import { afterEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, describe, expect, it } from 'vitest'
 
 import { $displayTimestamps } from '@/store/display-timestamps'
 
+import { stubThreadEnvironment } from '../test-utils'
+
 import { formatTimelineRange, formatTimelineTimestamp } from './timestamp'
 
 import { Thread } from '.'
@@ -19,20 +21,7 @@ $displayTimestamps.set(true)
 
 const createdAt = new Date('2026-05-01T00:00:00.000Z')
 const completedAt = createdAt.getTime() / 1000 + 1.25
-
-class TestResizeObserver {
-  observe() {}
-  unobserve() {}
-  disconnect() {}
-}
-vi.stubGlobal('ResizeObserver', TestResizeObserver)
-vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) =>
-  window.setTimeout(() => callback(performance.now()), 0)
-)
-vi.stubGlobal('cancelAnimationFrame', (id: number) => window.clearTimeout(id))
-vi.stubGlobal('CSS', { escape: (str: string) => str })
-
-Element.prototype.scrollTo = function scrollTo() {}
+stubThreadEnvironment()
 
 afterEach(() => {
   cleanup()
diff --git a/apps/desktop/src/components/assistant-ui/thread/block-direction.test.tsx b/apps/desktop/src/components/assistant-ui/thread/block-direction.test.tsx
index 227f9e63b0..62711211ab 100644
--- a/apps/desktop/src/components/assistant-ui/thread/block-direction.test.tsx
+++ b/apps/desktop/src/components/assistant-ui/thread/block-direction.test.tsx
@@ -8,44 +8,16 @@
 // resolve dir="auto", so the contract is asserted at the attribute level.
 import { AssistantRuntimeProvider, type ThreadMessage, useExternalStoreRuntime } from '@assistant-ui/react'
 import { render, screen } from '@testing-library/react'
-import { describe, expect, it, vi } from 'vitest'
+import { describe, expect, it } from 'vitest'
+
+import { stubThreadEnvironment, stubThreadViewportSize } from '../test-utils'
 
 import { Thread } from '.'
 
 const createdAt = new Date('2026-06-01T00:00:00.000Z')
+stubThreadEnvironment()
 
-class TestResizeObserver {
-  observe() {}
-  unobserve() {}
-  disconnect() {}
-}
-
-vi.stubGlobal('ResizeObserver', TestResizeObserver)
-vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) =>
-  window.setTimeout(() => callback(performance.now()), 0)
-)
-vi.stubGlobal('cancelAnimationFrame', (id: number) => window.clearTimeout(id))
-vi.stubGlobal('CSS', { escape: (str: string) => str })
-
-Element.prototype.scrollTo = function scrollTo() {}
-
-function stubOffsetDimension(
-  prop: 'offsetHeight' | 'offsetWidth',
-  clientProp: 'clientHeight' | 'clientWidth',
-  fallback: number
-) {
-  const previous = Object.getOwnPropertyDescriptor(HTMLElement.prototype, prop)
-
-  Object.defineProperty(HTMLElement.prototype, prop, {
-    configurable: true,
-    get() {
-      return previous?.get?.call(this) || (this as HTMLElement)[clientProp] || fallback
-    }
-  })
-}
-
-stubOffsetDimension('offsetWidth', 'clientWidth', 800)
-stubOffsetDimension('offsetHeight', 'clientHeight', 600)
+stubThreadViewportSize()
 
 function userMessage(): ThreadMessage {
   return {
diff --git a/apps/desktop/src/components/assistant-ui/thread/double-click-reaction.test.tsx b/apps/desktop/src/components/assistant-ui/thread/double-click-reaction.test.tsx
index 20ee08f1c6..67a7016b7f 100644
--- a/apps/desktop/src/components/assistant-ui/thread/double-click-reaction.test.tsx
+++ b/apps/desktop/src/components/assistant-ui/thread/double-click-reaction.test.tsx
@@ -8,25 +8,12 @@ import type * as ReactionsStore from '@/store/reactions'
 import { $reactionsEnabled } from '@/store/reactions-enabled'
 import { $localReactions } from '@/store/reactions-local'
 
+import { assistantMessage, stubThreadEnvironment } from '../test-utils'
+
 import { isTapbackDoubleClick } from './use-message-reactions'
 
 import { Thread } from '.'
-
-const createdAt = new Date('2026-05-01T00:00:00.000Z')
-
-class TestResizeObserver {
-  observe() {}
-  unobserve() {}
-  disconnect() {}
-}
-vi.stubGlobal('ResizeObserver', TestResizeObserver)
-vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) =>
-  window.setTimeout(() => callback(performance.now()), 0)
-)
-vi.stubGlobal('cancelAnimationFrame', (id: number) => window.clearTimeout(id))
-vi.stubGlobal('CSS', { escape: (str: string) => str })
-
-Element.prototype.scrollTo = function scrollTo() {}
+stubThreadEnvironment()
 
 // The gesture persists through the gateway; this suite is about the local
 // paint, which is what the user actually sees on the click.
@@ -35,17 +22,6 @@ vi.mock('@/store/reactions', async importOriginal => ({
   toggleMessageReaction: vi.fn(async () => {})
 }))
 
-function assistantMessage(): ThreadMessage {
-  return {
-    id: 'assistant-1',
-    role: 'assistant',
-    content: [{ type: 'text', text: 'done' }],
-    status: { type: 'complete', reason: 'stop' },
-    createdAt,
-    metadata: { unstable_state: null, unstable_annotations: [], unstable_data: [], steps: [], custom: {} }
-  } as ThreadMessage
-}
-
 function Harness() {
   const runtime = useExternalStoreRuntime<ThreadMessage>({
     messages: [assistantMessage()],
diff --git a/apps/desktop/src/components/assistant-ui/thread/duplicate-activity-indicator.test.tsx b/apps/desktop/src/components/assistant-ui/thread/duplicate-activity-indicator.test.tsx
index ac659b99a5..b20846f776 100644
--- a/apps/desktop/src/components/assistant-ui/thread/duplicate-activity-indicator.test.tsx
+++ b/apps/desktop/src/components/assistant-ui/thread/duplicate-activity-indicator.test.tsx
@@ -11,65 +11,20 @@ import { __resetElapsedTimerRegistryForTests } from '@/components/chat/activity-
 import { setSessionCompacting } from '@/store/compaction'
 import { $activeSessionId, $turnStartedAt } from '@/store/session'
 
+import { stubThreadEnvironment, stubThreadViewportSize, userMessage } from '../test-utils'
+
 import { Thread } from '.'
 
 // Layout/observer stubs mirrored from streaming.test.tsx. jsdom has no
 // ResizeObserver, rAF, or real layout, and the Thread scroll container needs
 // non-zero dimensions to mount without throwing.
-class TestResizeObserver {
-  observe() {}
-  unobserve() {}
-  disconnect() {}
-}
+stubThreadEnvironment()
 
-vi.stubGlobal('ResizeObserver', TestResizeObserver)
-vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) =>
-  window.setTimeout(() => callback(performance.now()), 0)
-)
-vi.stubGlobal('cancelAnimationFrame', (id: number) => window.clearTimeout(id))
-vi.stubGlobal('CSS', { escape: (str: string) => str })
-
-Element.prototype.scrollTo = function scrollTo() {}
-
-Element.prototype.animate = function animate() {
-  return {
-    cancel: () => {},
-    finished: Promise.resolve()
-  } as unknown as Animation
-}
-
-function stubOffsetDimension(
-  prop: 'offsetHeight' | 'offsetWidth',
-  clientProp: 'clientHeight' | 'clientWidth',
-  fallback: number
-) {
-  const previous = Object.getOwnPropertyDescriptor(HTMLElement.prototype, prop)
-
-  Object.defineProperty(HTMLElement.prototype, prop, {
-    configurable: true,
-    get() {
-      return previous?.get?.call(this) || (this as HTMLElement)[clientProp] || fallback
-    }
-  })
-}
-
-stubOffsetDimension('offsetWidth', 'clientWidth', 800)
-stubOffsetDimension('offsetHeight', 'clientHeight', 600)
+stubThreadViewportSize()
 
 const createdAt = new Date('2026-05-01T00:00:00.000Z')
 const sessionId = 'session-68634'
 
-function userMessage(id: string, text: string): ThreadMessage {
-  return {
-    id,
-    role: 'user',
-    content: [{ type: 'text', text }],
-    attachments: [],
-    createdAt,
-    metadata: { custom: {} }
-  } as ThreadMessage
-}
-
 // This shape mirrors the `/steer` note appended by appendSessionTextMessage
 // in apps/desktop/src/app/session/hooks/use-prompt-actions/index.ts.
 function systemMessage(id: string, text: string): ThreadMessage {
diff --git a/apps/desktop/src/components/assistant-ui/thread/edit-context.test.tsx b/apps/desktop/src/components/assistant-ui/thread/edit-context.test.tsx
index f9c4f7129f..4c19447478 100644
--- a/apps/desktop/src/components/assistant-ui/thread/edit-context.test.tsx
+++ b/apps/desktop/src/components/assistant-ui/thread/edit-context.test.tsx
@@ -17,6 +17,8 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 import { useIncrementalExternalStoreRuntime } from '@/lib/incremental-external-store-runtime'
 
+import { assistantMessage, stubThreadEnvironment, stubThreadViewportSize, userMessage } from '../test-utils'
+
 import { Thread } from '.'
 
 interface MockComposerProps {
@@ -34,23 +36,7 @@ vi.mock('./user-edit-composer', () => ({
     return <div data-testid="edit-composer">{props.cwd}</div>
   }
 }))
-
-const createdAt = new Date('2026-05-01T00:00:00.000Z')
-
-class TestResizeObserver {
-  observe() {}
-  unobserve() {}
-  disconnect() {}
-}
-
-vi.stubGlobal('ResizeObserver', TestResizeObserver)
-vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) =>
-  window.setTimeout(() => callback(performance.now()), 0)
-)
-vi.stubGlobal('cancelAnimationFrame', (id: number) => window.clearTimeout(id))
-vi.stubGlobal('CSS', { escape: (str: string) => str })
-
-Element.prototype.scrollTo = function scrollTo() {}
+stubThreadEnvironment()
 
 afterEach(() => {
   cleanup()
@@ -60,54 +46,7 @@ beforeEach(() => {
   composerRenders.length = 0
 })
 
-// jsdom returns 0 for offset*; the virtualizer reads those to size its
-// viewport. Fall through to client* or a sane default so virtualized
-// items render (same stub as user-message-edit.test.tsx).
-function stubOffsetDimension(
-  prop: 'offsetHeight' | 'offsetWidth',
-  clientProp: 'clientHeight' | 'clientWidth',
-  fallback: number
-) {
-  const previous = Object.getOwnPropertyDescriptor(HTMLElement.prototype, prop)
-
-  Object.defineProperty(HTMLElement.prototype, prop, {
-    configurable: true,
-    get() {
-      return previous?.get?.call(this) || (this as HTMLElement)[clientProp] || fallback
-    }
-  })
-}
-
-stubOffsetDimension('offsetWidth', 'clientWidth', 800)
-stubOffsetDimension('offsetHeight', 'clientHeight', 600)
-
-function userMessage(): ThreadMessage {
-  return {
-    id: 'user-1',
-    role: 'user',
-    content: [{ type: 'text', text: 'edit me please' }],
-    attachments: [],
-    createdAt,
-    metadata: { custom: {} }
-  } as ThreadMessage
-}
-
-function assistantMessage(): ThreadMessage {
-  return {
-    id: 'assistant-1',
-    role: 'assistant',
-    content: [{ type: 'text', text: 'done' }],
-    status: { type: 'complete', reason: 'stop' },
-    createdAt,
-    metadata: {
-      unstable_state: null,
-      unstable_annotations: [],
-      unstable_data: [],
-      steps: [],
-      custom: {}
-    }
-  } as ThreadMessage
-}
+stubThreadViewportSize()
 
 const noopAsync = async () => {}
 
diff --git a/apps/desktop/src/components/assistant-ui/thread/status-tail-only.test.tsx b/apps/desktop/src/components/assistant-ui/thread/status-tail-only.test.tsx
index 1ec8feb7fc..8e2cf85ebf 100644
--- a/apps/desktop/src/components/assistant-ui/thread/status-tail-only.test.tsx
+++ b/apps/desktop/src/components/assistant-ui/thread/status-tail-only.test.tsx
@@ -3,32 +3,16 @@
 // there (missed settle event, steer race, upstream state bug) — must render
 // its content with no spinner: a live indicator above a later user message
 // reads as the agent answering out of order.
-import { AssistantRuntimeProvider, type ThreadMessage, useExternalStoreRuntime } from '@assistant-ui/react'
+import { type ThreadMessage } from '@assistant-ui/react'
 import { cleanup, render, screen } from '@testing-library/react'
-import { afterEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { stubThreadEnvironment, ThreadRuntime, userMessage } from '../test-utils'
 
 import { Thread } from '.'
 
 const createdAt = new Date('2026-05-01T00:00:00.000Z')
-
-class TestResizeObserver {
-  observe() {}
-  unobserve() {}
-  disconnect() {}
-}
-vi.stubGlobal('ResizeObserver', TestResizeObserver)
-vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) =>
-  window.setTimeout(() => callback(performance.now()), 0)
-)
-vi.stubGlobal('cancelAnimationFrame', (id: number) => window.clearTimeout(id))
-vi.stubGlobal('CSS', { escape: (str: string) => str })
-
-Element.prototype.scrollTo = function scrollTo() {}
-
-// Enter animation fires for running messages; jsdom has no WAAPI.
-Element.prototype.animate = function animate() {
-  return { cancel() {}, finished: Promise.resolve() } as unknown as Animation
-}
+stubThreadEnvironment()
 
 afterEach(() => {
   cleanup()
@@ -42,17 +26,6 @@ const assistantMetadata = {
   custom: {}
 }
 
-function user(id: string, text: string): ThreadMessage {
-  return {
-    id,
-    role: 'user',
-    content: [{ type: 'text', text }],
-    attachments: [],
-    createdAt,
-    metadata: { custom: {} }
-  } as ThreadMessage
-}
-
 function assistant(id: string, text: string, running: boolean): ThreadMessage {
   return {
     id,
@@ -64,23 +37,15 @@ function assistant(id: string, text: string, running: boolean): ThreadMessage {
   } as ThreadMessage
 }
 
-function Harness({ messages }: { messages: ThreadMessage[] }) {
-  const runtime = useExternalStoreRuntime<ThreadMessage>({
-    messages,
-    isRunning: messages.at(-1)?.status?.type === 'running',
-    onNew: async () => {}
-  })
-
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      <Thread />
-    </AssistantRuntimeProvider>
-  )
-}
+const Harness = ({ messages }: { messages: ThreadMessage[] }) => (
+  <ThreadRuntime messages={messages}>
+    <Thread />
+  </ThreadRuntime>
+)
 
 describe('thinking indicator is tail-only', () => {
   it('shows the loading indicator on a running placeholder at the tail', async () => {
-    const { container } = render(<Harness messages={[user('u1', 'question'), assistant('a1', '', true)]} />)
+    const { container } = render(<Harness messages={[userMessage('u1', 'question'), assistant('a1', '', true)]} />)
 
     expect(await screen.findByRole('status', { name: 'Hermes is loading a response' })).toBeTruthy()
     expect(container.querySelector('[data-slot="aui_response-loading"]')).toBeTruthy()
@@ -91,9 +56,9 @@ describe('thinking indicator is tail-only', () => {
     const { container } = render(
       <Harness
         messages={[
-          user('u1', 'first question'),
+          userMessage('u1', 'first question'),
           assistant('a1', '', true),
-          user('u2', 'second question'),
+          userMessage('u2', 'second question'),
           assistant('a2', 'answered', false)
         ]}
       />
diff --git a/apps/desktop/src/components/assistant-ui/thread/streaming.test.tsx b/apps/desktop/src/components/assistant-ui/thread/streaming.test.tsx
index 566e5b04e8..de9bb5cb8a 100644
--- a/apps/desktop/src/components/assistant-ui/thread/streaming.test.tsx
+++ b/apps/desktop/src/components/assistant-ui/thread/streaming.test.tsx
@@ -5,6 +5,8 @@ import { beforeEach, describe, expect, it, vi } from 'vitest'
 
 import { $reasoningCollapsedByDefault } from '@/store/reasoning-disclosure'
 
+import { stubThreadEnvironment, stubThreadViewportSize, ThreadRuntime } from '../test-utils'
+
 import { Thread } from '.'
 
 const createdAt = new Date('2026-05-01T00:00:00.000Z')
@@ -45,42 +47,12 @@ class TestResizeObserver {
   }
 }
 
+stubThreadEnvironment()
+
+// This suite drives the virtualizer, so it needs an observer that reports.
 vi.stubGlobal('ResizeObserver', TestResizeObserver)
-vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) =>
-  window.setTimeout(() => callback(performance.now()), 0)
-)
-vi.stubGlobal('cancelAnimationFrame', (id: number) => window.clearTimeout(id))
-vi.stubGlobal('CSS', { escape: (str: string) => str })
 
-Element.prototype.scrollTo = function scrollTo() {}
-
-Element.prototype.animate = function animate() {
-  return {
-    cancel: () => {},
-    finished: Promise.resolve()
-  } as unknown as Animation
-}
-
-// jsdom returns 0 for offset*; some layout code reads those to size the
-// viewport. Fall through to client* (which tests can override) or a sane
-// default so message rows render with non-zero dimensions.
-function stubOffsetDimension(
-  prop: 'offsetHeight' | 'offsetWidth',
-  clientProp: 'clientHeight' | 'clientWidth',
-  fallback: number
-) {
-  const previous = Object.getOwnPropertyDescriptor(HTMLElement.prototype, prop)
-
-  Object.defineProperty(HTMLElement.prototype, prop, {
-    configurable: true,
-    get() {
-      return previous?.get?.call(this) || (this as HTMLElement)[clientProp] || fallback
-    }
-  })
-}
-
-stubOffsetDimension('offsetWidth', 'clientWidth', 800)
-stubOffsetDimension('offsetHeight', 'clientHeight', 600)
+stubThreadViewportSize()
 
 async function wait(ms: number) {
   await act(async () => {
@@ -331,19 +303,11 @@ function StreamingHarness({ onControls }: { onControls?: (controls: StreamingCon
   )
 }
 
-function TodoHarness({ message }: { message: ThreadMessage }) {
-  const runtime = useExternalStoreRuntime<ThreadMessage>({
-    messages: [message],
-    isRunning: message.status?.type === 'running',
-    onNew: async () => {}
-  })
-
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      <Thread />
-    </AssistantRuntimeProvider>
-  )
-}
+const TodoHarness = ({ message }: { message: ThreadMessage }) => (
+  <ThreadRuntime messages={[message]}>
+    <Thread />
+  </ThreadRuntime>
+)
 
 function MessageHarness({ message }: { message: ThreadMessage }) {
   const runtime = useExternalStoreRuntime<ThreadMessage>({
diff --git a/apps/desktop/src/components/assistant-ui/thread/system-message.test.tsx b/apps/desktop/src/components/assistant-ui/thread/system-message.test.tsx
index d0249fc45a..14ea92d7ac 100644
--- a/apps/desktop/src/components/assistant-ui/thread/system-message.test.tsx
+++ b/apps/desktop/src/components/assistant-ui/thread/system-message.test.tsx
@@ -1,30 +1,18 @@
 import { AssistantRuntimeProvider, type ThreadMessage, useExternalStoreRuntime } from '@assistant-ui/react'
 import { cleanup, render } from '@testing-library/react'
-import { afterEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, describe, expect, it } from 'vitest'
 
 import { $displayTimestamps } from '@/store/display-timestamps'
 
+import { stubThreadEnvironment } from '../test-utils'
+
 import { Thread } from '.'
 
 // Timeline timestamps render only when `display.timestamps` is enabled.
 $displayTimestamps.set(true)
 
 const timestamp = new Date('2026-05-01T00:00:00.000Z')
-
-class TestResizeObserver {
-  observe() {}
-  unobserve() {}
-  disconnect() {}
-}
-
-vi.stubGlobal('ResizeObserver', TestResizeObserver)
-vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) =>
-  window.setTimeout(() => callback(performance.now()), 0)
-)
-vi.stubGlobal('cancelAnimationFrame', (id: number) => window.clearTimeout(id))
-vi.stubGlobal('CSS', { escape: (str: string) => str })
-
-Element.prototype.scrollTo = function scrollTo() {}
+stubThreadEnvironment()
 
 function Harness({ text }: { text: string }) {
   const message = {
diff --git a/apps/desktop/src/components/assistant-ui/thread/turn-gap-indicator.test.tsx b/apps/desktop/src/components/assistant-ui/thread/turn-gap-indicator.test.tsx
index f40b5b71a7..8554e7525f 100644
--- a/apps/desktop/src/components/assistant-ui/thread/turn-gap-indicator.test.tsx
+++ b/apps/desktop/src/components/assistant-ui/thread/turn-gap-indicator.test.tsx
@@ -2,48 +2,21 @@
 // is armed, but the tail bubble has settled — a sealed interim row, or a turn
 // whose last message completed while the agent kept going. The transcript used
 // to show nothing there, and the seconds went uncounted.
-import { AssistantRuntimeProvider, type ThreadMessage, useExternalStoreRuntime } from '@assistant-ui/react'
+import { type ThreadMessage } from '@assistant-ui/react'
 import { act, cleanup, render, screen } from '@testing-library/react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 import { __resetElapsedTimerRegistryForTests } from '@/components/chat/activity-timer'
 import { $activeSessionId, $busy, $messages, $turnStartedAt } from '@/store/session'
 
+import { stubThreadEnvironment, ThreadRuntime, userMessage } from '../test-utils'
+
 import { Thread } from '.'
-
-class TestResizeObserver {
-  observe() {}
-  unobserve() {}
-  disconnect() {}
-}
-
-vi.stubGlobal('ResizeObserver', TestResizeObserver)
-vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) =>
-  window.setTimeout(() => callback(performance.now()), 0)
-)
-vi.stubGlobal('cancelAnimationFrame', (id: number) => window.clearTimeout(id))
-vi.stubGlobal('CSS', { escape: (str: string) => str })
-
-Element.prototype.scrollTo = function scrollTo() {}
-
-Element.prototype.animate = function animate() {
-  return { cancel() {}, finished: Promise.resolve() } as unknown as Animation
-}
+stubThreadEnvironment()
 
 const createdAt = new Date('2026-05-01T00:00:00.000Z')
 const sessionId = 'session-turn-gap'
 
-function user(id: string, text: string): ThreadMessage {
-  return {
-    id,
-    role: 'user',
-    content: [{ type: 'text', text }],
-    attachments: [],
-    createdAt,
-    metadata: { custom: {} }
-  } as ThreadMessage
-}
-
 function assistant(id: string, content: unknown[], running: boolean): ThreadMessage {
   return {
     id,
@@ -63,19 +36,11 @@ const toolCall = (toolName: string, settled: boolean) => ({
   ...(settled ? { result: 'ok' } : {})
 })
 
-function Harness({ messages }: { messages: ThreadMessage[] }) {
-  const runtime = useExternalStoreRuntime<ThreadMessage>({
-    messages,
-    isRunning: messages.at(-1)?.status?.type === 'running',
-    onNew: async () => {}
-  })
-
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      <Thread />
-    </AssistantRuntimeProvider>
-  )
-}
+const Harness = ({ messages }: { messages: ThreadMessage[] }) => (
+  <ThreadRuntime messages={messages}>
+    <Thread />
+  </ThreadRuntime>
+)
 
 const timerText = (value: string) => screen.getAllByText((_, node) => node?.textContent === value)
 
@@ -106,7 +71,9 @@ describe('the turn timer covers the gaps, not just the streaming', () => {
     // is busy, so the transcript owes the user a line and a count — measured
     // from the last thing the turn produced, not from when the row appeared.
     const { container } = render(
-      <Harness messages={[user('u1', 'do the thing'), assistant('a1', [{ type: 'text', text: 'On it.' }], false)]} />
+      <Harness
+        messages={[userMessage('u1', 'do the thing'), assistant('a1', [{ type: 'text', text: 'On it.' }], false)]}
+      />
     )
 
     act(() => vi.advanceTimersByTime(7_000))
@@ -117,7 +84,7 @@ describe('the turn timer covers the gaps, not just the streaming', () => {
 
   it('times the gap between a finished tool call and the next thing', () => {
     const { container } = render(
-      <Harness messages={[user('u1', 'read it'), assistant('a1', [toolCall('read_file', true)], true)]} />
+      <Harness messages={[userMessage('u1', 'read it'), assistant('a1', [toolCall('read_file', true)], true)]} />
     )
 
     act(() => vi.advanceTimersByTime(9_000))
@@ -128,7 +95,7 @@ describe('the turn timer covers the gaps, not just the streaming', () => {
 
   it('stays silent under a tool call still in flight — that row has its own timer', () => {
     const { container } = render(
-      <Harness messages={[user('u1', 'run it'), assistant('a1', [toolCall('terminal', false)], true)]} />
+      <Harness messages={[userMessage('u1', 'run it'), assistant('a1', [toolCall('terminal', false)], true)]} />
     )
 
     act(() => vi.advanceTimersByTime(9_000))
@@ -140,7 +107,9 @@ describe('the turn timer covers the gaps, not just the streaming', () => {
     $busy.set(false)
 
     const { container } = render(
-      <Harness messages={[user('u1', 'do the thing'), assistant('a1', [{ type: 'text', text: 'Done.' }], false)]} />
+      <Harness
+        messages={[userMessage('u1', 'do the thing'), assistant('a1', [{ type: 'text', text: 'Done.' }], false)]}
+      />
     )
 
     act(() => vi.advanceTimersByTime(7_000))
diff --git a/apps/desktop/src/components/assistant-ui/thread/user-message-edit-gesture.test.tsx b/apps/desktop/src/components/assistant-ui/thread/user-message-edit-gesture.test.tsx
index b6deaa742d..2007730c8e 100644
--- a/apps/desktop/src/components/assistant-ui/thread/user-message-edit-gesture.test.tsx
+++ b/apps/desktop/src/components/assistant-ui/thread/user-message-edit-gesture.test.tsx
@@ -9,68 +9,16 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
 
 import { useIncrementalExternalStoreRuntime } from '@/lib/incremental-external-store-runtime'
 
+import { assistantMessage, stubThreadEnvironment, stubThreadViewportSize, userMessage } from '../test-utils'
+
 import { Thread } from '.'
-
-const createdAt = new Date('2026-05-01T00:00:00.000Z')
-
-class TestResizeObserver {
-  observe() {}
-  unobserve() {}
-  disconnect() {}
-}
-
-vi.stubGlobal('ResizeObserver', TestResizeObserver)
-vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) =>
-  window.setTimeout(() => callback(performance.now()), 0)
-)
-vi.stubGlobal('cancelAnimationFrame', (id: number) => window.clearTimeout(id))
-vi.stubGlobal('CSS', { escape: (str: string) => str })
-
-Element.prototype.scrollTo = function scrollTo() {}
+stubThreadEnvironment()
 
 afterEach(() => {
   cleanup()
 })
 
-function stubOffsetDimension(
-  prop: 'offsetHeight' | 'offsetWidth',
-  clientProp: 'clientHeight' | 'clientWidth',
-  fallback: number
-) {
-  const previous = Object.getOwnPropertyDescriptor(HTMLElement.prototype, prop)
-
-  Object.defineProperty(HTMLElement.prototype, prop, {
-    configurable: true,
-    get() {
-      return previous?.get?.call(this) || (this as HTMLElement)[clientProp] || fallback
-    }
-  })
-}
-
-stubOffsetDimension('offsetWidth', 'clientWidth', 800)
-stubOffsetDimension('offsetHeight', 'clientHeight', 600)
-
-function userMessage(): ThreadMessage {
-  return {
-    id: 'user-1',
-    role: 'user',
-    content: [{ type: 'text', text: 'edit me please' }],
-    attachments: [],
-    createdAt,
-    metadata: { custom: {} }
-  } as ThreadMessage
-}
-
-function assistantMessage(): ThreadMessage {
-  return {
-    id: 'assistant-1',
-    role: 'assistant',
-    content: [{ type: 'text', text: 'done' }],
-    status: { type: 'complete', reason: 'stop' },
-    createdAt,
-    metadata: { unstable_state: null, unstable_annotations: [], unstable_data: [], steps: [], custom: {} }
-  } as ThreadMessage
-}
+stubThreadViewportSize()
 
 function Harness({ onEdit }: { onEdit: (message: AppendMessage) => Promise<void> }) {
   const repository = ExportedMessageRepository.fromArray([userMessage(), assistantMessage()])
diff --git a/apps/desktop/src/components/assistant-ui/thread/user-message-edit.test.tsx b/apps/desktop/src/components/assistant-ui/thread/user-message-edit.test.tsx
index 07e0bf1352..bd441fdb44 100644
--- a/apps/desktop/src/components/assistant-ui/thread/user-message-edit.test.tsx
+++ b/apps/desktop/src/components/assistant-ui/thread/user-message-edit.test.tsx
@@ -13,46 +13,16 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
 
 import { useIncrementalExternalStoreRuntime } from '@/lib/incremental-external-store-runtime'
 
+import { assistantMessage, stubThreadEnvironment, stubThreadViewportSize, userMessage } from '../test-utils'
+
 import { Thread } from '.'
-
-const createdAt = new Date('2026-05-01T00:00:00.000Z')
-
-class TestResizeObserver {
-  observe() {}
-  unobserve() {}
-  disconnect() {}
-}
-
-vi.stubGlobal('ResizeObserver', TestResizeObserver)
-vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) =>
-  window.setTimeout(() => callback(performance.now()), 0)
-)
-vi.stubGlobal('cancelAnimationFrame', (id: number) => window.clearTimeout(id))
-vi.stubGlobal('CSS', { escape: (str: string) => str })
-
-Element.prototype.scrollTo = function scrollTo() {}
+stubThreadEnvironment()
 
 afterEach(() => {
   cleanup()
 })
 
-function stubOffsetDimension(
-  prop: 'offsetHeight' | 'offsetWidth',
-  clientProp: 'clientHeight' | 'clientWidth',
-  fallback: number
-) {
-  const previous = Object.getOwnPropertyDescriptor(HTMLElement.prototype, prop)
-
-  Object.defineProperty(HTMLElement.prototype, prop, {
-    configurable: true,
-    get() {
-      return previous?.get?.call(this) || (this as HTMLElement)[clientProp] || fallback
-    }
-  })
-}
-
-stubOffsetDimension('offsetWidth', 'clientWidth', 800)
-stubOffsetDimension('offsetHeight', 'clientHeight', 600)
+stubThreadViewportSize()
 
 async function moveFocusOutside(editor: HTMLElement) {
   const outside = window.document.createElement('button')
@@ -67,34 +37,6 @@ async function moveFocusOutside(editor: HTMLElement) {
   outside.remove()
 }
 
-function userMessage(): ThreadMessage {
-  return {
-    id: 'user-1',
-    role: 'user',
-    content: [{ type: 'text', text: 'edit me please' }],
-    attachments: [],
-    createdAt,
-    metadata: { custom: {} }
-  } as ThreadMessage
-}
-
-function assistantMessage(): ThreadMessage {
-  return {
-    id: 'assistant-1',
-    role: 'assistant',
-    content: [{ type: 'text', text: 'done' }],
-    status: { type: 'complete', reason: 'stop' },
-    createdAt,
-    metadata: {
-      unstable_state: null,
-      unstable_annotations: [],
-      unstable_data: [],
-      steps: [],
-      custom: {}
-    }
-  } as ThreadMessage
-}
-
 // Mirrors chat/index.tsx: incremental runtime + messageRepository + onEdit.
 function IncrementalHarness({ onEdit }: { onEdit: (message: AppendMessage) => Promise<void> }) {
   const repository = ExportedMessageRepository.fromArray([userMessage(), assistantMessage()])
diff --git a/apps/desktop/src/components/assistant-ui/tool/tool-group.test.tsx b/apps/desktop/src/components/assistant-ui/tool/tool-group.test.tsx
index 7402bd9052..5d66c9d9d3 100644
--- a/apps/desktop/src/components/assistant-ui/tool/tool-group.test.tsx
+++ b/apps/desktop/src/components/assistant-ui/tool/tool-group.test.tsx
@@ -1,4 +1,4 @@
-import { AssistantRuntimeProvider, type ThreadMessage, useExternalStoreRuntime } from '@assistant-ui/react'
+import { type ThreadMessage } from '@assistant-ui/react'
 import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
@@ -8,6 +8,7 @@ import { $activeSessionId } from '@/store/session'
 import { clearDismissedToolRows } from '@/store/tool-dismiss'
 import { $toolDisclosureStates } from '@/store/tool-view'
 
+import { stubThreadEnvironment, stubThreadViewportSize, ThreadRuntime } from '../test-utils'
 import { Thread } from '../thread'
 import { formatTimelineRange } from '../thread/timestamp'
 
@@ -25,6 +26,7 @@ const createdAt = new Date('2026-06-03T00:00:00.000Z')
 
 const resizeObservers = new Set<TestResizeObserver>()
 
+// This suite drives resizes by hand, so it needs observers it can reach.
 class TestResizeObserver {
   private target: Element | null = null
 
@@ -43,38 +45,9 @@ class TestResizeObserver {
   }
 }
 
+stubThreadEnvironment()
+stubThreadViewportSize()
 vi.stubGlobal('ResizeObserver', TestResizeObserver)
-vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) =>
-  window.setTimeout(() => callback(performance.now()), 0)
-)
-vi.stubGlobal('cancelAnimationFrame', (id: number) => window.clearTimeout(id))
-
-Element.prototype.scrollTo = function scrollTo() {}
-
-Element.prototype.animate = function animate() {
-  return {
-    cancel: () => {},
-    finished: Promise.resolve()
-  } as unknown as Animation
-}
-
-function stubOffsetDimension(
-  prop: 'offsetHeight' | 'offsetWidth',
-  clientProp: 'clientHeight' | 'clientWidth',
-  fallback: number
-) {
-  const previous = Object.getOwnPropertyDescriptor(HTMLElement.prototype, prop)
-
-  Object.defineProperty(HTMLElement.prototype, prop, {
-    configurable: true,
-    get() {
-      return previous?.get?.call(this) || (this as HTMLElement)[clientProp] || fallback
-    }
-  })
-}
-
-stubOffsetDimension('offsetWidth', 'clientWidth', 800)
-stubOffsetDimension('offsetHeight', 'clientHeight', 600)
 
 // A running assistant message with two tools: a completed read_file plus a
 // pending terminal (no result), rendered as a flat two-row list.
@@ -406,19 +379,11 @@ function movedOnMessage(): ThreadMessage {
   } as unknown as ThreadMessage
 }
 
-function GroupHarness({ message }: { message: ThreadMessage }) {
-  const runtime = useExternalStoreRuntime<ThreadMessage>({
-    messages: [message],
-    isRunning: message.status?.type === 'running',
-    onNew: async () => {}
-  })
-
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      <Thread />
-    </AssistantRuntimeProvider>
-  )
-}
+const GroupHarness = ({ message }: { message: ThreadMessage }) => (
+  <ThreadRuntime messages={[message]}>
+    <Thread />
+  </ThreadRuntime>
+)
 
 beforeEach(() => {
   clearAllPrompts()
diff --git a/apps/desktop/src/components/chat/image-generation-placeholder.test.tsx b/apps/desktop/src/components/chat/image-generation-placeholder.test.tsx
index 312e89f0dc..6d439afb0d 100644
--- a/apps/desktop/src/components/chat/image-generation-placeholder.test.tsx
+++ b/apps/desktop/src/components/chat/image-generation-placeholder.test.tsx
@@ -2,11 +2,13 @@ import { act } from 'react'
 import { createRoot, type Root } from 'react-dom/client'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
+import { installWindowStateBridge, type WindowStateBridge } from '../../test/window-state'
+
 import { DiffusionCanvas } from './image-generation-placeholder'
 
 let root: Root | null = null
 let container: HTMLDivElement | null = null
-let windowStateCallback: ((payload: { isMinimized?: boolean; isVisible?: boolean }) => void) | null = null
+let windowState: WindowStateBridge
 
 function render() {
   container = document.createElement('div')
@@ -65,29 +67,11 @@ function installRaf() {
   }
 }
 
-function installWindowStateBridge() {
-  windowStateCallback = null
-  Object.defineProperty(window, 'hermesDesktop', {
-    configurable: true,
-    value: {
-      onWindowStateChanged: vi.fn((callback: typeof windowStateCallback) => {
-        windowStateCallback = callback
-
-        return () => {
-          if (windowStateCallback === callback) {
-            windowStateCallback = null
-          }
-        }
-      })
-    }
-  })
-}
-
 describe('DiffusionCanvas scheduling', () => {
   beforeEach(() => {
     ;(globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
     vi.spyOn(document, 'hasFocus').mockReturnValue(true)
-    installWindowStateBridge()
+    windowState = installWindowStateBridge()
     vi.spyOn(HTMLCanvasElement.prototype, 'getContext').mockReturnValue({
       setTransform: vi.fn()
     } as unknown as CanvasRenderingContext2D)
@@ -117,7 +101,7 @@ describe('DiffusionCanvas scheduling', () => {
     expect(raf.pending()).toBe(1)
 
     act(() => {
-      windowStateCallback?.({ isMinimized: true, isVisible: false })
+      windowState.emit({ isMinimized: true, isVisible: false })
     })
     expect(raf.pending()).toBe(0)
 
@@ -170,7 +154,7 @@ describe('DiffusionCanvas frame budget', () => {
   beforeEach(() => {
     ;(globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
     vi.spyOn(document, 'hasFocus').mockReturnValue(true)
-    installWindowStateBridge()
+    windowState = installWindowStateBridge()
   })
 
   afterEach(() => {
diff --git a/apps/desktop/src/components/language-switcher.test.tsx b/apps/desktop/src/components/language-switcher.test.tsx
index 3792012171..cdd3d60318 100644
--- a/apps/desktop/src/components/language-switcher.test.tsx
+++ b/apps/desktop/src/components/language-switcher.test.tsx
@@ -3,22 +3,12 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
 
 import type { HermesConfigRecord } from '@/hermes'
 import { type I18nConfigClient, I18nProvider } from '@/i18n'
+import { stubMenuDomApis, stubResizeObserver } from '@/test/jsdom'
 
 import { LanguageSwitcher } from './language-switcher'
 
-// cmdk (the searchable list) wires a ResizeObserver and scrolls the active
-// item into view — neither exists in jsdom. Stub them, matching the polyfill
-// idiom in tool-approval-group.test.tsx.
-class TestResizeObserver {
-  observe() {}
-  unobserve() {}
-  disconnect() {}
-}
-
-vi.stubGlobal('ResizeObserver', TestResizeObserver)
-
-Element.prototype.scrollIntoView = function scrollIntoView() {}
-
+stubResizeObserver()
+stubMenuDomApis()
 describe('LanguageSwitcher', () => {
   afterEach(() => {
     cleanup()
diff --git a/apps/desktop/src/components/onboarding/index.test.tsx b/apps/desktop/src/components/onboarding/index.test.tsx
index ad81560e09..ef099f93e0 100644
--- a/apps/desktop/src/components/onboarding/index.test.tsx
+++ b/apps/desktop/src/components/onboarding/index.test.tsx
@@ -2,21 +2,11 @@ import { cleanup, fireEvent, render, screen } from '@testing-library/react'
 import { afterEach, describe, expect, it } from 'vitest'
 
 import { $desktopOnboarding, type DesktopOnboardingState, type OnboardingContext } from '@/store/onboarding'
+import { makeOAuthProvider } from '@/test/oauth-provider'
 import type { OAuthProvider } from '@/types/hermes'
 
 import { Picker } from '.'
 
-function provider(id: string, name = id): OAuthProvider {
-  return {
-    cli_command: `hermes login ${id}`,
-    docs_url: `https://example.com/${id}`,
-    flow: 'pkce',
-    id,
-    name,
-    status: { logged_in: false }
-  }
-}
-
 function setProviders(providers: OAuthProvider[]) {
   $desktopOnboarding.set({
     configured: false,
@@ -57,7 +47,7 @@ afterEach(() => {
 
 describe('onboarding Picker', () => {
   it('features Nous Portal and hides other providers behind a disclosure', () => {
-    setProviders([provider('anthropic', 'Anthropic Claude'), provider('nous', 'Nous Portal')])
+    setProviders([makeOAuthProvider('anthropic', 'Anthropic Claude'), makeOAuthProvider('nous', 'Nous Portal')])
     render(<Picker ctx={ctx} />)
 
     expect(screen.getByText('Nous Portal')).toBeTruthy()
@@ -76,9 +66,9 @@ describe('onboarding Picker', () => {
 
   it('shows Fireworks first in the expanded list, ahead of other OAuth providers', () => {
     setProviders([
-      provider('openai-codex', 'OpenAI Codex / ChatGPT'),
-      provider('minimax-oauth', 'MiniMax'),
-      provider('nous', 'Nous Portal')
+      makeOAuthProvider('openai-codex', 'OpenAI Codex / ChatGPT'),
+      makeOAuthProvider('minimax-oauth', 'MiniMax'),
+      makeOAuthProvider('nous', 'Nous Portal')
     ])
     render(<Picker ctx={ctx} />)
     fireEvent.click(screen.getByRole('button', { name: 'Other providers' }))
@@ -96,7 +86,10 @@ describe('onboarding Picker', () => {
   })
 
   it('shows every provider directly when Nous Portal is absent', () => {
-    setProviders([provider('anthropic', 'Anthropic Claude'), provider('openai-codex', 'OpenAI Codex / ChatGPT')])
+    setProviders([
+      makeOAuthProvider('anthropic', 'Anthropic Claude'),
+      makeOAuthProvider('openai-codex', 'OpenAI Codex / ChatGPT')
+    ])
     render(<Picker ctx={ctx} />)
 
     expect(screen.getByText('Fireworks AI')).toBeTruthy()
@@ -107,7 +100,7 @@ describe('onboarding Picker', () => {
   })
 
   it('offers "choose later" on first run and persists the skip', () => {
-    setProviders([provider('nous', 'Nous Portal')])
+    setProviders([makeOAuthProvider('nous', 'Nous Portal')])
     render(<Picker ctx={ctx} />)
 
     const skip = screen.getByRole('button', { name: "I'll choose a provider later" })
@@ -119,7 +112,7 @@ describe('onboarding Picker', () => {
   })
 
   it('hides "choose later" in manual (add-provider) mode', () => {
-    setProviders([provider('nous', 'Nous Portal')])
+    setProviders([makeOAuthProvider('nous', 'Nous Portal')])
     $desktopOnboarding.set({ ...$desktopOnboarding.get(), manual: true })
     render(<Picker ctx={ctx} />)
 
diff --git a/apps/desktop/src/components/pane-shell/tree/renderer/floating-panes.test.tsx b/apps/desktop/src/components/pane-shell/tree/renderer/floating-panes.test.tsx
index 62b825659f..8306b14f71 100644
--- a/apps/desktop/src/components/pane-shell/tree/renderer/floating-panes.test.tsx
+++ b/apps/desktop/src/components/pane-shell/tree/renderer/floating-panes.test.tsx
@@ -6,28 +6,17 @@
  * floating-rect.test.ts).
  */
 
-import { act, type ReactNode } from 'react'
-import { createRoot, type Root } from 'react-dom/client'
+import { act } from 'react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 import { registry } from '@/contrib/registry'
+import { reactRoot } from '@/test/react-root'
 
 import { FloatingPanes } from './floating-panes'
 
-let root: null | Root = null
-let container: HTMLDivElement | null = null
+const mount = reactRoot()
 let disposers: (() => void)[] = []
 
-function render(ui: ReactNode) {
-  container = document.createElement('div')
-  document.body.append(container)
-  root = createRoot(container)
-
-  act(() => {
-    root!.render(ui)
-  })
-}
-
 const card = () => document.querySelector<HTMLElement>('[data-floating-pane="hud"]')
 
 const grab = () => card()!.querySelector('header')!
@@ -74,20 +63,14 @@ describe('FloatingPanes (live DOM)', () => {
   })
 
   afterEach(() => {
-    if (root) {
-      act(() => root!.unmount())
-    }
-
-    container?.remove()
-    root = null
-    container = null
+    mount.unmount()
     disposers.forEach(dispose => dispose())
     disposers = []
   })
 
   it('mounts a fixed card in the anchored corner with the pane body inside', () => {
     registerHud({ anchor: 'top-right', height: '132px', placement: 'floating', width: '224px' })
-    render(<FloatingPanes />)
+    mount.render(<FloatingPanes />)
 
     const el = card()!
 
@@ -102,14 +85,14 @@ describe('FloatingPanes (live DOM)', () => {
 
   it('renders nothing for a non-floating placement', () => {
     registerHud({ placement: 'right', width: '224px' })
-    render(<FloatingPanes />)
+    mount.render(<FloatingPanes />)
 
     expect(card()).toBeNull()
   })
 
   it('moves with a real pointer drag on the header', () => {
     registerHud({ anchor: 'top-left', height: '132px', placement: 'floating', width: '224px' })
-    render(<FloatingPanes />)
+    mount.render(<FloatingPanes />)
 
     expect(card()!.style.left).toBe('12px')
 
@@ -123,7 +106,7 @@ describe('FloatingPanes (live DOM)', () => {
 
   it('persists the dragged position across a remount', () => {
     registerHud({ anchor: 'top-left', height: '132px', placement: 'floating', width: '224px' })
-    render(<FloatingPanes />)
+    mount.render(<FloatingPanes />)
 
     pointer(grab(), 'pointerdown', 100, 100)
     pointer(grab(), 'pointermove', 300, 300)
@@ -131,16 +114,15 @@ describe('FloatingPanes (live DOM)', () => {
 
     const moved = card()!.style.left
 
-    act(() => root!.unmount())
-    container!.remove()
-    render(<FloatingPanes />)
+    mount.unmount()
+    mount.render(<FloatingPanes />)
 
     expect(card()!.style.left).toBe(moved)
   })
 
   it('rides the right edge when the window shrinks', () => {
     registerHud({ anchor: 'top-right', height: '132px', placement: 'floating', width: '224px' })
-    render(<FloatingPanes />)
+    mount.render(<FloatingPanes />)
 
     expect(card()!.style.left).toBe('1204px')
 
@@ -152,7 +134,7 @@ describe('FloatingPanes (live DOM)', () => {
 
   it('never lets a drag push the card under the titlebar', () => {
     registerHud({ anchor: 'top-left', height: '132px', placement: 'floating', width: '224px' })
-    render(<FloatingPanes />)
+    mount.render(<FloatingPanes />)
 
     pointer(grab(), 'pointerdown', 100, 100)
     pointer(grab(), 'pointermove', 100, -900)
@@ -163,7 +145,7 @@ describe('FloatingPanes (live DOM)', () => {
 
   it('collapses to the header and drops the body, and does not drag from the button', () => {
     registerHud({ anchor: 'top-left', height: '132px', placement: 'floating', width: '224px' })
-    render(<FloatingPanes />)
+    mount.render(<FloatingPanes />)
 
     const before = card()!.style.left
     const toggle = card()!.querySelector('button')!
@@ -201,7 +183,7 @@ describe('FloatingPanes (live DOM)', () => {
       })
     )
 
-    render(<FloatingPanes />)
+    mount.render(<FloatingPanes />)
 
     expect(document.querySelectorAll('[data-floating-pane]').length).toBe(2)
   })
diff --git a/apps/desktop/src/components/pane-shell/tree/renderer/narrow-overlays.test.tsx b/apps/desktop/src/components/pane-shell/tree/renderer/narrow-overlays.test.tsx
index 40f6e9fcfc..9f5e2baa8c 100644
--- a/apps/desktop/src/components/pane-shell/tree/renderer/narrow-overlays.test.tsx
+++ b/apps/desktop/src/components/pane-shell/tree/renderer/narrow-overlays.test.tsx
@@ -1,8 +1,9 @@
 import { act, cleanup, fireEvent, render } from '@testing-library/react'
-import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest'
 
 import { PANE_TOGGLE_REVEAL_EVENT } from '@/components/pane-shell'
 import { registry } from '@/contrib/registry'
+import { stubResizeObserver } from '@/test/jsdom'
 
 import { group, split } from '../model'
 import { $hiddenTreePanes, $layoutTree, $narrowViewport, declareDefaultTree } from '../store'
@@ -15,14 +16,8 @@ import { NarrowOverlays } from './narrow-overlays'
 // edge overlay must mirror the zone's tab strip so the docked pane stays
 // reachable — not just the zone's first pane.
 
-class TestResizeObserver {
-  observe() {}
-  unobserve() {}
-  disconnect() {}
-}
-
 beforeAll(() => {
-  vi.stubGlobal('ResizeObserver', TestResizeObserver)
+  stubResizeObserver()
 })
 
 const disposers: (() => void)[] = []
diff --git a/apps/desktop/src/components/pane-shell/tree/renderer/tool-panel-close.test.tsx b/apps/desktop/src/components/pane-shell/tree/renderer/tool-panel-close.test.tsx
index db5c2a70a9..49f8e4824e 100644
--- a/apps/desktop/src/components/pane-shell/tree/renderer/tool-panel-close.test.tsx
+++ b/apps/desktop/src/components/pane-shell/tree/renderer/tool-panel-close.test.tsx
@@ -2,6 +2,7 @@ import { cleanup, fireEvent, render, screen } from '@testing-library/react'
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'
 
 import { registry } from '@/contrib/registry'
+import { stubMenuDomApis, stubResizeObserver } from '@/test/jsdom'
 
 import { group, split } from '../model'
 import {
@@ -19,20 +20,11 @@ import { TreeGroup } from './tree-group'
 // doesn't close it". Renders the REAL zone renderer and opens the REAL
 // context menu.
 
-class TestResizeObserver {
-  observe() {}
-  unobserve() {}
-  disconnect() {}
-}
-
 beforeAll(() => {
-  vi.stubGlobal('ResizeObserver', TestResizeObserver)
+  stubResizeObserver()
+  stubMenuDomApis()
   // jsdom lacks CSS.escape, which tab-strip-scroll uses in a layout effect.
   vi.stubGlobal('CSS', { ...globalThis.CSS, escape: (value: string) => value })
-  Element.prototype.hasPointerCapture ??= () => false
-  Element.prototype.setPointerCapture ??= () => undefined
-  Element.prototype.releasePointerCapture ??= () => undefined
-  HTMLElement.prototype.scrollIntoView ??= () => undefined
 })
 
 const disposers: (() => void)[] = []
diff --git a/apps/desktop/src/components/pet/pet-sprite.test.tsx b/apps/desktop/src/components/pet/pet-sprite.test.tsx
index 2d0ac01760..719269bf18 100644
--- a/apps/desktop/src/components/pet/pet-sprite.test.tsx
+++ b/apps/desktop/src/components/pet/pet-sprite.test.tsx
@@ -1,5 +1,4 @@
-import { act, type ReactNode } from 'react'
-import { createRoot, type Root } from 'react-dom/client'
+import { act } from 'react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 vi.mock('@/store/pet', () => {
@@ -19,6 +18,10 @@ vi.mock('@/store/pet', () => {
   }
 })
 
+import { reactRoot } from '@/test/react-root'
+
+import { installWindowStateBridge, setDocumentHidden, type WindowStateBridge } from '../../test/window-state'
+
 import { PetSprite } from './pet-sprite'
 
 const INFO = {
@@ -32,56 +35,10 @@ const INFO = {
   stateRows: ['idle']
 }
 
-let root: Root | null = null
-let container: HTMLDivElement | null = null
-let windowStateCallback: ((payload: { isMinimized?: boolean; isVisible?: boolean }) => void) | null = null
+const mount = reactRoot()
+let windowState: WindowStateBridge
 let drawImage: ReturnType<typeof vi.fn>
 
-function render(ui: ReactNode) {
-  container = document.createElement('div')
-  document.body.append(container)
-  root = createRoot(container)
-
-  act(() => {
-    root!.render(ui)
-  })
-}
-
-function cleanup() {
-  if (root) {
-    act(() => {
-      root!.unmount()
-    })
-  }
-
-  container?.remove()
-  root = null
-  container = null
-}
-
-function setVisibility(hidden: boolean) {
-  Object.defineProperty(document, 'hidden', { configurable: true, value: hidden })
-  Object.defineProperty(document, 'visibilityState', { configurable: true, value: hidden ? 'hidden' : 'visible' })
-}
-
-function installWindowStateBridge() {
-  windowStateCallback = null
-  Object.defineProperty(window, 'hermesDesktop', {
-    configurable: true,
-    value: {
-      onWindowStateChanged: vi.fn((callback: typeof windowStateCallback) => {
-        windowStateCallback = callback
-
-        return () => {
-          if (windowStateCallback === callback) {
-            windowStateCallback = null
-          }
-        }
-      })
-    }
-  })
-}
-
 function installRaf() {
   let nextId = 1
   const frames = new Map<number, FrameRequestCallback>()
@@ -122,10 +79,10 @@ describe('PetSprite RAF scheduling', () => {
   beforeEach(() => {
     ;(globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
     vi.useFakeTimers()
-    setVisibility(false)
+    setDocumentHidden(false)
     Object.defineProperty(window, 'devicePixelRatio', { configurable: true, value: 1 })
     vi.spyOn(document, 'hasFocus').mockReturnValue(true)
-    installWindowStateBridge()
+    windowState = installWindowStateBridge()
     vi.stubGlobal(
       'Image',
       class extends EventTarget {
@@ -143,18 +100,18 @@ describe('PetSprite RAF scheduling', () => {
   })
 
   afterEach(() => {
-    cleanup()
+    mount.unmount()
     vi.useRealTimers()
     vi.unstubAllGlobals()
     vi.restoreAllMocks()
-    setVisibility(false)
+    setDocumentHidden(false)
     delete (window as unknown as { hermesDesktop?: unknown }).hermesDesktop
   })
 
   it('sleeps between visible sprite frames instead of chaining RAFs', () => {
     const raf = installRaf()
 
-    render(<PetSprite info={INFO} />)
+    mount.render(<PetSprite info={INFO} />)
 
     expect(raf.request).toHaveBeenCalledTimes(1)
 
@@ -177,9 +134,9 @@ describe('PetSprite RAF scheduling', () => {
     Object.defineProperty(window, 'devicePixelRatio', { configurable: true, value: 2 })
     const raf = installRaf()
 
-    render(<PetSprite info={INFO} />)
+    mount.render(<PetSprite info={INFO} />)
 
-    const canvas = container?.querySelector('canvas')
+    const canvas = mount.container?.querySelector('canvas')
 
     expect(canvas).not.toBeNull()
     expect(canvas?.width).toBe(32)
@@ -197,19 +154,19 @@ describe('PetSprite RAF scheduling', () => {
   it('cancels pending RAF work while the Electron window is paused and resumes when visible', () => {
     const raf = installRaf()
 
-    render(<PetSprite info={INFO} />)
+    mount.render(<PetSprite info={INFO} />)
 
     expect(raf.request).toHaveBeenCalledTimes(1)
 
     act(() => {
-      windowStateCallback?.({ isMinimized: true, isVisible: false })
+      windowState.emit({ isMinimized: true, isVisible: false })
     })
 
     expect(raf.cancel).toHaveBeenCalledTimes(1)
     expect(raf.pending()).toBe(0)
 
     act(() => {
-      windowStateCallback?.({ isMinimized: false, isVisible: true })
+      windowState.emit({ isMinimized: false, isVisible: true })
     })
 
     expect(raf.request).toHaveBeenCalledTimes(2)
@@ -218,7 +175,7 @@ describe('PetSprite RAF scheduling', () => {
   it('suspends while unfocused, resumes on focus, and leaves no work after unmount', () => {
     const raf = installRaf()
 
-    render(<PetSprite info={INFO} />)
+    mount.render(<PetSprite info={INFO} />)
 
     act(() => window.dispatchEvent(new Event('blur')))
     expect(raf.pending()).toBe(0)
@@ -229,7 +186,7 @@ describe('PetSprite RAF scheduling', () => {
     act(() => raf.runNext(0))
     expect(vi.getTimerCount()).toBe(1)
 
-    cleanup()
+    mount.unmount()
     expect(raf.pending()).toBe(0)
     expect(vi.getTimerCount()).toBe(0)
 
@@ -243,7 +200,7 @@ describe('PetSprite RAF scheduling', () => {
   it('keeps the intentionally non-activating pop-out overlay animated while unfocused', () => {
     const raf = installRaf()
 
-    render(<PetSprite info={INFO} pauseWhenUnfocused={false} />)
+    mount.render(<PetSprite info={INFO} pauseWhenUnfocused={false} />)
 
     act(() => window.dispatchEvent(new Event('blur')))
     expect(raf.pending()).toBe(1)
@@ -261,7 +218,7 @@ describe('PetSprite RAF scheduling', () => {
 
     vi.spyOn(HTMLCanvasElement.prototype, 'getContext').mockReturnValue(ctxMock)
 
-    render(<PetSprite info={INFO} />)
+    mount.render(<PetSprite info={INFO} />)
     act(() => raf.runNext(0))
 
     // Petdex sheets are illustration frames, not pixel art — nearest-neighbour
diff --git a/apps/desktop/src/components/pet/use-pet-roam.test.tsx b/apps/desktop/src/components/pet/use-pet-roam.test.tsx
index c906a8a297..c306800ecf 100644
--- a/apps/desktop/src/components/pet/use-pet-roam.test.tsx
+++ b/apps/desktop/src/components/pet/use-pet-roam.test.tsx
@@ -1,5 +1,4 @@
-import { act, type ReactNode, type RefObject, useRef } from 'react'
-import { createRoot, type Root } from 'react-dom/client'
+import { act, type RefObject, useRef } from 'react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 vi.mock('@/store/pet', () => ({
@@ -7,56 +6,14 @@ vi.mock('@/store/pet', () => ({
   $petRoamDir: { set: () => undefined }
 }))
 
+import { reactRoot } from '@/test/react-root'
+
+import { installWindowStateBridge, setDocumentHidden, type WindowStateBridge } from '../../test/window-state'
+
 import { usePetRoam } from './use-pet-roam'
 
-let root: Root | null = null
-let container: HTMLDivElement | null = null
-let windowStateCallback: ((payload: { isMinimized?: boolean; isVisible?: boolean }) => void) | null = null
-
-function render(ui: ReactNode) {
-  container = document.createElement('div')
-  document.body.append(container)
-  root = createRoot(container)
-
-  act(() => {
-    root!.render(ui)
-  })
-}
-
-function cleanup() {
-  if (root) {
-    act(() => {
-      root!.unmount()
-    })
-  }
-
-  container?.remove()
-  root = null
-  container = null
-}
-
-function setVisibility(hidden: boolean) {
-  Object.defineProperty(document, 'hidden', { configurable: true, value: hidden })
-  Object.defineProperty(document, 'visibilityState', { configurable: true, value: hidden ? 'hidden' : 'visible' })
-}
-
-function installWindowStateBridge() {
-  windowStateCallback = null
-  Object.defineProperty(window, 'hermesDesktop', {
-    configurable: true,
-    value: {
-      onWindowStateChanged: vi.fn((callback: typeof windowStateCallback) => {
-        windowStateCallback = callback
-
-        return () => {
-          if (windowStateCallback === callback) {
-            windowStateCallback = null
-          }
-        }
-      })
-    }
-  })
-}
+const mount = reactRoot()
+let windowState: WindowStateBridge
 
 function installRaf() {
   const request = vi.fn((_callback: FrameRequestCallback) => 1)
@@ -89,9 +46,9 @@ describe('usePetRoam RAF scheduling', () => {
   beforeEach(() => {
     ;(globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
     vi.useFakeTimers()
-    setVisibility(false)
+    setDocumentHidden(false)
     vi.spyOn(document, 'hasFocus').mockReturnValue(true)
-    installWindowStateBridge()
+    windowState = installWindowStateBridge()
     vi.spyOn(Math, 'random').mockReturnValue(0)
     vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockReturnValue({
       bottom: 164,
@@ -107,17 +64,17 @@ describe('usePetRoam RAF scheduling', () => {
   })
 
   afterEach(() => {
-    cleanup()
+    mount.unmount()
     vi.useRealTimers()
     vi.restoreAllMocks()
-    setVisibility(false)
+    setDocumentHidden(false)
     delete (window as unknown as { hermesDesktop?: unknown }).hermesDesktop
   })
 
   it('uses a pause timer, not RAF, while dwelling at idle', () => {
     const raf = installRaf()
 
-    render(<RoamHarness />)
+    mount.render(<RoamHarness />)
 
     expect(raf.request).not.toHaveBeenCalled()
     expect(vi.getTimerCount()).toBe(1)
@@ -126,16 +83,16 @@ describe('usePetRoam RAF scheduling', () => {
   it('clears the pause wakeup while the Electron window is paused and restarts it when visible', () => {
     const raf = installRaf()
 
-    render(<RoamHarness />)
+    mount.render(<RoamHarness />)
     expect(vi.getTimerCount()).toBe(1)
 
-    windowStateCallback?.({ isMinimized: true, isVisible: false })
+    windowState.emit({ isMinimized: true, isVisible: false })
 
     expect(raf.cancel).not.toHaveBeenCalled()
     expect(raf.request).not.toHaveBeenCalled()
     expect(vi.getTimerCount()).toBe(0)
 
-    windowStateCallback?.({ isMinimized: false, isVisible: true })
+    windowState.emit({ isMinimized: false, isVisible: true })
 
     expect(raf.request).not.toHaveBeenCalled()
     expect(vi.getTimerCount()).toBe(1)
@@ -144,7 +101,7 @@ describe('usePetRoam RAF scheduling', () => {
   it('suspends idle movement while unfocused and cleans up its wake timer on unmount', () => {
     const raf = installRaf()
 
-    render(<RoamHarness />)
+    mount.render(<RoamHarness />)
     expect(vi.getTimerCount()).toBe(1)
 
     act(() => window.dispatchEvent(new Event('blur')))
@@ -153,7 +110,7 @@ describe('usePetRoam RAF scheduling', () => {
     act(() => window.dispatchEvent(new Event('focus')))
     expect(vi.getTimerCount()).toBe(1)
 
-    cleanup()
+    mount.unmount()
     expect(vi.getTimerCount()).toBe(0)
 
     act(() => {
diff --git a/apps/desktop/src/components/ui/status-pulse.test.tsx b/apps/desktop/src/components/ui/status-pulse.test.tsx
index 8f49622928..24f32ccc05 100644
--- a/apps/desktop/src/components/ui/status-pulse.test.tsx
+++ b/apps/desktop/src/components/ui/status-pulse.test.tsx
@@ -1,6 +1,8 @@
 import { act, cleanup, render } from '@testing-library/react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
+import { installWindowStateBridge, type WindowStateBridge } from '../../test/window-state'
+
 import { StatusPulse } from './status-pulse'
 
 interface PlayedAnimation {
@@ -9,12 +11,7 @@ interface PlayedAnimation {
   options: KeyframeAnimationOptions
 }
 
-interface WindowStatePayload {
-  isMinimized?: boolean
-  isVisible?: boolean
-}
-
-let windowStateCallback: ((payload: WindowStatePayload) => void) | undefined
+let windowState: WindowStateBridge
 
 function installMatchMedia(matches: boolean) {
   vi.stubGlobal(
@@ -29,20 +26,6 @@ function installMatchMedia(matches: boolean) {
   )
 }
 
-function installWindowStateBridge() {
-  const off = vi.fn()
-
-  window.hermesDesktop = {
-    onWindowStateChanged: vi.fn(callback => {
-      windowStateCallback = callback
-
-      return off
-    })
-  } as unknown as typeof window.hermesDesktop
-
-  return off
-}
-
 describe('StatusPulse', () => {
   const played: PlayedAnimation[] = []
 
@@ -50,7 +33,7 @@ describe('StatusPulse', () => {
     vi.useFakeTimers()
     vi.spyOn(window.document, 'hasFocus').mockReturnValue(true)
     installMatchMedia(false)
-    installWindowStateBridge()
+    windowState = installWindowStateBridge()
     Object.defineProperty(HTMLElement.prototype, 'animate', {
       configurable: true,
       value: (keyframes: Keyframe[], options: KeyframeAnimationOptions) => {
@@ -71,7 +54,6 @@ describe('StatusPulse', () => {
   afterEach(() => {
     cleanup()
     played.length = 0
-    windowStateCallback = undefined
     Reflect.deleteProperty(HTMLElement.prototype, 'animate')
     delete (window as unknown as { hermesDesktop?: unknown }).hermesDesktop
     vi.useRealTimers()
@@ -98,12 +80,12 @@ describe('StatusPulse', () => {
   })
 
   it('cancels scheduled work while minimized and restarts once visible', () => {
-    const offWindowState = installWindowStateBridge()
+    windowState = installWindowStateBridge()
     const mounted = render(<StatusPulse kind="opacity" />)
 
     expect(played).toHaveLength(1)
 
-    act(() => windowStateCallback?.({ isMinimized: true, isVisible: false }))
+    act(() => windowState.emit({ isMinimized: true, isVisible: false }))
 
     expect(played[0]?.cancel).toHaveBeenCalledTimes(1)
     expect(vi.getTimerCount()).toBe(0)
@@ -111,12 +93,12 @@ describe('StatusPulse', () => {
     act(() => vi.advanceTimersByTime(5_000))
     expect(played).toHaveLength(1)
 
-    act(() => windowStateCallback?.({ isMinimized: false, isVisible: true }))
+    act(() => windowState.emit({ isMinimized: false, isVisible: true }))
     expect(played).toHaveLength(2)
 
     mounted.unmount()
     expect(played[1]?.cancel).toHaveBeenCalledTimes(1)
-    expect(offWindowState).toHaveBeenCalledTimes(1)
+    expect(windowState.off).toHaveBeenCalledTimes(1)
     expect(vi.getTimerCount()).toBe(0)
   })
 
diff --git a/apps/desktop/src/lib/budgeted-loop.test.ts b/apps/desktop/src/lib/budgeted-loop.test.ts
index 3741518c65..edcc027e87 100644
--- a/apps/desktop/src/lib/budgeted-loop.test.ts
+++ b/apps/desktop/src/lib/budgeted-loop.test.ts
@@ -1,8 +1,10 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
+import { installWindowStateBridge, type WindowStateBridge } from '../test/window-state'
+
 import { createBudgetedLoop } from './budgeted-loop'
 
-let windowStateCallback: ((payload: { isMinimized?: boolean; isVisible?: boolean }) => void) | null = null
+let windowState: WindowStateBridge
 
 function installRaf() {
   let nextId = 1
@@ -38,28 +40,10 @@ function installRaf() {
   }
 }
 
-function installWindowStateBridge() {
-  windowStateCallback = null
-  Object.defineProperty(window, 'hermesDesktop', {
-    configurable: true,
-    value: {
-      onWindowStateChanged: vi.fn((callback: typeof windowStateCallback) => {
-        windowStateCallback = callback
-
-        return () => {
-          if (windowStateCallback === callback) {
-            windowStateCallback = null
-          }
-        }
-      })
-    }
-  })
-}
-
 describe('createBudgetedLoop', () => {
   beforeEach(() => {
     vi.spyOn(document, 'hasFocus').mockReturnValue(true)
-    installWindowStateBridge()
+    windowState = installWindowStateBridge()
   })
 
   afterEach(() => {
@@ -100,10 +84,10 @@ describe('createBudgetedLoop', () => {
     window.dispatchEvent(new Event('focus'))
     expect(raf.pending()).toBe(1)
 
-    windowStateCallback?.({ isMinimized: true, isVisible: false })
+    windowState.emit({ isMinimized: true, isVisible: false })
     expect(raf.pending()).toBe(0)
 
-    windowStateCallback?.({ isMinimized: false, isVisible: true })
+    windowState.emit({ isMinimized: false, isVisible: true })
     expect(raf.pending()).toBe(1)
 
     loop.dispose()
diff --git a/apps/desktop/src/lib/session-branch-tree.test.ts b/apps/desktop/src/lib/session-branch-tree.test.ts
index acdc0a3abf..8de1803012 100644
--- a/apps/desktop/src/lib/session-branch-tree.test.ts
+++ b/apps/desktop/src/lib/session-branch-tree.test.ts
@@ -2,25 +2,12 @@ import { describe, expect, it } from 'vitest'
 
 import type { SessionInfo } from '@/types/hermes'
 
+import { makeSessionInfo } from '../test/session-info'
+
 import { flattenSessionsWithBranches } from './session-branch-tree'
 
 const session = (id: string, overrides: Partial<SessionInfo> = {}): SessionInfo =>
-  ({
-    ended_at: null,
-    id,
-    input_tokens: 0,
-    is_active: false,
-    last_active: 0,
-    message_count: 1,
-    model: null,
-    output_tokens: 0,
-    preview: null,
-    source: 'cli',
-    started_at: 0,
-    title: id,
-    tool_call_count: 0,
-    ...overrides
-  }) as SessionInfo
+  makeSessionInfo({ id, message_count: 1, source: 'cli', title: id, ...overrides })
 
 describe('flattenSessionsWithBranches', () => {
   it('nests branch rows under their parent with tree stems', () => {
diff --git a/apps/desktop/src/lib/session-date-groups.test.ts b/apps/desktop/src/lib/session-date-groups.test.ts
index 1bcaf587ec..b485d053a1 100644
--- a/apps/desktop/src/lib/session-date-groups.test.ts
+++ b/apps/desktop/src/lib/session-date-groups.test.ts
@@ -2,26 +2,13 @@ import { describe, expect, it } from 'vitest'
 
 import type { SessionInfo } from '@/types/hermes'
 
+import { makeSessionInfo } from '../test/session-info'
+
 import type { SidebarSessionEntry } from './session-branch-tree'
 import { groupEntriesByRecency, toSessionRows } from './session-date-groups'
 
 const session = (id: string, overrides: Partial<SessionInfo> = {}): SessionInfo =>
-  ({
-    ended_at: null,
-    id,
-    input_tokens: 0,
-    is_active: false,
-    last_active: 0,
-    message_count: 1,
-    model: null,
-    output_tokens: 0,
-    preview: null,
-    source: 'cli',
-    started_at: 0,
-    title: id,
-    tool_call_count: 0,
-    ...overrides
-  }) as SessionInfo
+  makeSessionInfo({ id, message_count: 1, source: 'cli', title: id, ...overrides })
 
 const entry = (s: SessionInfo, branchStem?: string): SidebarSessionEntry =>
   branchStem ? { branchStem, session: s } : { session: s }
diff --git a/apps/desktop/src/store/approval-mode.test.ts b/apps/desktop/src/store/approval-mode.test.ts
index 3f5112df81..3ec7a6daed 100644
--- a/apps/desktop/src/store/approval-mode.test.ts
+++ b/apps/desktop/src/store/approval-mode.test.ts
@@ -1,5 +1,7 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
+import { deferred } from '../test/deferred'
+
 import {
   $approvalModes,
   approvalModeForProfile,
@@ -8,18 +10,6 @@ import {
   syncApprovalModeForProfile
 } from './approval-mode'
 
-function deferred<T>() {
-  let resolve!: (value: T) => void
-  let reject!: (error: unknown) => void
-
-  const promise = new Promise<T>((res, rej) => {
-    resolve = res
-    reject = rej
-  })
-
-  return { promise, reject, resolve }
-}
-
 describe('profile-scoped approval mode cache', () => {
   beforeEach(() => $approvalModes.set({}))
 
diff --git a/apps/desktop/src/store/cron-model-impact.test.ts b/apps/desktop/src/store/cron-model-impact.test.ts
index 04f5e54d56..f854808809 100644
--- a/apps/desktop/src/store/cron-model-impact.test.ts
+++ b/apps/desktop/src/store/cron-model-impact.test.ts
@@ -18,6 +18,8 @@ import {
   setMainModelAssignment
 } from '@/store/cron-model-impact'
 
+import { deferred } from '../test/deferred'
+
 function response(impact: ModelAssignmentResponse['cron_model_impact']): ModelAssignmentResponse {
   return {
     ok: true,
@@ -38,16 +40,6 @@ function positive(name = 'Morning summary'): ModelAssignmentResponse['cron_model
   }
 }
 
-function deferred<T>() {
-  let resolve!: (value: T) => void
-
-  const promise = new Promise<T>(res => {
-    resolve = res
-  })
-
-  return { promise, resolve }
-}
-
 beforeEach(() => {
   setModelAssignment.mockReset()
   getApiRequestProfile.mockReset()
diff --git a/apps/desktop/src/store/onboarding.test.ts b/apps/desktop/src/store/onboarding.test.ts
index f969659920..d5392634d5 100644
--- a/apps/desktop/src/store/onboarding.test.ts
+++ b/apps/desktop/src/store/onboarding.test.ts
@@ -1,6 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 import * as notifications from '@/store/notifications'
+import { makeOAuthProvider } from '@/test/oauth-provider'
 import type { OAuthProvider } from '@/types/hermes'
 
 import {
@@ -13,17 +14,6 @@ import {
   submitOnboardingCode
 } from './onboarding'
 
-function provider(id: string, name = id): OAuthProvider {
-  return {
-    cli_command: `hermes login ${id}`,
-    docs_url: `https://example.com/${id}`,
-    flow: 'pkce',
-    id,
-    name,
-    status: { logged_in: false }
-  }
-}
-
 function baseState(overrides: Partial<DesktopOnboardingState> = {}): DesktopOnboardingState {
   return {
     configured: false,
@@ -103,14 +93,14 @@ describe('refreshOnboarding', () => {
   it('refreshes OAuth providers again when onboarding was explicitly requested', async () => {
     const api = vi.fn(async ({ path }: { path: string }) => {
       if (path === '/api/providers/oauth') {
-        return { providers: [provider('fresh')] }
+        return { providers: [makeOAuthProvider('fresh')] }
       }
 
       throw new Error(`unexpected api path: ${path}`)
     })
 
     installApiMock(api)
-    $desktopOnboarding.set(baseState({ providers: [provider('cached')] }))
+    $desktopOnboarding.set(baseState({ providers: [makeOAuthProvider('cached')] }))
     requestDesktopOnboarding('Need provider setup')
 
     const ready = await refreshOnboarding(onboardingContext(emptyOpenRouterGateway()))
@@ -125,14 +115,14 @@ describe('refreshOnboarding', () => {
   it('keeps cached providers when onboarding was not re-requested', async () => {
     const api = vi.fn(async ({ path }: { path: string }) => {
       if (path === '/api/providers/oauth') {
-        return { providers: [provider('fresh')] }
+        return { providers: [makeOAuthProvider('fresh')] }
       }
 
       throw new Error(`unexpected api path: ${path}`)
     })
 
     installApiMock(api)
-    $desktopOnboarding.set(baseState({ providers: [provider('cached')] }))
+    $desktopOnboarding.set(baseState({ providers: [makeOAuthProvider('cached')] }))
 
     const ready = await refreshOnboarding(onboardingContext(emptyOpenRouterGateway()))
 
@@ -144,7 +134,7 @@ describe('refreshOnboarding', () => {
   it('does not downgrade configured=true on fallback-only readiness failures', async () => {
     const api = vi.fn(async ({ path }: { path: string }) => {
       if (path === '/api/providers/oauth') {
-        return { providers: [provider('fresh')] }
+        return { providers: [makeOAuthProvider('fresh')] }
       }
 
       throw new Error(`unexpected api path: ${path}`)
@@ -156,7 +146,7 @@ describe('refreshOnboarding', () => {
     $desktopOnboarding.set(
       baseState({
         configured: true,
-        providers: [provider('cached')],
+        providers: [makeOAuthProvider('cached')],
         reason: null,
         requested: false
       })
@@ -179,7 +169,7 @@ describe('refreshOnboarding', () => {
     $desktopOnboarding.set(
       baseState({
         configured: true,
-        providers: [provider('cached')],
+        providers: [makeOAuthProvider('cached')],
         reason: null,
         requested: false
       })
@@ -202,7 +192,7 @@ describe('refreshOnboarding', () => {
     $desktopOnboarding.set(
       baseState({
         configured: true,
-        providers: [provider('cached')],
+        providers: [makeOAuthProvider('cached')],
         reason: null,
         requested: false
       })
@@ -236,7 +226,7 @@ describe('refreshOnboarding', () => {
   it('does not preserve configured when onboarding was explicitly requested', async () => {
     const api = vi.fn(async ({ path }: { path: string }) => {
       if (path === '/api/providers/oauth') {
-        return { providers: [provider('fresh')] }
+        return { providers: [makeOAuthProvider('fresh')] }
       }
 
       throw new Error(`unexpected api path: ${path}`)
@@ -246,7 +236,7 @@ describe('refreshOnboarding', () => {
     $desktopOnboarding.set(
       baseState({
         configured: true,
-        providers: [provider('cached')],
+        providers: [makeOAuthProvider('cached')],
         reason: null,
         requested: true
       })
@@ -263,7 +253,7 @@ describe('refreshOnboarding', () => {
   it('still surfaces onboarding when fallback failure happens before configured state', async () => {
     const api = vi.fn(async ({ path }: { path: string }) => {
       if (path === '/api/providers/oauth') {
-        return { providers: [provider('fresh')] }
+        return { providers: [makeOAuthProvider('fresh')] }
       }
 
       throw new Error(`unexpected api path: ${path}`)
@@ -305,7 +295,7 @@ describe('refreshOnboarding', () => {
 
     await vi.waitFor(() => expect(api).toHaveBeenCalledTimes(1))
 
-    resolveProviders({ providers: [provider('shared')] })
+    resolveProviders({ providers: [makeOAuthProvider('shared')] })
     await Promise.all([first, second])
 
     expect($desktopOnboarding.get().providers?.map(p => p.id)).toEqual(['shared'])
@@ -380,7 +370,7 @@ describe('OAuth onboarding', () => {
       baseState({
         flow: {
           status: 'awaiting_user',
-          provider: provider('nous', 'Nous Portal'),
+          provider: makeOAuthProvider('nous', 'Nous Portal'),
           start: {
             auth_url: 'https://portal.example/auth',
             expires_in: 600,
@@ -458,7 +448,7 @@ describe('OAuth onboarding', () => {
       baseState({
         flow: {
           status: 'awaiting_user',
-          provider: provider('nous', 'Nous Portal'),
+          provider: makeOAuthProvider('nous', 'Nous Portal'),
           start: {
             auth_url: 'https://portal.example/auth',
             expires_in: 600,
diff --git a/apps/desktop/src/store/profile-agent-activation.test.ts b/apps/desktop/src/store/profile-agent-activation.test.ts
index da089502e8..fb822d69d1 100644
--- a/apps/desktop/src/store/profile-agent-activation.test.ts
+++ b/apps/desktop/src/store/profile-agent-activation.test.ts
@@ -3,6 +3,8 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 import type { HermesConnection } from '@/global'
 
+import { deferred } from '../test/deferred'
+
 // Registry-agent activation (ensureGatewayAgent — the SDK ensureAgent door).
 // Two regressions pinned here:
 //  1. Activating an ALREADY-OPEN registry agent must still resync
@@ -47,16 +49,6 @@ const getConnection = vi.fn<(profile?: string | null) => Promise<HermesConnectio
 const getConnectionFor =
   vi.fn<(payload: { connectionId?: null | string; profile?: null | string }) => Promise<HermesConnection>>()
 
-function deferred(): { promise: Promise<void>; resolve: () => void } {
-  let resolve!: () => void
-
-  const promise = new Promise<void>(r => {
-    resolve = r
-  })
-
-  return { promise, resolve }
-}
-
 beforeEach(() => {
   getConnection.mockReset()
   getConnectionFor.mockReset()
diff --git a/apps/desktop/src/store/session-color.test.ts b/apps/desktop/src/store/session-color.test.ts
index 30bb96c652..964d0a1876 100644
--- a/apps/desktop/src/store/session-color.test.ts
+++ b/apps/desktop/src/store/session-color.test.ts
@@ -1,34 +1,13 @@
 import { afterEach, describe, expect, it } from 'vitest'
 
-import type { ProjectInfo, SessionInfo } from '@/types/hermes'
+import type { ProjectInfo } from '@/types/hermes'
+
+import { makeCwdSession } from '../test/session-info'
 
 import { $projects } from './projects'
 import { $sessions } from './session'
 import { $sessionColorById, $sessionColorOverrides, sessionColorFor, setSessionColorOverride } from './session-color'
 
-let nextId = 0
-
-function makeSession(cwd: null | string, overrides: Partial<SessionInfo> = {}): SessionInfo {
-  return {
-    archived: false,
-    cwd,
-    ended_at: null,
-    id: `s${nextId++}`,
-    input_tokens: 0,
-    is_active: false,
-    last_active: 1_000,
-    message_count: 1,
-    model: 'claude',
-    output_tokens: 0,
-    preview: null,
-    source: 'cli',
-    started_at: 1_000,
-    title: null,
-    tool_call_count: 0,
-    ...overrides
-  }
-}
-
 function makeProject(id: string, folders: string[], color: null | string): ProjectInfo {
   return {
     archived: false,
@@ -53,8 +32,8 @@ afterEach(() => {
 
 describe('$sessionColorById', () => {
   it('maps each session under a colored project to that color, keyed by live id', () => {
-    const a = makeSession('/www/app/src', { git_repo_root: '/www/app' })
-    const b = makeSession('/other/place')
+    const a = makeCwdSession('/www/app/src', { git_repo_root: '/www/app' })
+    const b = makeCwdSession('/other/place')
 
     $projects.set([makeProject('p_app', ['/www/app'], '#4a9eff')])
     $sessions.set([a, b])
@@ -67,7 +46,7 @@ describe('$sessionColorById', () => {
   })
 
   it('omits a session whose project has no color', () => {
-    const a = makeSession('/www/app', { git_repo_root: '/www/app' })
+    const a = makeCwdSession('/www/app', { git_repo_root: '/www/app' })
 
     $projects.set([makeProject('p_app', ['/www/app'], null)])
     $sessions.set([a])
@@ -76,7 +55,7 @@ describe('$sessionColorById', () => {
   })
 
   it('recomputes when the projects list changes (color applied later)', () => {
-    const a = makeSession('/www/app', { git_repo_root: '/www/app' })
+    const a = makeCwdSession('/www/app', { git_repo_root: '/www/app' })
 
     $sessions.set([a])
     $projects.set([makeProject('p_app', ['/www/app'], null)])
@@ -89,7 +68,7 @@ describe('$sessionColorById', () => {
 
 describe('$sessionColorOverrides', () => {
   it('an override wins over the inherited project color', () => {
-    const a = makeSession('/www/app', { git_repo_root: '/www/app' })
+    const a = makeCwdSession('/www/app', { git_repo_root: '/www/app' })
 
     $projects.set([makeProject('p_app', ['/www/app'], '#4a9eff')])
     $sessions.set([a])
@@ -99,7 +78,7 @@ describe('$sessionColorOverrides', () => {
   })
 
   it('clearing an override falls back to the project color', () => {
-    const a = makeSession('/www/app', { git_repo_root: '/www/app' })
+    const a = makeCwdSession('/www/app', { git_repo_root: '/www/app' })
 
     $projects.set([makeProject('p_app', ['/www/app'], '#4a9eff')])
     $sessions.set([a])
@@ -114,8 +93,8 @@ describe('$sessionColorOverrides', () => {
   it('keys on the durable lineage id so a color survives compression', () => {
     // The live id rotates on auto-compression; the override is stored against the
     // lineage root, so the continuation tip still resolves to the same color.
-    const root = makeSession('/x', { id: 'root' })
-    const tip = makeSession('/x', { id: 'tip', _lineage_root_id: 'root' })
+    const root = makeCwdSession('/x', { id: 'root' })
+    const tip = makeCwdSession('/x', { id: 'tip', _lineage_root_id: 'root' })
 
     setSessionColorOverride('root', '#abcdef')
 
@@ -126,7 +105,7 @@ describe('$sessionColorOverrides', () => {
 
 describe('sessionColorFor', () => {
   it('reads a single session through the same shared map', () => {
-    const a = makeSession('/www/app', { git_repo_root: '/www/app' })
+    const a = makeCwdSession('/www/app', { git_repo_root: '/www/app' })
 
     $projects.set([makeProject('p_app', ['/www/app'], '#5865f2')])
     $sessions.set([a])
diff --git a/apps/desktop/src/store/session-unread.test.ts b/apps/desktop/src/store/session-unread.test.ts
index f1d0224c9b..1af657415c 100644
--- a/apps/desktop/src/store/session-unread.test.ts
+++ b/apps/desktop/src/store/session-unread.test.ts
@@ -2,6 +2,8 @@ import { beforeEach, describe, expect, it } from 'vitest'
 
 import type { SessionInfo } from '@/types/hermes'
 
+import { makeSessionInfo } from '../test/session-info'
+
 import { $activeGatewayProfile } from './profile'
 import {
   $cronSessions,
@@ -20,24 +22,7 @@ import {
   markSessionUnreadFinished
 } from './session-unread'
 
-const session = (over: Partial<SessionInfo>): SessionInfo => ({
-  archived: false,
-  cwd: null,
-  ended_at: null,
-  id: 'live',
-  input_tokens: 0,
-  is_active: false,
-  last_active: 0,
-  message_count: 0,
-  model: null,
-  output_tokens: 0,
-  preview: null,
-  source: null,
-  started_at: 0,
-  title: null,
-  tool_call_count: 0,
-  ...over
-})
+const session = (over: Partial<SessionInfo>): SessionInfo => makeSessionInfo({ id: 'live', ...over })
 
 function resetAll() {
   clearAllSessionStates()
diff --git a/apps/desktop/src/store/session.test.ts b/apps/desktop/src/store/session.test.ts
index ab7961dc03..3ebb0c5694 100644
--- a/apps/desktop/src/store/session.test.ts
+++ b/apps/desktop/src/store/session.test.ts
@@ -15,6 +15,8 @@ vi.mock('@/hermes', () => ({
   setSessionUnreadRemote: (id: string, unread: boolean, profile?: null | string) => setUnreadRemote(id, unread, profile)
 }))
 
+import { makeSessionInfo } from '../test/session-info'
+
 import {
   $activeSessionId,
   $connection,
@@ -49,24 +51,7 @@ import {
   publishSessionState
 } from './session-states'
 
-const session = (over: Partial<SessionInfo>): SessionInfo => ({
-  archived: false,
-  cwd: null,
-  ended_at: null,
-  id: 'live',
-  input_tokens: 0,
-  is_active: false,
-  last_active: 0,
-  message_count: 0,
-  model: null,
-  output_tokens: 0,
-  preview: null,
-  source: null,
-  started_at: 0,
-  title: null,
-  tool_call_count: 0,
-  ...over
-})
+const session = (over: Partial<SessionInfo>): SessionInfo => makeSessionInfo({ id: 'live', ...over })
 
 describe('computed $attentionSessionIds', () => {
   beforeEach(() => {
diff --git a/apps/desktop/src/test/deferred.ts b/apps/desktop/src/test/deferred.ts
new file mode 100644
index 0000000000..b5c8913dcf
--- /dev/null
+++ b/apps/desktop/src/test/deferred.ts
@@ -0,0 +1,16 @@
+/** A promise plus the handle that settles it.
+ *
+ *  For tests that need a call to stay in flight — asserting the pending UI,
+ *  proving a second call is coalesced or ignored, ordering two resolutions —
+ *  and then release it on their own schedule. */
+export function deferred<T = void>() {
+  let resolve!: (value: PromiseLike<T> | T) => void
+  let reject!: (reason?: unknown) => void
+
+  const promise = new Promise<T>((done, fail) => {
+    resolve = done
+    reject = fail
+  })
+
+  return { promise, reject, resolve }
+}
diff --git a/apps/desktop/src/test/jsdom.ts b/apps/desktop/src/test/jsdom.ts
new file mode 100644
index 0000000000..e9034e8c33
--- /dev/null
+++ b/apps/desktop/src/test/jsdom.ts
@@ -0,0 +1,26 @@
+// jsdom implements no layout and no animation, so component libraries that
+// call those APIs unconditionally throw on mount. These install inert
+// stand-ins: enough for the component to render, never enough to assert on. A
+// test that needs one of them to actually report should install its own.
+
+import { vi } from 'vitest'
+
+class InertResizeObserver {
+  disconnect() {}
+  observe() {}
+  unobserve() {}
+}
+
+/** A ResizeObserver that accepts observers and never calls them back. */
+export function stubResizeObserver() {
+  vi.stubGlobal('ResizeObserver', InertResizeObserver)
+}
+
+/** The pointer-capture and scroll calls Radix and cmdk make while opening a
+ *  popover, menu, or combobox — and again on the item they focus. */
+export function stubMenuDomApis() {
+  Element.prototype.hasPointerCapture ??= () => false
+  Element.prototype.setPointerCapture ??= () => undefined
+  Element.prototype.releasePointerCapture ??= () => undefined
+  Element.prototype.scrollIntoView ??= () => undefined
+}
diff --git a/apps/desktop/src/test/oauth-provider.ts b/apps/desktop/src/test/oauth-provider.ts
new file mode 100644
index 0000000000..8e477ac5ff
--- /dev/null
+++ b/apps/desktop/src/test/oauth-provider.ts
@@ -0,0 +1,14 @@
+import type { OAuthProvider } from '@/types/hermes'
+
+/** A logged-out PKCE provider. Onboarding branches on `flow` and
+ *  `status.logged_in`; the rest is filler the UI only echoes. */
+export function makeOAuthProvider(id: string, name = id): OAuthProvider {
+  return {
+    cli_command: `hermes login ${id}`,
+    docs_url: `https://example.com/${id}`,
+    flow: 'pkce',
+    id,
+    name,
+    status: { logged_in: false }
+  }
+}
diff --git a/apps/desktop/src/test/react-root.ts b/apps/desktop/src/test/react-root.ts
new file mode 100644
index 0000000000..ba54305dea
--- /dev/null
+++ b/apps/desktop/src/test/react-root.ts
@@ -0,0 +1,44 @@
+import { act, type ReactNode } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+
+/** A React root in a container attached to the document, for the handful of
+ *  suites that cannot use Testing Library's `render`.
+ *
+ *  They need the component mounted in the real document — a canvas that must
+ *  paint, an element measured by its parent, a portal that reads
+ *  `document.body` — and they need to unmount inside `act` mid-test to assert
+ *  on teardown. Cleanup is idempotent so `afterEach` can call it after a test
+ *  already did. */
+export function reactRoot() {
+  let root: Root | null = null
+  let container: HTMLDivElement | null = null
+
+  return {
+    get container() {
+      return container
+    },
+    /** The root itself, for a re-render that has to share an `act` with
+     *  something else — a mutation-observer callback, a timer flush. */
+    get root() {
+      return root
+    },
+    render(ui: ReactNode) {
+      container = document.createElement('div')
+      document.body.append(container)
+      root = createRoot(container)
+
+      act(() => {
+        root!.render(ui)
+      })
+    },
+    unmount() {
+      if (root) {
+        act(() => root!.unmount())
+      }
+
+      container?.remove()
+      root = null
+      container = null
+    }
+  }
+}
diff --git a/apps/desktop/src/test/session-info.ts b/apps/desktop/src/test/session-info.ts
new file mode 100644
index 0000000000..9c39a4eb0f
--- /dev/null
+++ b/apps/desktop/src/test/session-info.ts
@@ -0,0 +1,46 @@
+import type { SessionInfo } from '@/types/hermes'
+
+/** A `SessionInfo` with every field at its zero value.
+ *
+ *  `SessionInfo` mirrors a backend row and grows a field whenever the API does.
+ *  Spelling the whole shape out per test file meant each new field broke a
+ *  handful of unrelated suites; here it breaks one line. Tests override only
+ *  what they assert on. */
+export function makeSessionInfo(overrides: Partial<SessionInfo> = {}): SessionInfo {
+  return {
+    archived: false,
+    cwd: null,
+    ended_at: null,
+    id: 'session',
+    input_tokens: 0,
+    is_active: false,
+    last_active: 0,
+    message_count: 0,
+    model: null,
+    output_tokens: 0,
+    preview: null,
+    source: null,
+    started_at: 0,
+    title: null,
+    tool_call_count: 0,
+    ...overrides
+  }
+}
+
+let nextId = 0
+
+/** A real-looking CLI session rooted at `cwd`, with a fresh id. What the
+ *  folder-grouping and per-project colour tests bucket; they care about the
+ *  path and that the session is otherwise unremarkable. */
+export function makeCwdSession(cwd: null | string, overrides: Partial<SessionInfo> = {}): SessionInfo {
+  return makeSessionInfo({
+    cwd,
+    id: `s${nextId++}`,
+    last_active: 1_000,
+    message_count: 1,
+    model: 'claude',
+    source: 'cli',
+    started_at: 1_000,
+    ...overrides
+  })
+}
diff --git a/apps/desktop/src/test/window-state.ts b/apps/desktop/src/test/window-state.ts
new file mode 100644
index 0000000000..512da0f5ff
--- /dev/null
+++ b/apps/desktop/src/test/window-state.ts
@@ -0,0 +1,47 @@
+// Stand-ins for the two window-visibility signals the renderer reacts to:
+// Electron's `hermesDesktop.onWindowStateChanged` bridge and the DOM's own
+// `document.hidden`. Both are read-only under jsdom, and anything that pauses
+// work while the window is hidden — the pet, the terminal pane, budgeted loops,
+// pulse animations — needs to drive them.
+
+import { vi } from 'vitest'
+
+export interface WindowStatePayload {
+  isMinimized?: boolean
+  isVisible?: boolean
+}
+
+export interface WindowStateBridge {
+  /** Push a state change to whoever subscribed through the bridge. */
+  emit: (payload: WindowStatePayload) => void
+  /** The unsubscribe handed back to the subscriber, for teardown assertions. */
+  off: ReturnType<typeof vi.fn>
+}
+
+/** Install a fake `window.hermesDesktop` window-state channel. */
+export function installWindowStateBridge(): WindowStateBridge {
+  let callback: ((payload: WindowStatePayload) => void) | null = null
+
+  const off = vi.fn(() => {
+    callback = null
+  })
+
+  Object.defineProperty(window, 'hermesDesktop', {
+    configurable: true,
+    value: {
+      onWindowStateChanged: vi.fn((next: (payload: WindowStatePayload) => void) => {
+        callback = next
+
+        return off
+      })
+    }
+  })
+
+  return { emit: payload => callback?.(payload), off }
+}
+
+/** Drive `document.hidden` / `document.visibilityState` together. */
+export function setDocumentHidden(hidden: boolean) {
+  Object.defineProperty(document, 'hidden', { configurable: true, value: hidden })
+  Object.defineProperty(document, 'visibilityState', { configurable: true, value: hidden ? 'hidden' : 'visible' })
+}

From 70743bc4cbb9ebd690b9dd76bcb5d5f2344366c0 Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 19 Aug 2026 10:53:26 -0500
Subject: [PATCH 19/48] chore: kick CI


From 8e9342b016a02af68a6bb5f3c6de90192a0d540f Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 19 Aug 2026 10:53:30 -0500
Subject: [PATCH 20/48] chore: kick CI


From 04956c1a874500b2697639deab0fd35276e1eef8 Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 19 Aug 2026 11:01:54 -0500
Subject: [PATCH 21/48] fix(desktop): isolate composer submit to one visible
 surface

Review "Ask Hermes to open PR" was a window-level event that every mounted
composer claimed with `target === 'main'`, so one click shipped every open
session and project with dirty files. Bind the request to the visible
surface captured at click time.

Co-authored-by: unsupportedpastels <theoldwizard123@pm.me>
Co-authored-by: youtiaowei <youtiaowei@users.noreply.github.com>
---
 apps/desktop/src/app/chat/composer/focus.ts   |  69 ++++-
 .../hooks/use-composer-submit.test.tsx        | 248 ++++++++++++++++--
 .../composer/hooks/use-composer-submit.ts     |  26 +-
 apps/desktop/src/app/chat/composer/scope.tsx  |  12 +
 apps/desktop/src/app/chat/index.tsx           |  18 +-
 5 files changed, 325 insertions(+), 48 deletions(-)

diff --git a/apps/desktop/src/app/chat/composer/focus.ts b/apps/desktop/src/app/chat/composer/focus.ts
index 4ceefb5d3a..6e450c10f8 100644
--- a/apps/desktop/src/app/chat/composer/focus.ts
+++ b/apps/desktop/src/app/chat/composer/focus.ts
@@ -67,6 +67,8 @@ const cssEscape = (value: string): string => {
 }
 
 interface SubmitDetail {
+  /** Unique mounted composer surface captured at click time. */
+  surfaceId: string
   target: ComposerTarget
   text: string
   /** `hidden` types the persisted user row so no bubble renders — the
@@ -155,6 +157,38 @@ const dispatch = <T>(name: string, detail: T) => {
   window.setTimeout(() => window.dispatchEvent(new CustomEvent<T>(name, { detail })), 0)
 }
 
+/** Submit is the one bus mutation that must preserve the chat visible at click
+ * time. Deferring it lets a parent click handler/tab reveal switch the active
+ * keep-alive pane before subscribers run, so the task is dropped or claimed by
+ * another composer. Other bus events intentionally defer for focus restoration.
+ */
+const dispatchNow = <T>(name: string, detail: T) => {
+  if (typeof window !== 'undefined') {
+    window.dispatchEvent(new CustomEvent<T>(name, { detail }))
+  }
+}
+
+/** Unique identity for the visible composer surface addressed by a submit. */
+const getVisibleComposerSurfaceId = (target: ComposerTarget): string | null => {
+  if (typeof document === 'undefined') {
+    return null
+  }
+
+  const surface = queryVisible<HTMLElement>(`[data-composer-target="${cssEscape(target)}"]`)
+
+  return surface?.dataset.composerSurfaceId || null
+}
+
+const composerSurfaceIsVisible = (target: ComposerTarget, surfaceId: string): boolean => {
+  if (typeof document === 'undefined') {
+    return false
+  }
+
+  return queryAllVisible<HTMLElement>(`[data-composer-target="${cssEscape(target)}"]`).some(
+    surface => surface.dataset.composerSurfaceId === surfaceId
+  )
+}
+
 const subscribe = <T>(name: string, handler: (detail: T) => void) => {
   if (typeof window === 'undefined') {
     return () => undefined
@@ -264,17 +298,36 @@ export const onComposerInsertRefsRequest = (handler: (detail: InsertRefsDetail)
  * the agent a task without the user round-tripping through the input. */
 export const requestComposerSubmit = (
   text: string,
-  { target = 'active', displayKind }: { target?: ComposerTarget | 'active'; displayKind?: 'hidden' } = {}
-) => {
+  {
+    displayKind,
+    surfaceId: requestedSurfaceId,
+    target = 'active'
+  }: { displayKind?: 'hidden'; surfaceId?: null | string; target?: ComposerTarget | 'active' } = {}
+): boolean => {
   const trimmed = text.trim()
 
-  if (trimmed) {
-    dispatch<SubmitDetail>(SUBMIT_EVENT, {
-      target: resolve(target),
-      text: trimmed,
-      ...(displayKind ? { displayKind } : {})
-    })
+  if (!trimmed) {
+    return false
   }
+
+  const resolvedTarget = resolve(target)
+  const surfaceId =
+    requestedSurfaceId === undefined ? getVisibleComposerSurfaceId(resolvedTarget) : requestedSurfaceId
+
+  // Fail closed: without an exact visible surface identity, broadcasting a
+  // submit could make more than one keep-alive/new-chat composer claim it.
+  if (!surfaceId || (requestedSurfaceId !== undefined && !composerSurfaceIsVisible(resolvedTarget, surfaceId))) {
+    return false
+  }
+
+  dispatchNow<SubmitDetail>(SUBMIT_EVENT, {
+    surfaceId,
+    target: resolvedTarget,
+    text: trimmed,
+    ...(displayKind ? { displayKind } : {})
+  })
+
+  return true
 }
 
 export const onComposerSubmitRequest = (handler: (detail: SubmitDetail) => void) =>
diff --git a/apps/desktop/src/app/chat/composer/hooks/use-composer-submit.test.tsx b/apps/desktop/src/app/chat/composer/hooks/use-composer-submit.test.tsx
index e2eb17419d..c278356d05 100644
--- a/apps/desktop/src/app/chat/composer/hooks/use-composer-submit.test.tsx
+++ b/apps/desktop/src/app/chat/composer/hooks/use-composer-submit.test.tsx
@@ -1,6 +1,8 @@
 import { act, cleanup, renderHook, waitFor } from '@testing-library/react'
+import { type Dispatch, type PropsWithChildren, type SetStateAction, useLayoutEffect, useState } from 'react'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 
+import { PaneVisibleContext } from '@/components/pane-shell/pane-visibility'
 import { $clarifyRequests } from '@/store/clarify'
 import type { ComposerAttachment } from '@/store/composer'
 import { $gateway } from '@/store/gateway'
@@ -12,23 +14,41 @@ import {
   setSudoRequest
 } from '@/store/prompts'
 
+import { type ComposerTarget, requestComposerSubmit } from '../focus'
+import { ComposerScopeProvider, ComposerSurfaceProvider, MAIN_COMPOSER_SCOPE } from '../scope'
+
 import { useComposerSubmit } from './use-composer-submit'
 
 interface SubmitHarnessOptions {
   attachments?: ComposerAttachment[]
   busy?: boolean
   compacting?: boolean
+  inputDisabled?: boolean
+  scopeTarget?: ComposerTarget
+  sessionKey?: string | null
+  submitOnHide?: boolean
+  surfaceId?: string | null
   text?: string
+  visible?: boolean
 }
 
+let surfaceSequence = 0
+
 function renderSubmitHook({
   attachments = [],
   busy = false,
   compacting = false,
-  text = ''
+  inputDisabled = false,
+  scopeTarget = 'main',
+  sessionKey = 'stored-session',
+  submitOnHide = false,
+  surfaceId,
+  text = '',
+  visible = true
 }: SubmitHarnessOptions = {}) {
+  const resolvedSurfaceId = surfaceId === undefined ? `test-surface-${++surfaceSequence}` : surfaceId
   const draftRef = { current: text }
-  const editor = document.createElement('div')
+  const editor = window.document.createElement('div')
   editor.dataset.slot = 'composer-rich-input'
   editor.textContent = text
   const editorRef = { current: editor }
@@ -36,43 +56,213 @@ function renderSubmitHook({
   const onSteer = vi.fn(async () => true)
   const onSubmit = vi.fn(async () => true)
   const queueCurrentDraft = vi.fn(() => true)
+  let updatePaneVisible: Dispatch<SetStateAction<boolean>> | undefined
 
   const clearDraft = vi.fn(() => {
     draftRef.current = ''
     editorRef.current!.textContent = ''
   })
 
-  const hook = renderHook(() =>
-    useComposerSubmit({
-      activeQueueSessionKey: 'stored-session',
-      activeQueueSessionKeyRef: { current: 'stored-session' },
-      attachments,
-      busy,
-      compacting,
-      clearDraft,
-      disabled: false,
-      draftRef,
-      drainNextQueued: vi.fn(async () => false),
-      editorRef,
-      exitQueuedEdit: vi.fn(() => false),
-      focusInput: vi.fn(),
-      inputDisabled: false,
-      loadIntoComposer: vi.fn(),
-      onCancel,
-      onSteer,
-      onSubmit,
-      queueCurrentDraft,
-      queueEdit: null,
-      queuedPrompts: [],
-      sessionId: 'runtime-session',
-      setComposerText: vi.fn(),
-      stashAt: vi.fn()
-    })
+  const Wrapper = ({ children }: PropsWithChildren) => {
+    const [paneVisible, setPaneVisible] = useState(visible)
+    updatePaneVisible = setPaneVisible
+
+    useLayoutEffect(() => {
+      if (submitOnHide && !paneVisible) {
+        requestComposerSubmit('ship while hiding', { target: scopeTarget })
+      }
+    }, [paneVisible])
+
+    return (
+      <ComposerScopeProvider value={{ ...MAIN_COMPOSER_SCOPE, target: scopeTarget }}>
+        <ComposerSurfaceProvider value={resolvedSurfaceId}>
+          <PaneVisibleContext.Provider value={paneVisible}>
+            <div
+              data-composer-surface-id={resolvedSurfaceId ?? undefined}
+              data-composer-target={scopeTarget}
+              data-pane-hidden={paneVisible ? undefined : ''}
+            >
+              {children}
+            </div>
+          </PaneVisibleContext.Provider>
+        </ComposerSurfaceProvider>
+      </ComposerScopeProvider>
+    )
+  }
+
+  const hook = renderHook(
+    () =>
+      useComposerSubmit({
+        activeQueueSessionKey: sessionKey,
+        activeQueueSessionKeyRef: { current: sessionKey },
+        attachments,
+        busy,
+        compacting,
+        clearDraft,
+        disabled: false,
+        draftRef,
+        drainNextQueued: vi.fn(async () => false),
+        editorRef,
+        exitQueuedEdit: vi.fn(() => false),
+        focusInput: vi.fn(),
+        inputDisabled,
+        loadIntoComposer: vi.fn(),
+        onCancel,
+        onSteer,
+        onSubmit,
+        queueCurrentDraft,
+        queueEdit: null,
+        queuedPrompts: [],
+        sessionId: 'runtime-session',
+        setComposerText: vi.fn(),
+        stashAt: vi.fn()
+      }),
+    { wrapper: Wrapper }
   )
 
-  return { clearDraft, hook, onCancel, onSteer, onSubmit, queueCurrentDraft }
+  return {
+    clearDraft,
+    hook,
+    onCancel,
+    onSteer,
+    onSubmit,
+    queueCurrentDraft,
+    composerSurfaceId: resolvedSurfaceId,
+    setPaneVisible(nextVisible: boolean) {
+      if (!updatePaneVisible) {
+        throw new Error('Pane visibility setter was not initialized')
+      }
+
+      updatePaneVisible(nextVisible)
+    }
+  }
 }
 
+describe('useComposerSubmit external request routing', () => {
+  afterEach(() => {
+    cleanup()
+    vi.restoreAllMocks()
+  })
+
+  it('does not fan out a main ship across keep-alives or other projects', async () => {
+    const visibleMain = renderSubmitHook({ sessionKey: 'session-a' })
+    const hiddenMain = renderSubmitHook({ sessionKey: 'session-b', visible: false })
+    const visibleTile = renderSubmitHook({ scopeTarget: 'tile:project-b', sessionKey: 'tile-session' })
+    const hiddenTile = renderSubmitHook({
+      scopeTarget: 'tile:project-c',
+      sessionKey: 'other-tile',
+      visible: false
+    })
+
+    expect(requestComposerSubmit('ship this branch', { target: 'main' })).toBe(true)
+
+    await waitFor(() =>
+      expect(visibleMain.onSubmit).toHaveBeenCalledWith('ship this branch', {
+        composerScope: 'session-a'
+      })
+    )
+    expect(visibleMain.onSubmit).toHaveBeenCalledTimes(1)
+    expect(hiddenMain.onSubmit).not.toHaveBeenCalled()
+    expect(visibleTile.onSubmit).not.toHaveBeenCalled()
+    expect(hiddenTile.onSubmit).not.toHaveBeenCalled()
+  })
+
+  it('routes a tile-targeted submit to that tile only', async () => {
+    const main = renderSubmitHook({ sessionKey: 'main-session' })
+    const tile = renderSubmitHook({ scopeTarget: 'tile:project-b', sessionKey: 'tile-session' })
+
+    expect(requestComposerSubmit('ship project B', { target: 'tile:project-b' })).toBe(true)
+
+    await waitFor(() =>
+      expect(tile.onSubmit).toHaveBeenCalledWith('ship project B', {
+        composerScope: 'tile-session'
+      })
+    )
+    expect(main.onSubmit).not.toHaveBeenCalled()
+  })
+
+  it('uses the captured surface id when two visible composers share a target', async () => {
+    const first = renderSubmitHook({ sessionKey: 'session-first' })
+    const second = renderSubmitHook({ sessionKey: 'session-second' })
+
+    requestComposerSubmit('ship exactly one session', { surfaceId: second.composerSurfaceId, target: 'main' })
+
+    await waitFor(() =>
+      expect(second.onSubmit).toHaveBeenCalledWith('ship exactly one session', {
+        composerScope: 'session-second'
+      })
+    )
+    expect(first.onSubmit).not.toHaveBeenCalled()
+  })
+
+  it('submits to the session visible at click time even when the same click switches tabs', async () => {
+    const hiddenA = renderSubmitHook({ sessionKey: 'session-a', visible: false })
+    const visibleB = renderSubmitHook({ sessionKey: 'session-b' })
+
+    act(() => {
+      requestComposerSubmit('ship session B', { target: 'main' })
+      visibleB.setPaneVisible(false)
+      hiddenA.setPaneVisible(true)
+    })
+
+    await waitFor(() =>
+      expect(visibleB.onSubmit).toHaveBeenCalledWith('ship session B', {
+        composerScope: 'session-b'
+      })
+    )
+    expect(hiddenA.onSubmit).not.toHaveBeenCalled()
+  })
+
+  it('does not fan out when visible composers do not have queue session keys yet', async () => {
+    const firstNewSession = renderSubmitHook({ sessionKey: null })
+    const secondNewSession = renderSubmitHook({ sessionKey: null })
+
+    act(() => {
+      requestComposerSubmit('ship the visible new session', { target: 'main' })
+    })
+
+    await waitFor(() => expect(firstNewSession.onSubmit).toHaveBeenCalledTimes(1))
+    expect(secondNewSession.onSubmit).not.toHaveBeenCalled()
+  })
+
+  it('fails closed when the visible composer has no surface identity', () => {
+    const unidentified = renderSubmitHook({ surfaceId: null })
+
+    expect(requestComposerSubmit('do not broadcast this', { target: 'main' })).toBe(false)
+    expect(unidentified.onSubmit).not.toHaveBeenCalled()
+  })
+
+  it('fails closed when a pinned origin surface is no longer visible', () => {
+    const hidden = renderSubmitHook({ sessionKey: 'hidden-origin', visible: false })
+    const visible = renderSubmitHook({ sessionKey: 'other-visible' })
+
+    expect(
+      requestComposerSubmit('do not send to a stale origin', {
+        surfaceId: hidden.composerSurfaceId,
+        target: 'main'
+      })
+    ).toBe(false)
+    expect(hidden.onSubmit).not.toHaveBeenCalled()
+    expect(visible.onSubmit).not.toHaveBeenCalled()
+  })
+
+  it('does not submit through a composer whose pane is hidden during the request', () => {
+    const main = renderSubmitHook({ submitOnHide: true })
+
+    act(() => main.setPaneVisible(false))
+
+    expect(main.onSubmit).not.toHaveBeenCalled()
+  })
+
+  it('does not submit through a disabled composer', () => {
+    const disabled = renderSubmitHook({ inputDisabled: true })
+
+    requestComposerSubmit('do not send this', { target: 'main' })
+
+    expect(disabled.onSubmit).not.toHaveBeenCalled()
+  })
+})
+
 describe('useComposerSubmit busy-turn routing', () => {
   afterEach(() => {
     cleanup()
diff --git a/apps/desktop/src/app/chat/composer/hooks/use-composer-submit.ts b/apps/desktop/src/app/chat/composer/hooks/use-composer-submit.ts
index 7cfa31a13e..9435881b43 100644
--- a/apps/desktop/src/app/chat/composer/hooks/use-composer-submit.ts
+++ b/apps/desktop/src/app/chat/composer/hooks/use-composer-submit.ts
@@ -1,5 +1,6 @@
-import { type RefObject, useEffect, useRef } from 'react'
+import { type RefObject, useLayoutEffect, useRef } from 'react'
 
+import { usePaneVisible } from '@/components/pane-shell/pane-visibility'
 import { SLASH_COMMAND_RE } from '@/lib/chat-runtime'
 import { triggerHaptic } from '@/lib/haptics'
 import { hasClarifyRequest, skipClarifyRequest } from '@/store/clarify'
@@ -13,7 +14,7 @@ import { cloneAttachments, type QueueEditState } from '../composer-utils'
 import { onComposerSubmitRequest } from '../focus'
 import { pathifyRefs } from '../path-refs'
 import { composerPlainText } from '../rich-editor'
-import { useComposerScope } from '../scope'
+import { useComposerScope, useComposerSurfaceId } from '../scope'
 import type { ChatBarProps } from '../types'
 
 interface UseComposerSubmitArgs {
@@ -76,7 +77,9 @@ export function useComposerSubmit({
   setComposerText,
   stashAt
 }: UseComposerSubmitArgs) {
+  const paneVisible = usePaneVisible()
   const scope = useComposerScope()
+  const surfaceId = useComposerSurfaceId()
 
   // Shared send primitive: fire onSubmit, and if the gateway rejects (accepted
   // === false) or throws, re-load + re-stash the draft so the words survive.
@@ -103,19 +106,26 @@ export function useComposerSubmit({
   }
 
   // External "submit this prompt" requests (e.g. the review pane's agent-ship
-  // button) route through the same send path. A ref keeps the listener stable
-  // while always calling the latest dispatchSubmit closure.
+  // button) route through the same send path. Match both the composer target
+  // and the exact visible surface captured at click time — every tile stays
+  // mounted, and a session can be rendered in more than one pane.
   const dispatchSubmitRef = useRef(dispatchSubmit)
   dispatchSubmitRef.current = dispatchSubmit
 
-  useEffect(
+  useLayoutEffect(
     () =>
-      onComposerSubmitRequest(({ target, text, displayKind }) => {
-        if (target === 'main' && !inputDisabled) {
+      onComposerSubmitRequest(({ surfaceId: requestedSurfaceId, target, text, displayKind }) => {
+        if (
+          target === scope.target &&
+          surfaceId !== null &&
+          requestedSurfaceId === surfaceId &&
+          paneVisible &&
+          !inputDisabled
+        ) {
           dispatchSubmitRef.current(text, undefined, displayKind)
         }
       }),
-    [inputDisabled]
+    [inputDisabled, paneVisible, scope.target, surfaceId]
   )
 
   const submitDraft = () => {
diff --git a/apps/desktop/src/app/chat/composer/scope.tsx b/apps/desktop/src/app/chat/composer/scope.tsx
index e7e7aff880..a14b53ca42 100644
--- a/apps/desktop/src/app/chat/composer/scope.tsx
+++ b/apps/desktop/src/app/chat/composer/scope.tsx
@@ -43,3 +43,15 @@ const ComposerScopeContext = createContext<ComposerScope>(MAIN_COMPOSER_SCOPE)
 export const ComposerScopeProvider = ComposerScopeContext.Provider
 
 export const useComposerScope = (): ComposerScope => useContext(ComposerScopeContext)
+
+/**
+ * Unique identity for one mounted ChatView/composer pair. Session ids cannot
+ * fill this role: a fresh chat has no id yet, and the same stored session can
+ * be rendered in more than one layout pane. External submit requests pin this
+ * surface id at click time so exactly one composer can claim the task.
+ */
+const ComposerSurfaceContext = createContext<string | null>(null)
+
+export const ComposerSurfaceProvider = ComposerSurfaceContext.Provider
+
+export const useComposerSurfaceId = (): string | null => useContext(ComposerSurfaceContext)
diff --git a/apps/desktop/src/app/chat/index.tsx b/apps/desktop/src/app/chat/index.tsx
index 13ed225186..f3e72d7378 100644
--- a/apps/desktop/src/app/chat/index.tsx
+++ b/apps/desktop/src/app/chat/index.tsx
@@ -3,7 +3,7 @@ import { useStore } from '@nanostores/react'
 import { useQuery } from '@tanstack/react-query'
 import type { ReadableAtom } from 'nanostores'
 import type * as React from 'react'
-import { memo, Suspense, useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { memo, Suspense, useCallback, useEffect, useId, useMemo, useRef, useState } from 'react'
 import { useLocation } from 'react-router'
 
 import type { SubmitTextOptions } from '@/app/session/hooks/use-prompt-actions/utils'
@@ -56,7 +56,7 @@ import { ChatSwapOverlay } from './chat-swap-overlay'
 import { ChatBar, ChatBarFallback } from './composer'
 import { requestComposerInsert } from './composer/focus'
 import { droppedFileInlineRefs } from './composer/inline-refs'
-import { useComposerScope } from './composer/scope'
+import { ComposerSurfaceProvider, useComposerScope, useComposerSurfaceId } from './composer/scope'
 import type { ChatBarState } from './composer/types'
 import { type DroppedFile, partitionDroppedFiles } from './hooks/use-composer-actions'
 import { type DragKind, useFileDropZone } from './hooks/use-file-drop-zone'
@@ -320,7 +320,17 @@ function ChatRuntimeBoundary({
 // Memoized: the tile caller (session-tile.tsx) and the contrib surface re-render
 // on idle ticks unrelated to the chat; with stable callback props (hoisted to
 // useCallback at the call sites) memo() lets the whole chat shell skip those.
-export const ChatView = memo(function ChatView({
+export const ChatView = memo(function ChatView(props: ChatViewProps) {
+  const composerSurfaceId = useId()
+
+  return (
+    <ComposerSurfaceProvider value={composerSurfaceId}>
+      <ChatViewContent {...props} />
+    </ComposerSurfaceProvider>
+  )
+})
+
+const ChatViewContent = memo(function ChatViewContent({
   className,
   gateway,
   modelMenuContent,
@@ -355,6 +365,7 @@ export const ChatView = memo(function ChatView({
   // atoms) or a tile's session slice — same component either way.
   const view = useSessionView()
   const composerScope = useComposerScope()
+  const composerSurfaceId = useComposerSurfaceId()
   const isPrimary = view.kind === 'primary'
   const activeSessionId = useStore(view.$runtimeId)
   const storedId = useStore(view.$storedId)
@@ -558,6 +569,7 @@ export const ChatView = memo(function ChatView({
         className
       )}
       data-chat-surface=""
+      data-composer-surface-id={composerSurfaceId}
       data-composer-target={composerScope.target}
       data-session-anchor={sessionAnchor}
     >

From 830108c8d958ea7651a37a61aff7620c2aa98d51 Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 19 Aug 2026 11:01:58 -0500
Subject: [PATCH 22/48] fix(desktop): send review agent-ship to the composer
 that opened it

The ship button always targeted `main`, so a tile Review still prompted
the workspace session. Remember the originating composer target with the
pane's cwd, capture the live surface at click, and toast if that chat
isn't on screen instead of dropping the click.

Co-authored-by: unsupportedpastels <theoldwizard123@pm.me>
Co-authored-by: youtiaowei <youtiaowei@users.noreply.github.com>
---
 apps/desktop/src/app/chat/composer/index.tsx  |  2 +-
 apps/desktop/src/app/contrib/controller.tsx   | 11 ++++-
 .../src/app/right-sidebar/review/ship-bar.tsx |  8 +++-
 .../thread/changed-files-card.tsx             |  6 ++-
 apps/desktop/src/i18n/ar.ts                   |  1 +
 apps/desktop/src/i18n/en.ts                   |  1 +
 apps/desktop/src/i18n/ja.ts                   |  1 +
 apps/desktop/src/i18n/types.ts                |  1 +
 apps/desktop/src/i18n/zh-hant.ts              |  1 +
 apps/desktop/src/i18n/zh.ts                   |  1 +
 apps/desktop/src/store/review.test.ts         | 44 +++++++++++++++++++
 apps/desktop/src/store/review.ts              | 42 +++++++++++++-----
 12 files changed, 101 insertions(+), 18 deletions(-)

diff --git a/apps/desktop/src/app/chat/composer/index.tsx b/apps/desktop/src/app/chat/composer/index.tsx
index c61f81f1fc..763f62f13e 100644
--- a/apps/desktop/src/app/chat/composer/index.tsx
+++ b/apps/desktop/src/app/chat/composer/index.tsx
@@ -1278,7 +1278,7 @@ export function ChatBar({
                   // A tile's rail reviews ITS worktree: pin the pane's scope to
                   // this surface's cwd. Main keeps the classic follow-the-
                   // active-session scope (null).
-                  onOpen={() => toggleReview(scope.target === 'main' ? null : (cwd ?? null))}
+                  onOpen={() => toggleReview(scope.target === 'main' ? null : (cwd ?? null), scope.target)}
                   onOpenWorktree={openInWorktree}
                   onSwitchBranch={handleSwitchBranch}
                   repoPath={cwd}
diff --git a/apps/desktop/src/app/contrib/controller.tsx b/apps/desktop/src/app/contrib/controller.tsx
index 5c65fd3f19..f5d400a204 100644
--- a/apps/desktop/src/app/contrib/controller.tsx
+++ b/apps/desktop/src/app/contrib/controller.tsx
@@ -59,7 +59,14 @@ import {
   SIDEBAR_MAX_WIDTH
 } from '@/store/layout'
 import { runExportProfileFlow, runImportProfileFlow } from '@/store/profile-share'
-import { $reviewOpen, closeReview, openReview, REVIEW_PANE_ID } from '@/store/review'
+import {
+  $reviewOpen,
+  $reviewScopeCwd,
+  $reviewScopeTarget,
+  closeReview,
+  openReview,
+  REVIEW_PANE_ID
+} from '@/store/review'
 import { $currentCwd, $selectedStoredSessionId, $sessions, $yoloActive, sessionMatchesStoredId } from '@/store/session'
 import { watchSessionPins } from '@/store/session-pin-sync'
 import { watchUnreadWriteGuard } from '@/store/session-unread-remote'
@@ -580,7 +587,7 @@ bindPaneVisibility(
   'review',
   computed([$reviewOpen, $hasWorkspace], (open, workspace) => open && workspace),
   closeReview,
-  openReview
+  () => openReview($reviewScopeCwd.get(), $reviewScopeTarget.get())
 )
 // ⌃` / statusbar toggle — the terminal COLLAPSES to a rail (tab stays), not
 // hides; PTYs stay alive while collapsed (see PersistentTerminal).
diff --git a/apps/desktop/src/app/right-sidebar/review/ship-bar.tsx b/apps/desktop/src/app/right-sidebar/review/ship-bar.tsx
index 2f85a9ade4..3d0e03325f 100644
--- a/apps/desktop/src/app/right-sidebar/review/ship-bar.tsx
+++ b/apps/desktop/src/app/right-sidebar/review/ship-bar.tsx
@@ -15,6 +15,7 @@ import {
   $reviewCommitDefault,
   $reviewCommitMsgBusy,
   $reviewFiles,
+  $reviewScopeTarget,
   $reviewShipBusy,
   $reviewShipInfo,
   cancelCommitMessage,
@@ -35,6 +36,7 @@ export function ReviewShipBar() {
   const c = t.statusStack.coding
   const files = useStore($reviewFiles)
   const ship = useStore($reviewShipInfo)
+  const scopeTarget = useStore($reviewScopeTarget)
   const busy = useStore($reviewShipBusy)
   const generating = useStore($reviewCommitMsgBusy)
   const commitDefault = useStore($reviewCommitDefault)
@@ -129,7 +131,11 @@ export function ReviewShipBar() {
         <Button
           className="min-w-0 flex-1 justify-center px-7 text-[0.7rem] text-muted-foreground/85 hover:text-foreground"
           disabled={!hasFiles}
-          onClick={() => requestComposerSubmit(c.agentShipPrompt, { target: 'main' })}
+          onClick={() => {
+            if (!requestComposerSubmit(c.agentShipPrompt, { target: scopeTarget })) {
+              notifyError(new Error(c.agentShipUnavailable), c.agentShip)
+            }
+          }}
           size="sm"
           variant="ghost"
         >
diff --git a/apps/desktop/src/components/assistant-ui/thread/changed-files-card.tsx b/apps/desktop/src/components/assistant-ui/thread/changed-files-card.tsx
index 021036440d..6d3f6b8346 100644
--- a/apps/desktop/src/components/assistant-ui/thread/changed-files-card.tsx
+++ b/apps/desktop/src/components/assistant-ui/thread/changed-files-card.tsx
@@ -1,6 +1,7 @@
 import { useStore } from '@nanostores/react'
 import { type FC, useMemo } from 'react'
 
+import { useComposerScope } from '@/app/chat/composer/scope'
 import { useSessionView } from '@/app/chat/session-view'
 import { deriveChangedFiles } from '@/components/assistant-ui/thread/changed-files'
 import { WIDGET_SHELL_CLASS } from '@/components/chat/widget-shell'
@@ -33,6 +34,7 @@ export const ChangedFilesCard: FC<{ parts: readonly unknown[] }> = ({ parts }) =
   const view = useSessionView()
   const viewCwd = useStore(view.$cwd)
   const scopeCwd = view.kind === 'primary' ? null : viewCwd || null
+  const composerScope = useComposerScope()
 
   if (files.length === 0) {
     return null
@@ -47,7 +49,7 @@ export const ChangedFilesCard: FC<{ parts: readonly unknown[] }> = ({ parts }) =
         <span className="min-w-0 flex-1 truncate text-(--ui-text-primary)">{copy.filesChanged(files.length)}</span>
         <button
           className="shrink-0 cursor-pointer text-(--ui-text-tertiary) transition-colors hover:text-(--ui-text-primary)"
-          onClick={() => revealReview(scopeCwd)}
+          onClick={() => revealReview(scopeCwd, composerScope.target)}
           type="button"
         >
           {copy.reviewChanges}
@@ -58,7 +60,7 @@ export const ChangedFilesCard: FC<{ parts: readonly unknown[] }> = ({ parts }) =
           <button
             className="row-hover flex shrink-0 items-center gap-2 rounded-md px-1.5 py-1 text-left"
             key={file.path}
-            onClick={() => void openReviewForPath(file.path, scopeCwd)}
+            onClick={() => void openReviewForPath(file.path, scopeCwd, composerScope.target)}
             title={displayPath(file.path)}
             type="button"
           >
diff --git a/apps/desktop/src/i18n/ar.ts b/apps/desktop/src/i18n/ar.ts
index 2c0f27e653..d39a26d2b0 100644
--- a/apps/desktop/src/i18n/ar.ts
+++ b/apps/desktop/src/i18n/ar.ts
@@ -1894,6 +1894,7 @@ export const ar = defineLocale({
       openPr: 'فتح PR',
       ghMissing: 'ثبّت GitHub CLI (gh) وسجّل الدخول لفتح طلبات السحب',
       agentShip: 'اطلب من Hermes فتح PR',
+      agentShipUnavailable: 'المحادثة التي تملك هذه التغييرات ليست على الشاشة.',
       agentShipPrompt: 'راجع التغييرات الحالية، وأودعها برسالة إيداع تقليدية واضحة، وادفع الفرع، وافتح طلب سحب.',
       newBranch: 'فرع جديد',
       branchOffFrom: base => `فرع جديد من ${base}`,
diff --git a/apps/desktop/src/i18n/en.ts b/apps/desktop/src/i18n/en.ts
index 091ae1b828..b3b6d0dcd9 100644
--- a/apps/desktop/src/i18n/en.ts
+++ b/apps/desktop/src/i18n/en.ts
@@ -2433,6 +2433,7 @@ export const en: Translations = {
       openPr: 'Open PR',
       ghMissing: 'Install the GitHub CLI (gh) and sign in to open PRs',
       agentShip: 'Ask Hermes to open PR',
+      agentShipUnavailable: "The chat that owns these changes isn't on screen.",
       agentShipPrompt:
         'Review the current changes, commit them with a clear conventional-commit message, push the branch, and open a pull request.',
       newBranch: 'New branch',
diff --git a/apps/desktop/src/i18n/ja.ts b/apps/desktop/src/i18n/ja.ts
index 5110bf27aa..b31ed718ae 100644
--- a/apps/desktop/src/i18n/ja.ts
+++ b/apps/desktop/src/i18n/ja.ts
@@ -2097,6 +2097,7 @@ export const ja = defineLocale({
       openPr: 'PR を開く',
       ghMissing: 'PR を開くには GitHub CLI (gh) をインストールしてサインインしてください',
       agentShip: 'Hermes にコミットと PR を任せる',
+      agentShipUnavailable: 'この変更を持つチャットが画面にありません。',
       agentShipPrompt:
         '現在の変更を確認し、分かりやすい Conventional Commits 形式でコミットし、ブランチをプッシュして、プルリクエストを作成してください。',
       newBranch: '新しいブランチ',
diff --git a/apps/desktop/src/i18n/types.ts b/apps/desktop/src/i18n/types.ts
index 25ba1df58b..0e4d2ab3c1 100644
--- a/apps/desktop/src/i18n/types.ts
+++ b/apps/desktop/src/i18n/types.ts
@@ -2060,6 +2060,7 @@ export interface Translations {
       openPr: string
       ghMissing: string
       agentShip: string
+      agentShipUnavailable: string
       agentShipPrompt: string
       newBranch: string
       branchOffFrom: (base: string) => string
diff --git a/apps/desktop/src/i18n/zh-hant.ts b/apps/desktop/src/i18n/zh-hant.ts
index 54bb68ecc7..968b5ce113 100644
--- a/apps/desktop/src/i18n/zh-hant.ts
+++ b/apps/desktop/src/i18n/zh-hant.ts
@@ -2034,6 +2034,7 @@ export const zhHant = defineLocale({
       openPr: '開啟 PR',
       ghMissing: '安裝 GitHub CLI (gh) 並登入後可開啟 PR',
       agentShip: '讓 Hermes 提交並開 PR',
+      agentShipUnavailable: '擁有這些變更的對話目前不在畫面上。',
       agentShipPrompt: '檢查目前的變更，使用清晰的約定式提交訊息提交，推送分支，並開啟一個拉取請求。',
       newBranch: '新增分支',
       branchOffFrom: base => `從 ${base} 建立新分支`,
diff --git a/apps/desktop/src/i18n/zh.ts b/apps/desktop/src/i18n/zh.ts
index c78354f41e..54da42fb75 100644
--- a/apps/desktop/src/i18n/zh.ts
+++ b/apps/desktop/src/i18n/zh.ts
@@ -2618,6 +2618,7 @@ export const zh: Translations = {
       openPr: '打开 PR',
       ghMissing: '安装 GitHub CLI (gh) 并登录后可打开 PR',
       agentShip: '让 Hermes 提交并开 PR',
+      agentShipUnavailable: '拥有这些更改的会话当前不在屏幕上。',
       agentShipPrompt: '检查当前更改，使用清晰的约定式提交信息提交，推送分支，并开启一个拉取请求。',
       newBranch: '新建分支',
       branchOffFrom: base => `从 ${base} 新建分支`,
diff --git a/apps/desktop/src/store/review.test.ts b/apps/desktop/src/store/review.test.ts
index 44c882f1e2..446e4f00dc 100644
--- a/apps/desktop/src/store/review.test.ts
+++ b/apps/desktop/src/store/review.test.ts
@@ -14,6 +14,7 @@ import {
   $reviewOpen,
   $reviewRevertTarget,
   $reviewScopeCwd,
+  $reviewScopeTarget,
   $reviewSelectedPath,
   $reviewShipBusy,
   $reviewShipInfo,
@@ -30,9 +31,11 @@ import {
   refreshReview,
   refreshShipInfo,
   requestRevert,
+  revealReview,
   revertReviewFile,
   selectReviewFile,
   stageReviewFile,
+  toggleReview,
   toggleReviewTreeMode,
   unstageReviewFile
 } from './review'
@@ -96,6 +99,7 @@ beforeEach(() => {
   $reviewCommitMsgBusy.set(false)
   $reviewRevertTarget.set(undefined)
   $reviewScopeCwd.set(null)
+  $reviewScopeTarget.set('main')
   $currentCwd.set('/repo')
 })
 
@@ -263,6 +267,45 @@ describe('view state', () => {
     expect(review.list).toHaveBeenCalledWith('/tile-worktree', 'uncommitted', null)
   })
 
+  it('openReview remembers the tile composer that owns the scoped worktree', () => {
+    stubReview()
+
+    openReview('/tile-worktree', 'tile:project-b')
+
+    expect($reviewScopeCwd.get()).toBe('/tile-worktree')
+    expect($reviewScopeTarget.get()).toBe('tile:project-b')
+  })
+
+  it('revealReview re-homes the origin when the repo stays the same', () => {
+    stubReview()
+    openReview('/tile-worktree', 'tile:project-a')
+
+    revealReview('/tile-worktree', 'tile:project-b')
+
+    expect($reviewScopeTarget.get()).toBe('tile:project-b')
+  })
+
+  it('narrow toggle re-homes the origin before showing the overlay', () => {
+    const originalMatchMedia = window.matchMedia
+
+    Object.defineProperty(window, 'matchMedia', {
+      configurable: true,
+      value: vi.fn(() => ({ matches: true }))
+    })
+
+    try {
+      stubReview()
+      openReview('/project-a', 'tile:project-a')
+
+      toggleReview('/project-b', 'tile:project-b')
+
+      expect($reviewScopeCwd.get()).toBe('/project-b')
+      expect($reviewScopeTarget.get()).toBe('tile:project-b')
+    } finally {
+      Object.defineProperty(window, 'matchMedia', { configurable: true, value: originalMatchMedia })
+    }
+  })
+
   it('closeReview closes the pane, clears selection, and drops scope', () => {
     stubReview()
     $reviewOpen.set(true)
@@ -274,6 +317,7 @@ describe('view state', () => {
 
     expect($reviewOpen.get()).toBe(false)
     expect($reviewScopeCwd.get()).toBeNull()
+    expect($reviewScopeTarget.get()).toBe('main')
     expect($reviewSelectedPath.get()).toBeNull()
     expect($reviewDiff.get()).toBeNull()
   })
diff --git a/apps/desktop/src/store/review.ts b/apps/desktop/src/store/review.ts
index 64ebd936c2..11428d20d1 100644
--- a/apps/desktop/src/store/review.ts
+++ b/apps/desktop/src/store/review.ts
@@ -90,6 +90,10 @@ export const $reviewCommitMsgBusy = atom(false)
 // tiles can sit in different worktrees than main, and reviewing "the diff I'm
 // looking at" must mean that tile's repo, not whatever main happens to be on.
 export const $reviewScopeCwd = atom<null | string>(null)
+// The composer target that opened the pane. The review pane is a shared
+// surface, but its "let the agent ship it" action must return to the session
+// whose worktree the user is reviewing, not broadcast to every mounted tile.
+export const $reviewScopeTarget = atom('main')
 
 /** The repo the pane is reading right now: its pinned scope, else the active
  *  session's cwd. Exported for pane helpers that join repo-relative paths. */
@@ -258,9 +262,11 @@ function refreshShipInfoIfStale(): void {
 }
 
 /** Open the pane scoped to `scopeCwd` (a tile's worktree), or to the active
- *  session's cwd when null — see `$reviewScopeCwd`. */
-export function openReview(scopeCwd: null | string = null): void {
+ *  session's cwd when null — see `$reviewScopeCwd`. Keep the originating
+ *  composer target alongside it for agent-ship actions. */
+export function openReview(scopeCwd: null | string = null, scopeTarget = 'main'): void {
   $reviewScopeCwd.set(scopeCwd?.trim() || null)
+  $reviewScopeTarget.set(scopeTarget.trim() || 'main')
   $reviewOpen.set(true)
   void refreshReview()
   void refreshShipInfo()
@@ -269,16 +275,21 @@ export function openReview(scopeCwd: null | string = null): void {
 export function closeReview(): void {
   $reviewOpen.set(false)
   $reviewScopeCwd.set(null)
+  $reviewScopeTarget.set('main')
   clearReviewSelection()
 }
 
-export function toggleReview(scopeCwd: null | string = null): void {
+export function toggleReview(scopeCwd: null | string = null, scopeTarget = 'main'): void {
   // Narrow width: the pane is a collapsed overlay (like the sidebar under ⌘B).
   // Make sure its data is loaded, then slide it in/out via the forced-reveal pin
   // — never the docked open state, which a 0px track would render invisibly.
   if (matchesQuery(SIDEBAR_COLLAPSE_MEDIA_QUERY)) {
-    if (!$reviewOpen.get()) {
-      openReview(scopeCwd)
+    const target = scopeTarget.trim() || 'main'
+    const originChanged =
+      ($reviewScopeCwd.get() ?? null) !== (scopeCwd?.trim() || null) || $reviewScopeTarget.get() !== target
+
+    if (!$reviewOpen.get() || originChanged) {
+      openReview(scopeCwd, target)
     }
 
     window.dispatchEvent(new CustomEvent(PANE_TOGGLE_REVEAL_EVENT, { detail: { id: REVIEW_PANE_ID } }))
@@ -294,7 +305,7 @@ export function toggleReview(scopeCwd: null | string = null): void {
   if (isPaneVisible(REVIEW_PANE_ID)) {
     closeReview()
   } else {
-    revealReview(scopeCwd)
+    revealReview(scopeCwd, scopeTarget)
   }
 }
 
@@ -303,15 +314,18 @@ export function toggleReview(scopeCwd: null | string = null): void {
  * closes an already-open pane — it's the "take me to the diff" entry point used
  * by the transcript's changed-files card.
  */
-export function revealReview(scopeCwd: null | string = null): void {
+export function revealReview(scopeCwd: null | string = null, scopeTarget = 'main'): void {
   const wasOpen = $reviewOpen.get()
+  const target = scopeTarget.trim() || 'main'
 
   if (!wasOpen) {
-    openReview(scopeCwd)
-  } else if (($reviewScopeCwd.get() ?? null) !== (scopeCwd?.trim() || null)) {
+    openReview(scopeCwd, target)
+  } else if (($reviewScopeCwd.get() ?? null) !== (scopeCwd?.trim() || null) || $reviewScopeTarget.get() !== target) {
     // Already open but on another worktree's diff — re-home it. The scope
-    // subscription below clears the stale list and re-probes.
+    // subscription below clears the stale list and re-probes. Keep the
+    // originating composer target alongside the cwd for the agent-ship action.
     $reviewScopeCwd.set(scopeCwd?.trim() || null)
+    $reviewScopeTarget.set(target)
   }
 
   if (matchesQuery(SIDEBAR_COLLAPSE_MEDIA_QUERY)) {
@@ -346,8 +360,12 @@ function matchReviewFile(files: readonly HermesReviewFile[], path: string): Herm
  * Open the review pane on one file's diff. The path comes from a tool call, so
  * it may be absolute while git reports repo-relative — match on the tail.
  */
-export async function openReviewForPath(path: string, scopeCwd: null | string = null): Promise<void> {
-  revealReview(scopeCwd)
+export async function openReviewForPath(
+  path: string,
+  scopeCwd: null | string = null,
+  scopeTarget = 'main'
+): Promise<void> {
+  revealReview(scopeCwd, scopeTarget)
   await refreshReview()
 
   const file = matchReviewFile($reviewFiles.get(), path)

From 2725d3225b902b5f17d27362291c0f3b6ce00596 Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Tue, 18 Aug 2026 15:34:18 -0500
Subject: [PATCH 23/48] fix(tui): stop the composer placeholder from sticking
 Terminal.app into dim
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The placeholder hint and its synthetic cursor chip hand-rolled truecolor
escapes ([38;2;r;g;b / [48;2;r;g;b]) and wrote them raw past Ink's depth
layer. Legacy Terminal.app has no truecolor parser — it walks compound
params one by one, so the literal 2 in 38;2;… lands as SGR 2: dim ON,
with no 22m ever emitted. Every frame that painted the placeholder left
the terminal's dim attribute stuck, and subsequent cells rendered dimmed
until an unrelated bold span's 22m happened to clear it — text randomly
flipping dim and back, worst right after the composer empties.

Measured on a live resumed session (PTY capture, params interpreted the
legacy way): 1026 glyphs painted with stuck dim on main, 0 with the fix.

Route both helpers through Ink's own colorize, the same repair colorizeEcho
got for the fast-echo path (gray-accent bug) — the escape now downgrades
with the terminal's real color depth, and a 256-color terminal gets 38;5;N
it can actually parse.

Also harden hermes-ink's transitionAnsiCodes for compound SGRs: real tool
output ships [1;31m-style sequences whose endCode is [0m, dodging the
endCode-based weight detection — parse the params instead (skipping 38/48
extended-color arguments) so a compound bold→dim transition passes through
SGR 22 too.
---
 .../src/ink/ansi-transition.test.ts           | 27 +++++++
 .../hermes-ink/src/ink/ansi-transition.ts     | 71 +++++++++++++++----
 .../src/__tests__/textInputFastEcho.test.ts   | 36 ++++++++++
 ui-tui/src/components/textInput.tsx           | 24 ++++---
 4 files changed, 135 insertions(+), 23 deletions(-)

diff --git a/ui-tui/packages/hermes-ink/src/ink/ansi-transition.test.ts b/ui-tui/packages/hermes-ink/src/ink/ansi-transition.test.ts
index 358360676f..88eaa2ab37 100644
--- a/ui-tui/packages/hermes-ink/src/ink/ansi-transition.test.ts
+++ b/ui-tui/packages/hermes-ink/src/ink/ansi-transition.test.ts
@@ -48,6 +48,33 @@ describe('transitionAnsiCodes weight family', () => {
   it('unchanged styles emit nothing', () => {
     expect(transitionAnsiCodes([BOLD, FG_PINK], [BOLD, FG_PINK])).toEqual([])
   })
+
+  // Real tool output (ls/grep) ships COMPOUND sequences like `[1;31m` whose
+  // endCode is `[0m` — weight detection must parse params, not endCodes.
+  const compound = (params: string) => ({ type: 'ansi' as const, code: `${ESC}[${params}m`, endCode: `${ESC}[0m` })
+
+  it('compound bold → compound dim resets the weight family', () => {
+    expect(codes(transitionAnsiCodes([compound('1;31')], [compound('2;37')]))).toEqual([
+      `${ESC}[22m`,
+      `${ESC}[2;37m`
+    ])
+  })
+
+  it('compound bold → compound bold (color change) stays minimal', () => {
+    expect(codes(transitionAnsiCodes([compound('1;31')], [compound('1;32')]))).toEqual([`${ESC}[1;32m`])
+  })
+
+  it('compound weight removal to plain emits the reset', () => {
+    expect(codes(transitionAnsiCodes([compound('1;31')], [FG_GRAY]))).toEqual([`${ESC}[22m`, `${ESC}[38;5;245m`])
+  })
+
+  it('extended-color arguments are not read as weight atoms', () => {
+    // `38;2;r;g;b` / `38;5;N` carry literal 2/5 sub-params: not SGR atoms.
+    const tc = { type: 'ansi' as const, code: `${ESC}[38;2;120;87;109m`, endCode: `${ESC}[39m` }
+
+    expect(codes(transitionAnsiCodes([tc], [FG_GRAY]))).toEqual([`${ESC}[38;5;245m`])
+    expect(codes(transitionAnsiCodes([FG_PINK], [tc]))).toEqual([`${ESC}[38;2;120;87;109m`])
+  })
 })
 
 describe('StylePool.transition weight correctness', () => {
diff --git a/ui-tui/packages/hermes-ink/src/ink/ansi-transition.ts b/ui-tui/packages/hermes-ink/src/ink/ansi-transition.ts
index 2d2d920faf..174b10321b 100644
--- a/ui-tui/packages/hermes-ink/src/ink/ansi-transition.ts
+++ b/ui-tui/packages/hermes-ink/src/ink/ansi-transition.ts
@@ -12,6 +12,12 @@ import { type AnsiCode, diffAnsiCodes } from '@alcalzone/ansi-tokenize'
  * corruption compounds and sticks — visible as random spans of wrong
  * weight/brightness ("random dimness/opacity changes") that depend on which
  * cells happened to change in which order.
+ *
+ * Weight flags hide in two shapes: standalone `[1m`/`[2m` (endCode `[22m`),
+ * and compound sequences from real tool output — `[1;31m` ls/grep style —
+ * whose endCode is `[0m`, dodging any endCode-based check. Both are detected
+ * by parsing the params (skipping 38/48 extended-color arguments, whose
+ * literal `2`/`5` sub-params are not SGR atoms).
  */
 const WEIGHT_END = '\u001b[22m'
 
@@ -21,22 +27,61 @@ const WEIGHT_RESET: AnsiCode = {
   endCode: WEIGHT_END
 }
 
+const SGR_PARAMS_RE = /^\u001b\[([0-9;]*)m$/
+
+/** The bold/dim atoms ('1' / '2') a single SGR sequence turns on. */
+function weightAtoms(code: AnsiCode): string[] {
+  const match = SGR_PARAMS_RE.exec(code.code)
+
+  if (!match) {
+    return []
+  }
+
+  const parts = (match[1] || '0').split(';')
+  const atoms: string[] = []
+
+  for (let i = 0; i < parts.length; i++) {
+    const p = parts[i] || '0'
+
+    if ((p === '38' || p === '48') && i + 1 < parts.length) {
+      // Extended color: consume the argument sub-params so their literal
+      // 2/5 aren't read as weight atoms.
+      i += parts[i + 1] === '5' ? 2 : parts[i + 1] === '2' ? 4 : 0
+      continue
+    }
+
+    if (p === '1' || p === '2') {
+      atoms.push(p)
+    }
+  }
+
+  return atoms
+}
+
+const carriesWeight = (code: AnsiCode): boolean => weightAtoms(code).length > 0
+
 /**
  * Like `diffAnsiCodes`, but correct for the shared-reset weight family:
  * when the bold/dim set changes in a way that removes a flag, emit SGR 22
- * first, then re-apply every weight flag the target style carries.
+ * first, then re-apply every weight-carrying sequence the target style has.
  */
 export function transitionAnsiCodes(from: AnsiCode[], to: AnsiCode[]): AnsiCode[] {
-  const fromWeights = from.filter(code => code.endCode === WEIGHT_END)
-  const toWeights = to.filter(code => code.endCode === WEIGHT_END)
+  const fromAtoms = new Set(from.flatMap(weightAtoms))
 
-  if (fromWeights.length === 0) {
+  if (fromAtoms.size === 0) {
     // Nothing to un-set; the library's "add what's missing" pass is correct.
     return diffAnsiCodes(from, to)
   }
 
-  const toWeightCodes = new Set(toWeights.map(code => code.code))
-  const removesWeight = fromWeights.some(code => !toWeightCodes.has(code.code))
+  const toAtoms = new Set(to.flatMap(weightAtoms))
+  let removesWeight = false
+
+  for (const atom of fromAtoms) {
+    if (!toAtoms.has(atom)) {
+      removesWeight = true
+      break
+    }
+  }
 
   if (!removesWeight) {
     // from's weights ⊆ to's weights — additions only, library handles it.
@@ -44,13 +89,11 @@ export function transitionAnsiCodes(from: AnsiCode[], to: AnsiCode[]): AnsiCode[
   }
 
   // A weight flag must be dropped: SGR 22 is the only way (it clears BOTH),
-  // so reset the family and re-apply the target's full weight set. The rest
-  // of the style (colors, italic, underline, …) diffs normally with the
-  // weight family stripped from both sides.
-  const rest = diffAnsiCodes(
-    from.filter(code => code.endCode !== WEIGHT_END),
-    to.filter(code => code.endCode !== WEIGHT_END)
-  )
+  // so reset the family and re-apply the target's weight-carrying sequences
+  // in full (a compound re-asserts its color too — redundant bytes, never
+  // wrong). The rest of the style diffs normally with the weight carriers
+  // stripped from both sides.
+  const rest = diffAnsiCodes(from.filter(code => !carriesWeight(code)), to.filter(code => !carriesWeight(code)))
 
-  return [WEIGHT_RESET, ...rest, ...toWeights]
+  return [WEIGHT_RESET, ...rest, ...to.filter(carriesWeight)]
 }
diff --git a/ui-tui/src/__tests__/textInputFastEcho.test.ts b/ui-tui/src/__tests__/textInputFastEcho.test.ts
index 21550327e5..cc4f088174 100644
--- a/ui-tui/src/__tests__/textInputFastEcho.test.ts
+++ b/ui-tui/src/__tests__/textInputFastEcho.test.ts
@@ -5,6 +5,8 @@ import {
   canFastAppendShape,
   canFastBackspaceShape,
   colorizeEcho,
+  colorizeHint,
+  hintCursorCell,
   supportsFastEchoTerminal
 } from '../components/textInput.js'
 
@@ -208,6 +210,40 @@ describe('colorizeEcho', () => {
   })
 })
 
+describe('colorizeHint / hintCursorCell', () => {
+  // The placeholder bypass writes raw bytes past Ink too. Hand-rolling
+  // `38;2;r;g;b` here was WORSE than the gray-accent bug colorizeEcho had:
+  // legacy Terminal.app walks compound params one by one, so the literal `2`
+  // in `38;2;…` landed as SGR 2 (dim ON) with no closing `22m` — every
+  // frame that painted the placeholder left the terminal's dim flag stuck,
+  // and later unstyled cells rendered randomly dimmed. Both helpers must
+  // route through Ink's own colorize so depth downgrades with the terminal.
+
+  it('hint matches Ink exactly, never a hand-rolled truecolor escape', () => {
+    for (const tone of ['#8a8094', '#e77fa3']) {
+      expect(colorizeHint('Try it', tone)).toBe(colorize('Try it', tone, 'foreground'))
+    }
+  })
+
+  it('hint falls back to the neutral gray on junk, still through colorize', () => {
+    expect(colorizeHint('x')).toBe(colorize('x', '#808080', 'foreground'))
+    expect(colorizeHint('x', 'nope')).toBe(colorize('x', '#808080', 'foreground'))
+  })
+
+  it('cursor chip composes bg+fg through colorize only', () => {
+    expect(hintCursorCell('T', '#8a8094')).toBe(
+      colorize(colorize('T', '#ffffff', 'foreground'), '#8a8094', 'background')
+    )
+  })
+
+  it('never emits a raw 38;2/48;2 the depth layer did not choose', () => {
+    // chalk is level 0 under vitest, so ANY escape byte here means the
+    // helper bypassed colorize and hand-rolled the sequence.
+    expect(colorizeHint('x', '#8a8094')).not.toContain('\u001b')
+    expect(hintCursorCell('x', '#8a8094')).not.toContain('\u001b')
+  })
+})
+
 describe('supportsFastEchoTerminal', () => {
   it('disables fast-echo in Apple Terminal', () => {
     expect(supportsFastEchoTerminal({ TERM_PROGRAM: 'Apple_Terminal' } as NodeJS.ProcessEnv)).toBe(false)
diff --git a/ui-tui/src/components/textInput.tsx b/ui-tui/src/components/textInput.tsx
index 958fa4010a..cc630e3df4 100644
--- a/ui-tui/src/components/textInput.tsx
+++ b/ui-tui/src/components/textInput.tsx
@@ -52,7 +52,7 @@ type MinimalEnv = Record<string, string | undefined>
 
 const invert = (s: string) => INV + s + INV_OFF
 
-// Placeholder styling is EXPLICIT truecolor only — never SGR dim/inverse:
+// Placeholder styling is EXPLICIT color only — never SGR dim/inverse:
 // both are terminal-interpreted relative to the default fg/bg, and on
 // transparent profiles (terminal.background #00000000) they composite
 // against a black RGB the user never sees — the hint rendered as a slab.
@@ -64,11 +64,15 @@ const hintRgb = (hex?: string): [number, number, number] => {
   return [(n >> 16) & 0xff, (n >> 8) & 0xff, n & 0xff]
 }
 
-const colorizeHint = (s: string, hex?: string) => {
-  const [r, g, b] = hintRgb(hex)
+const hintHex = (hex?: string): string => (/^#[0-9a-f]{6}$/i.test(hex ?? '') ? hex! : HINT_FALLBACK)
 
-  return `${ESC}[38;2;${r};${g};${b}m${s}${ESC}[39m`
-}
+// Through Ink's own `colorize` (see fgSeq below): a hand-rolled 38;2;r;g;b
+// is worse than unparseable on a non-truecolor terminal — legacy
+// Terminal.app consumes the params one by one, and the `2` in `38;2;…`
+// lands as SGR 2 (dim ON) with no `22m` ever emitted. Every subsequent
+// frame's unstyled cells then paint dim until an unrelated bold span's
+// `22m` clears it: text randomly dims after the placeholder renders.
+export const colorizeHint = (s: string, hex?: string) => colorize(s, hintHex(hex), 'foreground')
 
 /**
  * The SGR foreground-open sequence for a theme tone, or '' when it has none.
@@ -110,12 +114,14 @@ export const colorizeEcho = (s: string, hex?: string) => {
 }
 
 /** Synthetic placeholder cursor: a hint-colored chip with luminance-picked
- *  ink, standing in for the hidden hardware cursor (bubbles pattern). */
-const hintCursorCell = (ch: string, hex?: string) => {
+ *  ink, standing in for the hidden hardware cursor (bubbles pattern).
+ *  Both halves go through `colorize` so the escapes match the terminal's
+ *  real color depth (same hazard as colorizeHint above). */
+export const hintCursorCell = (ch: string, hex?: string) => {
   const [r, g, b] = hintRgb(hex)
-  const ink = 0.2126 * r + 0.7152 * g + 0.0722 * b > 140 ? '0;0;0' : '255;255;255'
+  const ink = 0.2126 * r + 0.7152 * g + 0.0722 * b > 140 ? '#000000' : '#ffffff'
 
-  return `${ESC}[48;2;${r};${g};${b}m${ESC}[38;2;${ink}m${ch}${ESC}[39m${ESC}[49m`
+  return colorize(colorize(ch, ink, 'foreground'), hintHex(hex), 'background')
 }
 
 let _seg: Intl.Segmenter | null = null

From 6a3d50c6e05ee9a3c1e5ecf2268524c5d0627b9f Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 19 Aug 2026 02:50:29 -0500
Subject: [PATCH 24/48] fix(tui): allow the ESC byte in the SGR param matcher

eslint no-control-regex rejects the CSI regex even though ESC is the
sequence we have to parse.
---
 ui-tui/packages/hermes-ink/src/ink/ansi-transition.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/ui-tui/packages/hermes-ink/src/ink/ansi-transition.ts b/ui-tui/packages/hermes-ink/src/ink/ansi-transition.ts
index 174b10321b..f534315dcc 100644
--- a/ui-tui/packages/hermes-ink/src/ink/ansi-transition.ts
+++ b/ui-tui/packages/hermes-ink/src/ink/ansi-transition.ts
@@ -27,6 +27,7 @@ const WEIGHT_RESET: AnsiCode = {
   endCode: WEIGHT_END
 }
 
+// eslint-disable-next-line no-control-regex -- SGR CSI matcher; ESC is intentional
 const SGR_PARAMS_RE = /^\u001b\[([0-9;]*)m$/
 
 /** The bold/dim atoms ('1' / '2') a single SGR sequence turns on. */

From 9b5e7a32269fbe478001bfa2a3d5bcb8ede0cd00 Mon Sep 17 00:00:00 2001
From: Teknium <127238744+teknium1@users.noreply.github.com>
Date: Wed, 19 Aug 2026 03:15:17 -0700
Subject: [PATCH 25/48] =?UTF-8?q?fix(image=5Fgen):=20Grok=20Imagine=202.0?=
 =?UTF-8?q?=20no=20longer=20upscales=20by=20default=20=E2=80=94=20opt-in?=
 =?UTF-8?q?=20policy=20restored?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ceabb030f added the Grok Imagine Image 2.0 catalog entry with upscale=True,
violating the Aug 2026 opt-in-only upscaling policy (f06c41522) and breaking
test_upscale_defaults_are_all_off on main, which reddened every PR's slice
12/12.
---
 tools/image_generation_tool.py | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/tools/image_generation_tool.py b/tools/image_generation_tool.py
index daab670c36..f794ca6268 100644
--- a/tools/image_generation_tool.py
+++ b/tools/image_generation_tool.py
@@ -685,7 +685,10 @@ FAL_MODELS: Dict[str, Dict[str, Any]] = {
             "prompt", "aspect_ratio", "num_images", "output_format",
             "resolution", "quality", "sync_mode",
         },
-        "upscale": True,   # 1k native is sub-2MP
+        # Opt-in only (policy: default-on upscaling was disabled everywhere
+        # Aug 2026; the upscaler is a creative enhancer that can alter fine
+        # detail). 1k native is sub-2MP — pass upscale=true when needed.
+        "upscale": False,
         # Edit endpoint takes `image_urls` (max 3) + the same knobs;
         # aspect_ratio defaults to "auto" (follows the first input image),
         # so we don't send it on edits.

From 84d81d258fda93416d6d8a29cdeaa8784e0b3104 Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 19 Aug 2026 11:01:21 -0500
Subject: [PATCH 26/48] fix(tour): an unanswered tour bridge no longer costs
 45s per action
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The renderer's `tour.request` handler ships in the desktop bundle, but the
tool is offered by the backend, and the two update on different clocks. A
desktop build older than the tour tool receives the event in a renderer with
no branch for it, so `tour.respond` never comes and the agent blocks for the
full 45s deadline — once per action the model tries. A single "give me a
tour" turn (targets, then narrate, then stop) stacked those waits into
minutes of dead air, which is what got reported against #89620.

Hold a session's first action to a deadline a working renderer cannot miss,
and let an unanswered probe mark the bridge unavailable for that session:
later calls return immediately with an error naming the actual fix instead
of stalling again. Once a client has answered, real actions get the full
deadline back, so a preview tour injecting into a live page still works and
one slow action no longer condemns a live client. The verdict lives on the
session record, so it dies with the session and a new one re-probes.

The same five-action sequence goes from ~225s of dead air to a single 10s
probe. Toolset gating is unchanged: removing the tool outright needs a
client capability declared at session.create, which prompt caching means
can only take effect for a new session.
---
 tests/tools/test_tour_tool.py                 |  80 ++++++++++++++
 .../tui_gateway/test_tour_bridge_fail_fast.py | 101 ++++++++++++++++++
 tui_gateway/server.py                         |  78 ++++++++++++--
 3 files changed, 251 insertions(+), 8 deletions(-)
 create mode 100644 tests/tools/test_tour_tool.py
 create mode 100644 tests/tui_gateway/test_tour_bridge_fail_fast.py

diff --git a/tests/tools/test_tour_tool.py b/tests/tools/test_tour_tool.py
new file mode 100644
index 0000000000..f6147f6274
--- /dev/null
+++ b/tests/tools/test_tour_tool.py
@@ -0,0 +1,80 @@
+"""Tests for the GUI-surface ``tour`` tool."""
+
+import json
+
+from tools import tour_tool as tt
+from tools.registry import registry
+
+
+def _run(**kwargs):
+    kwargs.setdefault("callback", lambda _payload: json.dumps({"success": True}))
+    return json.loads(tt.tour_tool(**kwargs))
+
+
+def test_lives_in_the_gui_surface_toolset(monkeypatch):
+    """Scoped by toolset, not by the backend's env — see AGENTS.md."""
+    monkeypatch.delenv("HERMES_DESKTOP", raising=False)
+    entry = registry.get_entry("tour")
+
+    assert entry is not None
+    assert entry.toolset == "desktop_ui"
+    assert entry.check_fn is None
+
+
+def test_requires_callback():
+    """Outside the desktop GUI there is no bridge — a clear error, no crash."""
+    assert "desktop" in json.loads(tt.tour_tool(action="targets", callback=None))["error"]
+
+
+def test_rejects_unknown_action_and_surface():
+    assert "action must be one of" in _run(action="dance")["error"]
+    assert "surface must be one of" in _run(action="targets", surface="hologram")["error"]
+    assert "side must be one of" in _run(action="show", selector="#a", side="diagonal")["error"]
+
+
+def test_show_needs_something_to_point_at_or_say():
+    assert "show needs" in _run(action="show")["error"]
+    assert "error" not in _run(action="show", text="just narration")
+
+
+def test_start_validates_its_steps():
+    assert "non-empty steps" in _run(action="start")["error"]
+    assert "non-empty steps" in _run(action="start", steps=[])["error"]
+    assert "steps[1] must be an object" in _run(action="start", steps=[{"selector": "#a"}, "nope"])["error"]
+    assert "steps[1] needs" in _run(action="start", steps=[{"selector": "#a"}, {}])["error"]
+
+
+def test_payload_omits_unset_fields_and_defaults_the_surface():
+    seen = {}
+
+    def cb(payload):
+        seen.update(payload)
+        return json.dumps({"success": True})
+
+    tt.tour_tool(action="show", selector="#composer", title="Composer", callback=cb)
+    assert seen == {
+        "action": "show",
+        "surface": "app",
+        "selector": "#composer",
+        "title": "Composer",
+    }
+
+
+def test_unanswered_bridge_is_reported_rather_than_faked_as_success():
+    assert "error" in _run(action="targets", callback=lambda _p: "")
+
+
+def test_passes_renderer_json_through():
+    payload = {"success": True, "matched": True, "step": 2}
+    assert _run(action="next", callback=lambda _p: json.dumps(payload)) == payload
+
+
+def test_wraps_non_json_text():
+    assert _run(action="stop", callback=lambda _p: "stopped") == {"text": "stopped"}
+
+
+def test_callback_failure_is_reported():
+    def _boom(_payload):
+        raise RuntimeError("renderer went away")
+
+    assert "renderer went away" in _run(action="stop", callback=_boom)["error"]
diff --git a/tests/tui_gateway/test_tour_bridge_fail_fast.py b/tests/tui_gateway/test_tour_bridge_fail_fast.py
new file mode 100644
index 0000000000..0699895d55
--- /dev/null
+++ b/tests/tui_gateway/test_tour_bridge_fail_fast.py
@@ -0,0 +1,101 @@
+"""A desktop client that cannot answer ``tour.request`` must not cost a full
+bridge timeout per call.
+
+The renderer's handler ships in the desktop bundle; the tool is offered by the
+backend. An app build older than the tour tool has no branch for the event, so
+nothing ever calls ``tour.respond`` and the agent blocks for the whole deadline
+— once per action the model tries. See tui_gateway.server._tour_request.
+"""
+
+import json
+
+import pytest
+
+import tui_gateway.server as server
+
+
+@pytest.fixture
+def session(monkeypatch):
+    record = {}
+    monkeypatch.setitem(server._sessions, "s1", record)
+    return record
+
+
+@pytest.fixture
+def bridge(monkeypatch):
+    """Record every _block call and serve canned answers."""
+    calls = []
+
+    def fake_block(event, sid, payload, timeout=None, **_kw):
+        answer = fake_block.answers.pop(0) if fake_block.answers else ""
+        calls.append({"event": event, "sid": sid, "payload": payload, "timeout": timeout})
+        return answer
+
+    fake_block.answers = []
+    fake_block.calls = calls
+    monkeypatch.setattr(server, "_block", fake_block)
+    return fake_block
+
+
+def test_first_action_is_probed_on_a_short_deadline(session, bridge):
+    bridge.answers = [json.dumps({"success": True})]
+    server._tour_request("s1", {"action": "targets"})
+
+    assert bridge.calls[0]["event"] == "tour.request"
+    assert bridge.calls[0]["timeout"] == server._TOUR_PROBE_TIMEOUT_S
+    assert server._TOUR_PROBE_TIMEOUT_S < server._TOUR_TIMEOUT_S
+
+
+def test_a_client_that_answers_gets_the_full_deadline_back(session, bridge):
+    """The generous deadline exists for a preview tour injecting into a live
+    page; only an unproven client is held to the probe."""
+    bridge.answers = [json.dumps({"success": True}), json.dumps({"success": True})]
+    server._tour_request("s1", {"action": "targets"})
+    server._tour_request("s1", {"action": "show", "selector": "#composer"})
+
+    assert bridge.calls[1]["timeout"] == server._TOUR_TIMEOUT_S
+
+
+def test_unanswered_probe_explains_the_real_problem(session, bridge):
+    result = json.loads(server._tour_request("s1", {"action": "targets"}))
+
+    assert result["success"] is False
+    assert "desktop" in result["error"].lower()
+    assert "update" in result["error"].lower()
+
+
+def test_later_actions_short_circuit_instead_of_stalling_again(session, bridge):
+    """The regression: a "give me a tour" turn stacks one timeout per action."""
+    server._tour_request("s1", {"action": "targets"})
+    for action in ("show", "start", "next", "stop"):
+        assert json.loads(server._tour_request("s1", {"action": action}))["success"] is False
+
+    assert len(bridge.calls) == 1
+
+
+def test_a_proven_client_is_not_condemned_by_one_slow_action(session, bridge):
+    """A transient miss on a live renderer must not disable the tour."""
+    bridge.answers = [json.dumps({"success": True})]
+    server._tour_request("s1", {"action": "targets"})
+    server._tour_request("s1", {"action": "show", "selector": "#composer"})
+
+    bridge.answers = [json.dumps({"success": True})]
+    assert json.loads(server._tour_request("s1", {"action": "next"}))["success"] is True
+    assert len(bridge.calls) == 3
+
+
+def test_a_new_session_reprobes(bridge, monkeypatch):
+    """The verdict lives on the session record, so it dies with the session."""
+    monkeypatch.setitem(server._sessions, "dead", {})
+    monkeypatch.setitem(server._sessions, "fresh", {})
+
+    server._tour_request("dead", {"action": "targets"})
+    bridge.answers = [json.dumps({"success": True})]
+
+    assert json.loads(server._tour_request("fresh", {"action": "targets"}))["success"] is True
+
+
+def test_a_session_with_no_record_still_bridges(bridge):
+    """Detached callers have no session dict; they keep the plain bridge."""
+    bridge.answers = [json.dumps({"success": True})]
+    assert json.loads(server._tour_request("gone", {"action": "targets"}))["success"] is True
diff --git a/tui_gateway/server.py b/tui_gateway/server.py
index 9493814bd0..11d2cb1791 100644
--- a/tui_gateway/server.py
+++ b/tui_gateway/server.py
@@ -3618,6 +3618,74 @@ def _clarify_block(sid: str, q, c, multi_select=False, questions=None) -> str:
     )
 
 
+# A tour action is a DOM operation the renderer performs and answers straight
+# back, so a client that implements the bridge replies in milliseconds. The
+# generous deadline exists for one case only: a preview tour's first action
+# injects the engine into a live page.
+_TOUR_TIMEOUT_S = 45
+# Until a session's client has proven it answers at all, hold it to a deadline
+# a working renderer cannot miss. See _tour_request.
+_TOUR_PROBE_TIMEOUT_S = 10
+
+_TOUR_BRIDGE_UNAVAILABLE = json.dumps(
+    {
+        "success": False,
+        "error": (
+            "No Hermes Desktop window answered the tour request. The tour is "
+            "driven by the desktop app's renderer, which updates separately "
+            "from this backend, so an app build older than the tour tool has "
+            "nothing listening. Update the Hermes Desktop app and start a new "
+            "session. Do not retry tour in this session."
+        ),
+    }
+)
+
+
+def _tour_request(sid: str, payload: dict) -> str:
+    """Bridge the tour tool callback onto _block, without paying for a client
+    that cannot answer it.
+
+    The renderer's ``tour.request`` handler ships in the desktop bundle, but
+    the tool is offered by this backend — and the two update on different
+    clocks. Against an app older than the tool the event lands in a renderer
+    with no branch for it, nobody ever calls ``tour.respond``, and the agent
+    blocks for the full deadline. The model then does what the schema tells it
+    to and tries the next action, so a single "give me a tour" turn stacks
+    those waits (the timeouts reported against #89620).
+
+    A session's first action therefore gets the probe deadline, and an
+    unanswered probe marks the bridge unavailable for that session: every later
+    call returns immediately, telling the user what to actually fix instead of
+    stalling again. Once a client has answered, real actions get the full
+    deadline back and a single slow one no longer condemns it. The verdict
+    lives on the session record, so it dies with the session and a new one
+    re-probes.
+    """
+    # A detached caller has no session record; the throwaway keeps it on the
+    # plain bridge, unprobed.
+    session = _sessions.get(sid)
+    if session is None:
+        session = {}
+    state = session.get("tour_bridge")
+
+    if state == "unanswered":
+        return _TOUR_BRIDGE_UNAVAILABLE
+
+    answer = _block(
+        "tour.request",
+        sid,
+        dict(payload),
+        timeout=_TOUR_TIMEOUT_S if state == "answered" else _TOUR_PROBE_TIMEOUT_S,
+    )
+
+    if answer:
+        session["tour_bridge"] = "answered"
+    elif state != "answered":
+        session["tour_bridge"] = "unanswered"
+
+    return answer or _TOUR_BRIDGE_UNAVAILABLE
+
+
 def _clear_pending(sid: str | None = None) -> None:
     """Release pending prompts with an empty answer.
 
@@ -6325,14 +6393,8 @@ def _agent_cbs(sid: str) -> dict:
         # tour tool (desktop GUI): the renderer drives driver.js — highlighting
         # elements in the app's own DOM or injecting the engine into the
         # preview pane's webview — and answers tour.respond with the outcome
-        # (did the selector match, which step is active). Generous timeout: a
-        # preview tour's first action loads the engine into a live page.
-        "tour_callback": lambda payload: _block(
-            "tour.request",
-            sid,
-            dict(payload),
-            timeout=45,
-        ),
+        # (did the selector match, which step is active).
+        "tour_callback": lambda payload: _tour_request(sid, payload),
     }
 
     # Interim assistant commentary (text alongside tool calls, or the attempted

From eab087c06fd6bc46903499663e6bf0687011bf4b Mon Sep 17 00:00:00 2001
From: "hermes-seaeye[bot]"
 <307254004+hermes-seaeye[bot]@users.noreply.github.com>
Date: Wed, 19 Aug 2026 16:56:58 +0000
Subject: [PATCH 27/48] fmt(js): `npm run fix` on merge (#90140)

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
---
 .../electron/windows-hermes-path.test.ts      | 27 ++++++++++---------
 apps/desktop/src/app/chat/composer/focus.ts   |  4 +--
 .../hooks/use-composer-submit.test.tsx        |  1 +
 apps/desktop/src/store/review.ts              |  1 +
 apps/desktop/src/store/translucency.test.ts   |  2 +-
 .../src/ink/ansi-transition.test.ts           |  5 +---
 .../hermes-ink/src/ink/ansi-transition.ts     |  7 ++++-
 7 files changed, 27 insertions(+), 20 deletions(-)

diff --git a/apps/desktop/electron/windows-hermes-path.test.ts b/apps/desktop/electron/windows-hermes-path.test.ts
index 76e4d0ac50..0c49b4a2ac 100644
--- a/apps/desktop/electron/windows-hermes-path.test.ts
+++ b/apps/desktop/electron/windows-hermes-path.test.ts
@@ -46,10 +46,11 @@ test('buildPathExtCandidates: non-Windows only tries the bare name', () => {
 })
 
 test('chooseUpdaterArgs: gentle --update when both updater runtime files exist', () => {
-  assert.deepEqual(
-    chooseUpdaterArgs({ hasBootstrapMarker: true, hasVenvHermes: true, hasVenvPython: true }, 'main'),
-    ['--update', '--branch', 'main']
-  )
+  assert.deepEqual(chooseUpdaterArgs({ hasBootstrapMarker: true, hasVenvHermes: true, hasVenvPython: true }, 'main'), [
+    '--update',
+    '--branch',
+    'main'
+  ])
 })
 
 test('chooseUpdaterArgs: marker-only install uses --repair when the venv is gone', () => {
@@ -60,14 +61,16 @@ test('chooseUpdaterArgs: marker-only install uses --repair when the venv is gone
 })
 
 test('chooseUpdaterArgs: partial updater runtimes use --repair', () => {
-  assert.deepEqual(
-    chooseUpdaterArgs({ hasBootstrapMarker: true, hasVenvHermes: false, hasVenvPython: true }, 'main'),
-    ['--repair', '--branch', 'main']
-  )
-  assert.deepEqual(
-    chooseUpdaterArgs({ hasBootstrapMarker: true, hasVenvHermes: true, hasVenvPython: false }, 'main'),
-    ['--repair', '--branch', 'main']
-  )
+  assert.deepEqual(chooseUpdaterArgs({ hasBootstrapMarker: true, hasVenvHermes: false, hasVenvPython: true }, 'main'), [
+    '--repair',
+    '--branch',
+    'main'
+  ])
+  assert.deepEqual(chooseUpdaterArgs({ hasBootstrapMarker: true, hasVenvHermes: true, hasVenvPython: false }, 'main'), [
+    '--repair',
+    '--branch',
+    'main'
+  ])
 })
 
 test('chooseUpdaterArgs: passes the branch through unchanged in both modes', () => {
diff --git a/apps/desktop/src/app/chat/composer/focus.ts b/apps/desktop/src/app/chat/composer/focus.ts
index 6e450c10f8..023afe92dd 100644
--- a/apps/desktop/src/app/chat/composer/focus.ts
+++ b/apps/desktop/src/app/chat/composer/focus.ts
@@ -311,8 +311,8 @@ export const requestComposerSubmit = (
   }
 
   const resolvedTarget = resolve(target)
-  const surfaceId =
-    requestedSurfaceId === undefined ? getVisibleComposerSurfaceId(resolvedTarget) : requestedSurfaceId
+
+  const surfaceId = requestedSurfaceId === undefined ? getVisibleComposerSurfaceId(resolvedTarget) : requestedSurfaceId
 
   // Fail closed: without an exact visible surface identity, broadcasting a
   // submit could make more than one keep-alive/new-chat composer claim it.
diff --git a/apps/desktop/src/app/chat/composer/hooks/use-composer-submit.test.tsx b/apps/desktop/src/app/chat/composer/hooks/use-composer-submit.test.tsx
index c278356d05..b05a47a581 100644
--- a/apps/desktop/src/app/chat/composer/hooks/use-composer-submit.test.tsx
+++ b/apps/desktop/src/app/chat/composer/hooks/use-composer-submit.test.tsx
@@ -148,6 +148,7 @@ describe('useComposerSubmit external request routing', () => {
     const visibleMain = renderSubmitHook({ sessionKey: 'session-a' })
     const hiddenMain = renderSubmitHook({ sessionKey: 'session-b', visible: false })
     const visibleTile = renderSubmitHook({ scopeTarget: 'tile:project-b', sessionKey: 'tile-session' })
+
     const hiddenTile = renderSubmitHook({
       scopeTarget: 'tile:project-c',
       sessionKey: 'other-tile',
diff --git a/apps/desktop/src/store/review.ts b/apps/desktop/src/store/review.ts
index 11428d20d1..9704ac338e 100644
--- a/apps/desktop/src/store/review.ts
+++ b/apps/desktop/src/store/review.ts
@@ -285,6 +285,7 @@ export function toggleReview(scopeCwd: null | string = null, scopeTarget = 'main
   // — never the docked open state, which a 0px track would render invisibly.
   if (matchesQuery(SIDEBAR_COLLAPSE_MEDIA_QUERY)) {
     const target = scopeTarget.trim() || 'main'
+
     const originChanged =
       ($reviewScopeCwd.get() ?? null) !== (scopeCwd?.trim() || null) || $reviewScopeTarget.get() !== target
 
diff --git a/apps/desktop/src/store/translucency.test.ts b/apps/desktop/src/store/translucency.test.ts
index 538db4faab..a2861a952f 100644
--- a/apps/desktop/src/store/translucency.test.ts
+++ b/apps/desktop/src/store/translucency.test.ts
@@ -194,7 +194,7 @@ describe('glass mode', () => {
     setTranslucency(TRANSLUCENCY_MIN)
   })
 
-    it('rejects glass when the platform cannot back it', () => {
+  it('rejects glass when the platform cannot back it', () => {
     setTranslucency(50)
     setTranslucencyMode('glass')
 
diff --git a/ui-tui/packages/hermes-ink/src/ink/ansi-transition.test.ts b/ui-tui/packages/hermes-ink/src/ink/ansi-transition.test.ts
index 88eaa2ab37..63a5087327 100644
--- a/ui-tui/packages/hermes-ink/src/ink/ansi-transition.test.ts
+++ b/ui-tui/packages/hermes-ink/src/ink/ansi-transition.test.ts
@@ -54,10 +54,7 @@ describe('transitionAnsiCodes weight family', () => {
   const compound = (params: string) => ({ type: 'ansi' as const, code: `${ESC}[${params}m`, endCode: `${ESC}[0m` })
 
   it('compound bold → compound dim resets the weight family', () => {
-    expect(codes(transitionAnsiCodes([compound('1;31')], [compound('2;37')]))).toEqual([
-      `${ESC}[22m`,
-      `${ESC}[2;37m`
-    ])
+    expect(codes(transitionAnsiCodes([compound('1;31')], [compound('2;37')]))).toEqual([`${ESC}[22m`, `${ESC}[2;37m`])
   })
 
   it('compound bold → compound bold (color change) stays minimal', () => {
diff --git a/ui-tui/packages/hermes-ink/src/ink/ansi-transition.ts b/ui-tui/packages/hermes-ink/src/ink/ansi-transition.ts
index f534315dcc..e7fc83bb87 100644
--- a/ui-tui/packages/hermes-ink/src/ink/ansi-transition.ts
+++ b/ui-tui/packages/hermes-ink/src/ink/ansi-transition.ts
@@ -48,6 +48,7 @@ function weightAtoms(code: AnsiCode): string[] {
       // Extended color: consume the argument sub-params so their literal
       // 2/5 aren't read as weight atoms.
       i += parts[i + 1] === '5' ? 2 : parts[i + 1] === '2' ? 4 : 0
+
       continue
     }
 
@@ -80,6 +81,7 @@ export function transitionAnsiCodes(from: AnsiCode[], to: AnsiCode[]): AnsiCode[
   for (const atom of fromAtoms) {
     if (!toAtoms.has(atom)) {
       removesWeight = true
+
       break
     }
   }
@@ -94,7 +96,10 @@ export function transitionAnsiCodes(from: AnsiCode[], to: AnsiCode[]): AnsiCode[
   // in full (a compound re-asserts its color too — redundant bytes, never
   // wrong). The rest of the style diffs normally with the weight carriers
   // stripped from both sides.
-  const rest = diffAnsiCodes(from.filter(code => !carriesWeight(code)), to.filter(code => !carriesWeight(code)))
+  const rest = diffAnsiCodes(
+    from.filter(code => !carriesWeight(code)),
+    to.filter(code => !carriesWeight(code))
+  )
 
   return [WEIGHT_RESET, ...rest, ...to.filter(carriesWeight)]
 }

From 00888e80acb7059c36646c304eccc4edcabce454 Mon Sep 17 00:00:00 2001
From: Teknium <127238744+teknium1@users.noreply.github.com>
Date: Wed, 19 Aug 2026 10:01:26 -0700
Subject: [PATCH 28/48] test: drop the upscale-defaults-off catalog invariant
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Grok Imagine Image 2.0 (ceabb030fb) intentionally ships upscale: True —
its 1k native output is sub-2MP. Per-entry defaults are a catalog
decision now; the blanket all-off invariant no longer reflects policy.
Per-call upscale=true/false override is unchanged.
---
 tests/tools/test_image_generation.py | 11 -----------
 1 file changed, 11 deletions(-)

diff --git a/tests/tools/test_image_generation.py b/tests/tools/test_image_generation.py
index f365cdd0ed..d5a7a65bfb 100644
--- a/tests/tools/test_image_generation.py
+++ b/tests/tools/test_image_generation.py
@@ -57,17 +57,6 @@ class TestFalCatalog:
             assert not missing, f"{mid} missing required keys: {missing}"
 
 
-    def test_upscale_defaults_are_all_off(self, image_tool):
-        """Upscaling is opt-in only (Aug 2026 policy). The default-on
-        experiment chained the Clarity Upscaler — a creative SD1.5
-        tile-diffusion enhancer — after every sub-2MP generation, which
-        degraded output quality (mangled GPT Image 2 / Ideogram text
-        rendering, CJK, faces). No catalog entry may default upscale on."""
-        for mid, meta in image_tool.FAL_MODELS.items():
-            assert meta["upscale"] is False, \
-                f"{mid} must not default upscale on — opt-in per call only"
-
-
     def test_edit_capable_entries_declare_a_full_edit_contract(self, image_tool):
         """An `edit_endpoint` is useless without the whitelist and the
         reference-image cap that `_build_fal_edit_payload` reads."""

From cd3f9b64dec90fa95a5d949867477f6a1094a0bf Mon Sep 17 00:00:00 2001
From: Noah Lee <opsdownn@gmail.com>
Date: Tue, 30 Jun 2026 14:37:50 +0900
Subject: [PATCH 29/48] feat(skills): add --yes/-y flag to hermes skills
 uninstall

`do_uninstall` already accepted a `skip_confirm` parameter and the
slash-command handler already passed `skip_confirm=True`, but the CLI
argparse path never exposed a flag to reach it. This adds `--yes`/`-y`
to `hermes skills uninstall`, matching the existing pattern on `install`
and `reset`.
---
 hermes_cli/skills_hub.py         | 2 +-
 hermes_cli/subcommands/skills.py | 6 ++++++
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/hermes_cli/skills_hub.py b/hermes_cli/skills_hub.py
index 295248f6fd..28fbf5d81f 100644
--- a/hermes_cli/skills_hub.py
+++ b/hermes_cli/skills_hub.py
@@ -1835,7 +1835,7 @@ def skills_command(args) -> None:
         do_audit(name=getattr(args, "name", None),
                  deep=getattr(args, "deep", False))
     elif action == "uninstall":
-        do_uninstall(args.name)
+        do_uninstall(args.name, skip_confirm=getattr(args, "yes", False))
     elif action == "reset":
         do_reset(args.name, restore=getattr(args, "restore", False),
                  skip_confirm=getattr(args, "yes", False))
diff --git a/hermes_cli/subcommands/skills.py b/hermes_cli/subcommands/skills.py
index 6c2aa85d22..cfcc677f18 100644
--- a/hermes_cli/subcommands/skills.py
+++ b/hermes_cli/subcommands/skills.py
@@ -182,6 +182,12 @@ def build_skills_parser(subparsers, *, cmd_skills: Callable) -> None:
         "uninstall", help="Remove a hub-installed skill"
     )
     skills_uninstall.add_argument("name", help="Skill name to remove")
+    skills_uninstall.add_argument(
+        "--yes",
+        "-y",
+        action="store_true",
+        help="Skip confirmation prompt",
+    )
 
     skills_reset = skills_subparsers.add_parser(
         "reset",

From 9551df12051383cf6fa8872558727a898fb5c181 Mon Sep 17 00:00:00 2001
From: Noah Lee <opsdownn@gmail.com>
Date: Fri, 7 Aug 2026 11:26:49 +0900
Subject: [PATCH 30/48] test(skills): add CLI regression tests for skills
 uninstall --yes/-y flag

Covers the new --yes/-y flag on , asserting the
parsed value reaches do_uninstall(skip_confirm=True) via the real
main() -> cmd_skills -> skills_command dispatch path. Mirrors the
install-flag test pattern in test_skills_install_flags.py.
---
 .../hermes_cli/test_skills_uninstall_flags.py | 58 +++++++++++++++++++
 1 file changed, 58 insertions(+)
 create mode 100644 tests/hermes_cli/test_skills_uninstall_flags.py

diff --git a/tests/hermes_cli/test_skills_uninstall_flags.py b/tests/hermes_cli/test_skills_uninstall_flags.py
new file mode 100644
index 0000000000..2fa615916b
--- /dev/null
+++ b/tests/hermes_cli/test_skills_uninstall_flags.py
@@ -0,0 +1,58 @@
+"""
+Tests for --yes / -y flag in `hermes skills uninstall` CLI subcommand.
+
+Verifies the parser registers the flag and the value reaches
+``do_uninstall(skip_confirm=True)`` through the real ``skills_command``
+dispatch path (mirrors ``test_skills_install_flags.py``).
+"""
+
+import sys
+
+
+def _run_uninstall_cli(monkeypatch, argv):
+    captured = {}
+
+    def fake_do_uninstall(name, *, skip_confirm=False, **kwargs):
+        captured["name"] = name
+        captured["skip_confirm"] = skip_confirm
+
+    monkeypatch.setattr("hermes_cli.skills_hub.do_uninstall", fake_do_uninstall)
+    monkeypatch.setattr(sys, "argv", argv)
+
+    from hermes_cli.main import main
+
+    main()
+    return captured
+
+
+def test_cli_skills_uninstall_yes_sets_skip_confirm(monkeypatch):
+    """`--yes` should propagate to do_uninstall(skip_confirm=True)."""
+    captured = _run_uninstall_cli(
+        monkeypatch,
+        ["hermes", "skills", "uninstall", "test-skill", "--yes"],
+    )
+
+    assert captured["name"] == "test-skill"
+    assert captured["skip_confirm"] is True
+
+
+def test_cli_skills_uninstall_y_alias_sets_skip_confirm(monkeypatch):
+    """`-y` should behave the same as `--yes`."""
+    captured = _run_uninstall_cli(
+        monkeypatch,
+        ["hermes", "skills", "uninstall", "test-skill", "-y"],
+    )
+
+    assert captured["name"] == "test-skill"
+    assert captured["skip_confirm"] is True
+
+
+def test_cli_skills_uninstall_no_flags_keeps_prompt(monkeypatch):
+    """Without --yes, skip_confirm must be False (prompt preserved)."""
+    captured = _run_uninstall_cli(
+        monkeypatch,
+        ["hermes", "skills", "uninstall", "test-skill"],
+    )
+
+    assert captured["name"] == "test-skill"
+    assert captured["skip_confirm"] is False
\ No newline at end of file

From bdc5b1f74c26e6240deb8f067ade6dc91c00e8f2 Mon Sep 17 00:00:00 2001
From: Teknium <127238744+teknium1@users.noreply.github.com>
Date: Wed, 19 Aug 2026 02:48:21 -0700
Subject: [PATCH 31/48] chore: map contributor email for noahingh

---
 contributors/emails/opsdownn@gmail.com | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 contributors/emails/opsdownn@gmail.com

diff --git a/contributors/emails/opsdownn@gmail.com b/contributors/emails/opsdownn@gmail.com
new file mode 100644
index 0000000000..e6a9ddbeef
--- /dev/null
+++ b/contributors/emails/opsdownn@gmail.com
@@ -0,0 +1 @@
+noahingh

From a45d854d7dbf9d53bbf28f3927a2dffbf45478a6 Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 19 Aug 2026 12:05:41 -0500
Subject: [PATCH 32/48] fix(docs): index every docs page in llms.txt, not a
 hand-picked 98
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The section list decided membership as well as order, so it drifted as the
docs grew: 109 of 204 pages were absent from the index every LLM reads to
learn what Hermes does — Bot Mode, the desktop app, computer use, web search,
skins, Mixture of Agents, and 22 messaging platforms among them.

Enumerate the docs tree instead. SECTIONS now curates only which pages lead a
section; anything it does not name is absorbed under its path, and a page
matching no section lands in "More" rather than falling out. This also picks
up the three .mdx pages the .md-only glob never saw, points section landing
pages at the directory URL Docusaurus actually serves, and drops a curated row
still aimed at a guide moved to developer-guide/plugins in #59613.

Tests hold both directions against the filesystem rather than the enumerator,
so a page cannot go missing and a link cannot point at a page that moved.
---
 tests/website/test_generate_llms_txt.py | 133 +++++++++++++++
 website/scripts/generate-llms-txt.py    | 214 ++++++++++++++++--------
 2 files changed, 280 insertions(+), 67 deletions(-)
 create mode 100644 tests/website/test_generate_llms_txt.py

diff --git a/tests/website/test_generate_llms_txt.py b/tests/website/test_generate_llms_txt.py
new file mode 100644
index 0000000000..738ba55a09
--- /dev/null
+++ b/tests/website/test_generate_llms_txt.py
@@ -0,0 +1,133 @@
+"""`llms.txt` is how an LLM learns what Hermes can do.
+
+It is the index every model reads when pointed at our docs — including Hermes
+itself, whose `hermes-agent` skill routes unknown-feature questions there.
+`website/` is never packaged, so there is no shipped copy to fall back on.
+
+The index used to be a hand-written list of page paths, and it rotted to 53%
+coverage: Bot Mode, the desktop app, computer use, web search, and 22 messaging
+platforms were all absent, which is why an agent asked how to make bots talk to
+each other answered that it couldn't. These tests hold the two directions of
+that contract — every page reachable, every link real — so the index tracks the
+docs tree instead of someone's memory of it.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import re
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+GENERATOR = REPO_ROOT / "website" / "scripts" / "generate-llms-txt.py"
+
+
+@pytest.fixture(scope="module")
+def gen():
+    spec = importlib.util.spec_from_file_location("generate_llms_txt", GENERATOR)
+    assert spec is not None and spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+@pytest.fixture(scope="module")
+def index(gen) -> str:
+    return gen.emit_llms_index()
+
+
+def _linked(gen, index: str) -> set[str]:
+    return set(re.findall(rf"\]\({re.escape(gen.SITE_BASE)}/([^)]+)\)", index))
+
+
+def _pages_on_disk(gen) -> set[str]:
+    """Walk the docs tree directly, duplicating only the two documented
+    exclusions.
+
+    Deliberately does not call `iter_docs()`: the index is built from that
+    enumeration, so checking one against the other would pass even if the
+    enumerator went blind to a whole tree — which is the failure being guarded.
+    """
+    pages = set()
+    for path in (*gen.DOCS.rglob("*.md"), *gen.DOCS.rglob("*.mdx")):
+        rel = path.relative_to(gen.DOCS).with_suffix("")
+        slug = str(rel.parent) if rel.name == "index" else str(rel)
+        # The docs landing page is the index's subject; per-skill pages are
+        # summarized by the two catalog reference pages.
+        if slug == "." or slug.startswith(("user-guide/skills/bundled", "user-guide/skills/optional")):
+            continue
+        pages.add(slug)
+    return pages
+
+
+def test_every_docs_page_is_indexed(gen, index):
+    """The regression: a page the index omits is a feature the agent denies."""
+    pages = _pages_on_disk(gen)
+    assert len(pages) > 100, "docs root resolved wrong — the rest of this file proves nothing"
+
+    missing = pages - _linked(gen, index)
+    assert not missing, (
+        f"{len(missing)} docs pages missing from llms.txt: {sorted(missing)} — "
+        "they should have been absorbed into a section automatically"
+    )
+
+
+def test_the_enumerator_sees_the_whole_docs_tree(gen):
+    """Everything downstream trusts `iter_docs()`, so pin it to the filesystem."""
+    assert set(gen.iter_docs()) == _pages_on_disk(gen)
+
+
+def test_every_indexed_page_exists(gen, index):
+    """The other direction: a renamed page leaves the index pointing at a 404."""
+    for slug in sorted(_linked(gen, index)):
+        assert gen.doc_path(slug) is not None, (
+            f"llms.txt links {slug}, which is not in the docs tree — "
+            "drop the SECTIONS row and let the page be absorbed under its new path"
+        )
+
+
+def test_pages_are_listed_once(gen, index):
+    """Curating a page must promote it, not duplicate it."""
+    entries = re.findall(rf"^- \[.*?\]\({re.escape(gen.SITE_BASE)}/([^)]+)\)", index, re.MULTILINE)
+    duplicated = {slug for slug in entries if entries.count(slug) > 1}
+    assert not duplicated, f"listed more than once in llms.txt: {sorted(duplicated)}"
+
+
+def test_curation_orders_pages_without_gatekeeping_them(gen):
+    """SECTIONS decides what leads a section, never what the index contains."""
+    curated = {slug for _section, items in gen.SECTIONS for slug, _t, _d in items}
+    pages = set(gen.iter_docs())
+
+    assert curated < pages, "every page is curated — absorption is no longer exercised"
+    assert gen.section_for("user-guide/features/some-feature-shipped-tomorrow") in dict(gen.ABSORB)
+    assert gen.section_for("a-tree-nobody-anticipated/page") == gen.MISC_SECTION
+
+
+def test_section_landing_pages_resolve_to_their_directory(gen):
+    """`messaging/index.md` is served at `/messaging`; `/messaging/index` 404s."""
+    assert gen.slug_for(gen.DOCS / "user-guide" / "messaging" / "index.md") == "user-guide/messaging"
+    assert "user-guide/messaging/index" not in _linked(gen, gen.emit_llms_index())
+
+
+def test_mdx_pages_are_indexed_without_their_imports(gen):
+    """MDX docs are real pages; their component imports are not prose."""
+    mdx = [p for p in gen.DOCS.rglob("*.mdx") if gen.slug_for(p)]
+    assert mdx, "no .mdx docs — this test no longer guards anything"
+    assert {gen.slug_for(p) for p in mdx} <= set(gen.iter_docs())
+
+    _meta, body = gen.read_frontmatter(mdx[0])
+    assert not re.search(r"^import\s", body, re.MULTILINE)
+
+
+def test_per_skill_catalog_pages_stay_out(gen):
+    """~195 generated skill pages would bury the product docs in the index."""
+    assert not [slug for slug in gen.iter_docs() if slug.startswith(gen.SKILL_CATALOG)]
+    assert "reference/skills-catalog" in gen.iter_docs(), "the summary page must remain"
+
+
+def test_bot_mode_is_reachable(gen, index):
+    """The page behind the original complaint, and the answer it has to carry."""
+    assert "user-guide/bot-mode" in _linked(gen, index)
+    assert "hermes peer dm" in (gen.DOCS / "user-guide" / "bot-mode.md").read_text(encoding="utf-8")
diff --git a/website/scripts/generate-llms-txt.py b/website/scripts/generate-llms-txt.py
index a34c57792a..91caeb4ad3 100644
--- a/website/scripts/generate-llms-txt.py
+++ b/website/scripts/generate-llms-txt.py
@@ -2,12 +2,20 @@
 """Generate llms.txt and llms-full.txt for the Hermes docs site.
 
 Outputs:
-  website/static/llms.txt        — short curated index of the docs, one link per page,
-                                    grouped by section. Conforms to https://llmstxt.org.
-  website/static/llms-full.txt   — every `.md` file under `website/docs/` concatenated,
+  website/static/llms.txt        — index of the docs, one link per page, grouped by
+                                    section. Conforms to https://llmstxt.org.
+  website/static/llms-full.txt   — every doc under `website/docs/` concatenated,
                                     with `# <title>` headings and `<!-- source: … -->`
                                     comments separating files.
 
+Both are driven by `iter_docs()`, which walks the docs tree. `SECTIONS` below
+curates *order and grouping*, never membership: a page nobody curated still
+gets indexed, under the section its path belongs to. That distinction is the
+reason this file was rewritten — when the section list also decided membership,
+it silently drifted to 53% coverage, and Bot Mode, the desktop app, computer
+use, web search, and 22 messaging platforms were absent from the index every
+LLM reads to learn what Hermes does.
+
 Both publish at:
   https://hermes-agent.nousresearch.com/docs/llms.txt
   https://hermes-agent.nousresearch.com/docs/llms-full.txt
@@ -33,9 +41,11 @@ STATIC = WEBSITE / "static"
 
 SITE_BASE = "https://hermes-agent.nousresearch.com/docs"
 
-# Curated sections for llms.txt — mirrors the product story, not the filesystem.
-# Each entry: (docs-relative path without .md, display title, optional short desc).
-# `None` desc → pulled from frontmatter `description:` field.
+# The product story: which pages lead, and in what order. Everything not named
+# here is still indexed — ABSORB decides where it lands — so this list is safe
+# to leave alone as the docs grow, and worth editing only to promote a page.
+# Each entry: (docs-relative path without extension, display title, optional
+# short desc). `None` desc → pulled from frontmatter `description:` field.
 SECTIONS: list[tuple[str, list[tuple[str, str, str | None]]]] = [
     ("Getting Started", [
         ("getting-started/installation", "Installation", None),
@@ -88,7 +98,7 @@ SECTIONS: list[tuple[str, list[tuple[str, str, str | None]]]] = [
         ("user-guide/features/tts", "Text-to-Speech", None),
     ]),
     ("Messaging Platforms", [
-        ("user-guide/messaging/index", "Overview", None),
+        ("user-guide/messaging", "Overview", None),
         ("user-guide/messaging/telegram", "Telegram", None),
         ("user-guide/messaging/discord", "Discord", None),
         ("user-guide/messaging/slack", "Slack", None),
@@ -102,7 +112,7 @@ SECTIONS: list[tuple[str, list[tuple[str, str, str | None]]]] = [
         ("user-guide/messaging/webhooks", "Webhooks", None),
     ]),
     ("Integrations", [
-        ("integrations/index", "Integrations Overview", None),
+        ("integrations", "Integrations Overview", None),
         ("integrations/providers", "Providers", None),
         ("user-guide/features/mcp", "MCP (Model Context Protocol)", None),
         ("user-guide/features/acp", "ACP (Agent Context Protocol)", None),
@@ -121,7 +131,6 @@ SECTIONS: list[tuple[str, list[tuple[str, str, str | None]]]] = [
         ("guides/use-mcp-with-hermes", "Use MCP with Hermes", None),
         ("guides/use-voice-mode-with-hermes", "Use Voice Mode with Hermes", None),
         ("guides/use-soul-with-hermes", "Use SOUL.md with Hermes", None),
-        ("guides/build-a-hermes-plugin", "Build a Hermes Plugin", None),
         ("guides/automate-with-cron", "Automate with Cron", None),
         ("guides/work-with-skills", "Work with Skills", None),
         ("guides/delegation-patterns", "Delegation Patterns", None),
@@ -158,9 +167,40 @@ SECTIONS: list[tuple[str, list[tuple[str, str, str | None]]]] = [
 ]
 
 
+DOC_EXTS = (".md", ".mdx")
+
+# Per-skill pages are generated from the skill tree and summarized by the two
+# catalog reference pages. Listing ~195 of them would bury the product docs in
+# the index and add ~1.4 MB of duplicative material to llms-full.txt.
+SKILL_CATALOG = ("user-guide/skills/bundled", "user-guide/skills/optional")
+
+# Where a page nobody curated goes. First match wins, so a narrower prefix must
+# precede the tree containing it. Anything matching nothing lands in
+# MISC_SECTION — no path can drop a page out of the index.
+ABSORB: tuple[tuple[str, tuple[str, ...]], ...] = (
+    ("Getting Started", ("getting-started",)),
+    ("Messaging Platforms", ("user-guide/messaging",)),
+    ("Core Features", ("user-guide/features",)),
+    ("Using Hermes", ("user-guide",)),
+    ("Integrations", ("integrations",)),
+    ("Guides & Tutorials", ("guides",)),
+    ("Developer Guide", ("developer-guide",)),
+    ("Reference", ("reference",)),
+)
+MISC_SECTION = "More"
+
 FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---\s*\n", re.DOTALL)
-DESC_RE = re.compile(r"^description:\s*[\"'](.+?)[\"']\s*$", re.MULTILINE)
-TITLE_RE = re.compile(r"^title:\s*[\"'](.+?)[\"']\s*$", re.MULTILINE)
+DESC_RE = re.compile(r"^description:\s*(.+?)\s*$", re.MULTILINE)
+TITLE_RE = re.compile(r"^title:\s*(.+?)\s*$", re.MULTILINE)
+H1_RE = re.compile(r"^#\s+(.+?)\s*$", re.MULTILINE)
+# MDX pages open with component imports — markup plumbing, not prose.
+MDX_IMPORT_RE = re.compile(r"^(?:import|export)\s.*$\n?", re.MULTILINE)
+
+
+def _unquote(value: str) -> str:
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
+        return value[1:-1]
+    return value
 
 
 def read_frontmatter(path: Path) -> tuple[dict[str, str], str]:
@@ -172,30 +212,86 @@ def read_frontmatter(path: Path) -> tuple[dict[str, str], str]:
     if m:
         fm = m.group(1)
         body = text[m.end():]
-        dm = DESC_RE.search(fm)
-        if dm:
-            meta["description"] = dm.group(1)
-        tm = TITLE_RE.search(fm)
-        if tm:
-            meta["title"] = tm.group(1)
+        for key, pattern in (("description", DESC_RE), ("title", TITLE_RE)):
+            found = pattern.search(fm)
+            if found:
+                meta[key] = _unquote(found.group(1))
+    if path.suffix == ".mdx":
+        body = MDX_IMPORT_RE.sub("", body)
     return meta, body
 
 
+def slug_for(path: Path) -> str:
+    """URL slug for a page: `user-guide/messaging/index.md` → `user-guide/messaging`."""
+    rel = path.relative_to(DOCS).with_suffix("")
+    if rel.name == "index":
+        rel = rel.parent
+    return "" if str(rel) == "." else str(rel)
+
+
+def doc_path(slug: str) -> Path | None:
+    """The file backing a slug, whether it's a page or a section landing page."""
+    for ext in DOC_EXTS:
+        for candidate in (DOCS / f"{slug}{ext}", DOCS / slug / f"index{ext}"):
+            if candidate.exists():
+                return candidate
+    return None
+
+
+def iter_docs() -> list[str]:
+    """Every indexable page, as a slug — the one enumeration of the docs tree.
+
+    llms.txt lists exactly these and llms-full.txt emits exactly these, so a
+    page on disk cannot be missing from either output.
+    """
+    slugs = set()
+    for ext in DOC_EXTS:
+        for path in DOCS.rglob(f"*{ext}"):
+            slug = slug_for(path)
+            # The docs landing page is this index's subject, not an entry in it.
+            if slug and not slug.startswith(SKILL_CATALOG):
+                slugs.add(slug)
+    return sorted(slugs)
+
+
+def section_for(slug: str) -> str:
+    for section, prefixes in ABSORB:
+        if any(slug == prefix or slug.startswith(f"{prefix}/") for prefix in prefixes):
+            return section
+    return MISC_SECTION
+
+
+def resolve_meta(slug: str) -> tuple[str, str]:
+    """(title, description) for a page, falling back to its H1 then its slug."""
+    path = doc_path(slug)
+    if path is None:
+        return slug, ""
+    meta, body = read_frontmatter(path)
+    title = meta.get("title")
+    if not title:
+        h1 = H1_RE.search(body)
+        title = h1.group(1) if h1 else slug.rsplit("/", 1)[-1].replace("-", " ").title()
+    return title, meta.get("description", "")
+
+
 def resolve_desc(slug: str, provided: str | None) -> str:
     """Resolve short description for llms.txt entry."""
-    if provided:
-        return provided
-    path = DOCS / f"{slug}.md"
-    if not path.exists():
-        path = DOCS / slug / "index.md"
-    if not path.exists():
-        return ""
-    meta, _ = read_frontmatter(path)
-    return meta.get("description", "")
+    return provided or resolve_meta(slug)[1]
+
+
+def _entry(slug: str, title: str, desc: str) -> str:
+    url = f"{SITE_BASE}/{slug}"
+    return f"- [{title}]({url}): {desc}" if desc else f"- [{title}]({url})"
 
 
 def emit_llms_index() -> str:
-    """Build the short llms.txt index."""
+    """Build the llms.txt index: curated pages lead a section, the rest follow."""
+    curated = {slug for _section, items in SECTIONS for slug, _title, _desc in items}
+    absorbed: dict[str, list[str]] = {}
+    for slug in iter_docs():
+        if slug not in curated:
+            absorbed.setdefault(section_for(slug), []).append(slug)
+
     lines: list[str] = []
     lines.append("# Hermes Agent")
     lines.append("")
@@ -222,23 +318,24 @@ def emit_llms_index() -> str:
         lines.append(f"## {section}")
         lines.append("")
         for slug, title, desc_override in items:
-            desc = resolve_desc(slug, desc_override)
-            url = f"{SITE_BASE}/{slug}"
-            if desc:
-                lines.append(f"- [{title}]({url}): {desc}")
-            else:
-                lines.append(f"- [{title}]({url})")
+            lines.append(_entry(slug, title, resolve_desc(slug, desc_override)))
+        for slug in absorbed.pop(section, []):
+            lines.append(_entry(slug, *resolve_meta(slug)))
+        lines.append("")
+
+    # Only MISC_SECTION can survive the pops — a page whose path matched no
+    # section still has to appear somewhere.
+    for section, slugs in absorbed.items():
+        lines.append(f"## {section}")
+        lines.append("")
+        for slug in slugs:
+            lines.append(_entry(slug, *resolve_meta(slug)))
         lines.append("")
     return "\n".join(lines).rstrip() + "\n"
 
 
 def emit_llms_full() -> str:
-    """Concatenate every doc under website/docs/ into a single markdown file.
-
-    Order: mirrors the curated SECTIONS list first (so the most important
-    pages are front-loaded for agents that truncate on token budget), then
-    appends any remaining .md files sorted by path.
-    """
+    """Concatenate every doc under website/docs/ into a single markdown file."""
     seen: set[Path] = set()
     chunks: list[str] = [
         "# Hermes Agent — Full Documentation\n",
@@ -253,41 +350,24 @@ def emit_llms_full() -> str:
         "\n---\n\n",
     ]
 
-    def emit_file(rel: str) -> None:
-        path = DOCS / f"{rel}.md"
-        if not path.exists():
-            path = DOCS / rel / "index.md"
-        if not path.exists() or path in seen:
+    def emit_file(slug: str) -> None:
+        path = doc_path(slug)
+        if path is None or path in seen:
             return
         seen.add(path)
-        meta, body = read_frontmatter(path)
-        title = meta.get("title") or rel
+        title, _desc = resolve_meta(slug)
+        _meta, body = read_frontmatter(path)
         chunks.append(f"<!-- source: website/docs/{path.relative_to(DOCS)} -->\n")
         chunks.append(f"# {title}\n\n")
         chunks.append(body.rstrip() + "\n\n---\n\n")
 
-    # Curated order first
-    for _, items in SECTIONS:
-        for slug, _t, _d in items:
+    # Curated order first, so a reader truncating on token budget keeps the
+    # pages that matter most; then everything else the docs tree holds.
+    for _section, items in SECTIONS:
+        for slug, _title, _desc in items:
             emit_file(slug)
-
-    # Everything else (sorted, skipping already emitted and auto-gen skill pages
-    # — those are covered by the two catalog reference pages, emitting every
-    # individual skill would add ~1.4 MB of largely duplicative material).
-    for path in sorted(DOCS.rglob("*.md")):
-        if path in seen:
-            continue
-        rel = path.relative_to(DOCS)
-        parts = rel.parts
-        if len(parts) >= 3 and parts[0] == "user-guide" and parts[1] == "skills" \
-                and parts[2] in {"bundled", "optional"}:
-            continue
-        seen.add(path)
-        meta, body = read_frontmatter(path)
-        title = meta.get("title") or str(rel)
-        chunks.append(f"<!-- source: website/docs/{rel} -->\n")
-        chunks.append(f"# {title}\n\n")
-        chunks.append(body.rstrip() + "\n\n---\n\n")
+    for slug in iter_docs():
+        emit_file(slug)
 
     return "".join(chunks).rstrip() + "\n"
 

From dc8481b78bb6c1f92c75ce62294d9a0f224200c8 Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 19 Aug 2026 12:05:41 -0500
Subject: [PATCH 33/48] feat(skill): route hermes-agent's unknown-feature
 questions to llms.txt
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The routing table listed 18 topics and had nothing to say about the rest of
the product, so an agent asked how to get bots to talk to each other answered
that it could not — while user-guide/bot-mode documented four ways to do it.

Point the catch-all at the published index, which is generated from the docs
tree on every build and so cannot fall behind the feature set. website/ is
never packaged, so the URL is the only complete self-knowledge a running
Hermes has; curl covers sessions where the web tools are disabled.
---
 .../hermes-agent/SKILL.md                     | 17 +++--
 tests/skills/test_hermes_agent_skill.py       | 69 +++++++++++++++++++
 2 files changed, 82 insertions(+), 4 deletions(-)
 create mode 100644 tests/skills/test_hermes_agent_skill.py

diff --git a/skills/autonomous-ai-agents/hermes-agent/SKILL.md b/skills/autonomous-ai-agents/hermes-agent/SKILL.md
index 42edf68cc4..7b4565825f 100644
--- a/skills/autonomous-ai-agents/hermes-agent/SKILL.md
+++ b/skills/autonomous-ai-agents/hermes-agent/SKILL.md
@@ -1,13 +1,13 @@
 ---
 name: hermes-agent
 description: "Use, configure, theme, extend, and orchestrate Hermes Agent."
-version: 3.1.0
+version: 3.2.0
 author: Hermes Agent + Teknium
 license: MIT
 platforms: [linux, macos, windows]
 metadata:
   hermes:
-    tags: [hermes, setup, configuration, multi-agent, spawning, cli, gateway, themes, skins, desktop-plugins, tui-widgets, petdex, development]
+    tags: [hermes, setup, configuration, multi-agent, spawning, cli, gateway, bots, bot-mode, features, themes, skins, desktop-plugins, tui-widgets, petdex, development]
     homepage: https://github.com/NousResearch/hermes-agent
     related_skills: [claude-code, codex, opencode]
 ---
@@ -34,12 +34,14 @@ What makes Hermes different:
 
 This skill is a concise operating guide, not the complete source of truth for every Hermes feature. If a Hermes feature, command, or setting is not mentioned here or in a reference, do not treat that absence as evidence that it does not exist. Check the live repository and official docs before giving a negative answer.
 
-Good verification targets:
+Good verification targets, cheapest first:
 
+- **Every shipped feature, one line each: https://hermes-agent.nousresearch.com/docs/llms.txt.** Start here for any "can Hermes do X?" or "how do I do X?" — it indexes the entire documentation set with a link to the page that answers. It is generated from the docs tree on every build, so it is never behind the product. Fetch it with `web_extract`, or `curl -s https://hermes-agent.nousresearch.com/docs/llms.txt` when web tools are off. The whole documentation set in one file is at `/docs/llms-full.txt`.
 - CLI commands: `hermes --help`, `hermes <command> --help`, and `hermes_cli/main.py`
-- User documentation: https://hermes-agent.nousresearch.com/docs/
 - Source tree: https://github.com/NousResearch/hermes-agent
 
+Never answer "Hermes can't do that" from memory. Hermes ships far more than this skill body describes, and the index exists so a negative answer is always checkable.
+
 ## Quick Start
 
 ```bash
@@ -86,6 +88,8 @@ Profiles use `~/.hermes/profiles/<name>/` with the same layout. When a profile i
 
 | User wants... | Load |
 |---|---|
+| **Anything not listed below — "can Hermes do X?", "how do I set up X?"** | **https://hermes-agent.nousresearch.com/docs/llms.txt** |
+| Bots that chat, run routines, or message each other; the Bots tab | docs: `/user-guide/bot-mode` |
 | CLI commands, subcommands, flags, "how do I run X" | `references/cli-reference.md` |
 | In-session slash commands | `references/slash-commands.md` |
 | Provider setup, API keys, OAuth | `references/providers-and-models.md` |
@@ -104,6 +108,11 @@ Profiles use `~/.hermes/profiles/<name>/` with the same layout. When a profile i
 | Contributing code: adding tools, slash commands, tests | `references/contributor-guide.md` |
 | delegate_task "capped at N" reports | `references/delegate-task-concurrency-diagnosis.md` |
 | "Can app X use my Nous Portal subscription/OAuth?" | `references/portal-auth-for-third-party-apps.md` |
+| Connecting a messaging platform (Telegram, Discord, Slack, WhatsApp, …) | docs: `/user-guide/messaging` |
+
+The reference list above is not the feature list — it is the set of topics that
+need more than their docs page. For everything else Hermes ships, fetch
+`llms.txt` and it maps the question to the page that answers it.
 
 Two theming rules that hold even without loading the reference: **you apply skins yourself** (`hermes config set display.skin <name>` — every surface repaints live within ~a second; don't tell the user to run `/skin`), and **to tweak one color, edit the ACTIVE skin** (`hermes skin set <key> <hex>`) — never fork `default`, which drops the palette and resets the background.
 
diff --git a/tests/skills/test_hermes_agent_skill.py b/tests/skills/test_hermes_agent_skill.py
new file mode 100644
index 0000000000..a98910a996
--- /dev/null
+++ b/tests/skills/test_hermes_agent_skill.py
@@ -0,0 +1,69 @@
+"""The `hermes-agent` skill is what a running Hermes knows about itself.
+
+`website/` is never packaged, so an installed Hermes has no local copy of the
+user guide; skills ARE synced into `$HERMES_HOME/skills/`. The skill therefore
+does not try to restate the product — it routes to the published `llms.txt`,
+which is generated from the docs tree on every build and so can never be behind
+the feature set. These tests keep that routing honest: the index has to be where
+the skill says it is, and every reference has to be reachable, otherwise a
+shipped feature is invisible and the agent answers "Hermes can't do that."
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import re
+from pathlib import Path
+
+import pytest
+
+REPO = Path(__file__).resolve().parents[2]
+SKILL_DIR = REPO / "skills" / "autonomous-ai-agents" / "hermes-agent"
+SKILL_MD = SKILL_DIR / "SKILL.md"
+GENERATOR = REPO / "website" / "scripts" / "generate-llms-txt.py"
+
+
+@pytest.fixture(scope="module")
+def skill_text() -> str:
+    return SKILL_MD.read_text(encoding="utf-8")
+
+
+def test_every_referenced_file_exists(skill_text):
+    """Routing a question to a file that isn't there is a dead end."""
+    targets = set(re.findall(r"`((?:references|templates)/[^`]+)`", skill_text))
+
+    assert targets, "the skill's routing table no longer references any files"
+    for target in sorted(targets):
+        assert (SKILL_DIR / target).exists(), f"SKILL.md routes to missing {target}"
+
+
+def test_every_reference_is_reachable_from_the_skill(skill_text):
+    """An unrouted reference is one the agent will never think to open.
+
+    This is the failure that produced the original complaint: content can exist
+    and still be invisible because nothing points at it.
+    """
+    on_disk = {f"references/{path.name}" for path in (SKILL_DIR / "references").glob("*.md")}
+    routed = set(re.findall(r"`(references/[^`]+)`", skill_text))
+
+    assert not (on_disk - routed), (
+        f"reference files no reader will ever reach: {sorted(on_disk - routed)} — "
+        "add a routing-table row in SKILL.md"
+    )
+
+
+def test_unknown_features_route_to_the_published_index(skill_text):
+    """The catch-all is what makes coverage of the whole product possible."""
+    assert "/docs/llms.txt" in skill_text
+    # web_extract can be disabled; terminal never is.
+    assert "curl" in skill_text, "no way to reach the index without web tools"
+
+
+def test_the_index_is_published_where_the_skill_says_it_is(skill_text):
+    """A skill pointing at a URL nobody generates is worse than no routing."""
+    spec = importlib.util.spec_from_file_location("generate_llms_txt", GENERATOR)
+    assert spec is not None and spec.loader is not None
+    gen = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(gen)
+
+    assert f"{gen.SITE_BASE}/llms.txt" in skill_text

From 3a034356a237341452b7afebd3a2bfd21021609f Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 19 Aug 2026 12:05:41 -0500
Subject: [PATCH 34/48] ci: run the Python lane for docs and website script
 changes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

llms.txt coverage is asserted in Python, but website/ sat on the Python skip
list, so a PR adding a docs page — or regressing the generator — went green
without ever running the test that checks the page is reachable. That is how
the index drifted to 53% coverage unnoticed.
---
 scripts/ci/classify_changes.py    | 14 +++++++++++++-
 tests/ci/test_classify_changes.py | 19 +++++++++++++++++--
 2 files changed, 30 insertions(+), 3 deletions(-)

diff --git a/scripts/ci/classify_changes.py b/scripts/ci/classify_changes.py
index 3a3e268423..db79da5c7b 100644
--- a/scripts/ci/classify_changes.py
+++ b/scripts/ci/classify_changes.py
@@ -45,6 +45,9 @@ must never skip one a change could break:
 * ``website/static/oauth/`` is python-relevant too: it publishes the OAuth
   Client ID Metadata Document that ``tests/tools/test_mcp_cimd.py`` checks
   against the pinned callback ports in ``tools/mcp_oauth.py``.
+* ``website/docs/`` and ``website/scripts/`` are python-relevant for the same
+  reason: the docs tree generates ``llms.txt``, and
+  ``tests/website/test_generate_llms_txt.py`` asserts every page reaches it.
 """
 
 from __future__ import annotations
@@ -66,7 +69,16 @@ _PY_SKIP = ("docs/", "website/") + _FRONTEND
 # callback ports in tools/mcp_oauth.py, so editing it alone must still run the
 # Python lane — otherwise dropping a redirect URI goes green here and breaks
 # every CIMD login on main.
-_PY_RELEVANT_SITE = ("website/static/oauth/",)
+# website/docs/ and website/scripts/ are asserted about the same way. The docs
+# tree generates llms.txt — the index every LLM (Hermes included, via the
+# hermes-agent skill) reads to learn what Hermes can do — and
+# tests/website/test_generate_llms_txt.py holds every page to appearing in it.
+# Skipping Python on a docs-only PR is how the index drifted to 53% coverage.
+_PY_RELEVANT_SITE = (
+    "website/static/oauth/",
+    "website/docs/",
+    "website/scripts/",
+)
 
 # CI-sensitive files: eslint config, workflow files, composite actions.
 # Changes here can influence what code the autofix job executes and pushes to
diff --git a/tests/ci/test_classify_changes.py b/tests/ci/test_classify_changes.py
index 3a33f576f7..56fe3a7ad5 100644
--- a/tests/ci/test_classify_changes.py
+++ b/tests/ci/test_classify_changes.py
@@ -76,11 +76,15 @@ CASES = {
     # Lockfile bump shifts every TS package's tree, but not the Python suite.
     "root lockfile → frontend, not python": (["package-lock.json"], _lanes(frontend=True, npm_lock=True)),
     "nested lockfile → npm_lock": (["website/package-lock.json"], _lanes(site=True, npm_lock=True)),
-    "website → site": (["website/docs/intro.md"], _lanes(site=True)),
+    # A website file the Python suite cannot read stays site-only.
+    "website config → site": (["website/docusaurus.config.ts"], _lanes(site=True)),
     # uv lock --check re-resolves against PyPI, so it must stay off for any
     # diff that can't desync the lockfile — a registry blip on a docs PR
     # otherwise shows up as a blocking "uv.lock out of sync" red X.
-    "docs → no uv_lock": (["website/docs/user-guide/profiles.md"], _lanes(site=True)),
+    "docs → no uv_lock": (
+        ["website/docs/developer-guide/plugins/index.md"],
+        _lanes(python=True, site=True),
+    ),
     "frontend → no uv_lock": (["apps/desktop/src/store/profile.ts"], _lanes(frontend=True)),
     # The published CIMD document is asserted about by the Python suite, so a
     # lone edit there must not skip the lane that would catch a bad edit.
@@ -88,6 +92,17 @@ CASES = {
         ["website/static/oauth/client-metadata.json"],
         _lanes(python=True, site=True),
     ),
+    # A new docs page must reach llms.txt, and the generator that puts it there
+    # has its own tests. Skipping Python on either is how the index drifted to
+    # 53% coverage while every PR stayed green.
+    "docs page → python + site": (
+        ["website/docs/user-guide/bot-mode.md"],
+        _lanes(python=True, site=True),
+    ),
+    "docs generator → python + site": (
+        ["website/scripts/generate-llms-txt.py"],
+        _lanes(python=True, scan=True, site=True),
+    ),
     # SKILL.md reads like docs, but the skill-doc tests read skills/, so a
     # skill edit must still run Python.
     "skill md → python + site": (["skills/github/SKILL.md"], _lanes(python=True, site=True)),

From 107531549a76238ce8bf51f280b0d7ade81bcf83 Mon Sep 17 00:00:00 2001
From: Gille <4317663+helix4u@users.noreply.github.com>
Date: Mon, 17 Aug 2026 17:53:43 -0600
Subject: [PATCH 35/48] fix(update): show live Desktop update progress

---
 scripts/desktop-update/ui.html                | 25 +++--
 scripts/desktop-update/windows.ps1            | 93 ++++++++++++++++---
 tests/test_desktop_update_windows_progress.py | 87 +++++++++++++++++
 3 files changed, 184 insertions(+), 21 deletions(-)
 create mode 100644 tests/test_desktop_update_windows_progress.py

diff --git a/scripts/desktop-update/ui.html b/scripts/desktop-update/ui.html
index 0009a98e52..2b36bf6403 100644
--- a/scripts/desktop-update/ui.html
+++ b/scripts/desktop-update/ui.html
@@ -3,8 +3,8 @@
   Quiet shim page for the desktop update hand-off (Windows + POSIX).
 
   Served over loopback by the orchestrator (windows.ps1 / posix.sh) into a
-  chromeless browser app window. Pure veneer: polls /progress for `done` or
-  `error` and reacts; owns nothing (relaunch, result file, marker hygiene
+  chromeless browser app window. Pure veneer: polls /progress for the current
+  hand-off stage or a terminal event and reacts; owns nothing (relaunch, result file, marker hygiene
   all live in the orchestrator, which runs identically with no UI at all).
 
   The visual is PR #75895's update hand-off screen, ported verbatim:
@@ -12,8 +12,8 @@
     apps/bootstrap-installer/src/components/loader.tsx (itself lifted from
     apps/desktop/src/components/ui/loader.tsx 'fourier-flow'). Keep the
     constants in sync if the desktop's curve is retuned.
-  - Layout: loader (size-20) + one title + one muted line. No progress bar,
-    no stage list, no log pane, no cancel (see #75895 for the arguments).
+  - Layout: loader (size-20) + one title + one muted stage/elapsed line. No
+    progress bar, stage list, log pane, or cancel (see #75895 for the arguments).
   - Appearance follows the OS. Dark seeds are the installer's neutral
     charcoal (#232323 base, foreground #d6d6d6) — never brand blue.
 -->
@@ -104,7 +104,7 @@
     <div id="loader" role="status" aria-label="Updating"></div>
     <div id="glyph"></div>
     <h2 id="title">Updating Hermes</h2>
-    <p id="line">Hermes will open once done.</p>
+    <p id="line">Preparing update<br>0s elapsed</p>
   </div>
 <script>
   /* ── Fourier Flow loader, ported verbatim from loader.tsx ─────────────── */
@@ -195,10 +195,11 @@
 
   render(performance.now())
 
-  /* ── Event listener: done | error, nothing else ───────────────────────── */
+  /* ── Event listener: running stage or terminal outcome ───────────────── */
   const titleEl = document.getElementById('title')
   const lineEl = document.getElementById('line')
   const glyphEl = document.getElementById('glyph')
+  const clientStartedAt = Date.now()
   let settled = false
 
   function settle(state) {
@@ -209,7 +210,17 @@
 
   function apply(state) {
     if (settled) return
-    if (state.status === 'done') {
+    if (state.status === 'running') {
+      const reported = Number(state.elapsed_seconds)
+      const elapsed = Number.isFinite(reported) && reported >= 0
+        ? Math.floor(reported)
+        : Math.floor((Date.now() - clientStartedAt) / 1000)
+      const elapsedText = elapsed < 60
+        ? `${elapsed}s elapsed`
+        : `${Math.floor(elapsed / 60)}m ${elapsed % 60}s elapsed`
+      lineEl.textContent = `${state.message || 'Updating Hermes'}\n${elapsedText}`
+      lineEl.style.whiteSpace = 'pre-line'
+    } else if (state.status === 'done') {
       settle('done')
       glyphEl.textContent = '\u2713'
       lineEl.textContent = 'Opening Hermes\u2026'
diff --git a/scripts/desktop-update/windows.ps1 b/scripts/desktop-update/windows.ps1
index 247ca6cf5b..ad3db7e7ea 100644
--- a/scripts/desktop-update/windows.ps1
+++ b/scripts/desktop-update/windows.ps1
@@ -83,6 +83,8 @@ $LogDir = Join-Path $HermesHome "logs"
 $LogPath = Join-Path $LogDir "desktop-update-handoff.log"
 $ResultPath = Join-Path $HermesHome ".hermes-update-result.json"
 $script:Ui = $null
+$script:UiStage = "Preparing update"
+$script:UiStopwatch = [System.Diagnostics.Stopwatch]::StartNew()
 
 function Write-HandoffLog([string]$Message) {
     $line = "{0:yyyy-MM-ddTHH:mm:ssK} {1}" -f (Get-Date), $Message
@@ -93,15 +95,16 @@ function Write-HandoffLog([string]$Message) {
 # ── The shim: repo-owned HTML in a chromeless Edge app window ──────────────
 # The window is a veneer, not a participant: the update runs identically with
 # or without it (Edge missing/failed degrades to the WinForms card below,
-# then log-only). It streams nothing and knows nothing — it polls /progress
-# for one of two events, `done` or `error`, and reacts. The loopback listener
+# then log-only). It never consumes child output; it polls /progress for the
+# current hand-off stage or a terminal event and reacts. The loopback listener
 # is not a web server in any meaningful sense; it exists because file:// pages
 # cannot receive events from a detached process. Salvaged from the web-shell
 # spike (Co-authored-by: teknium1), reshaped to the quiet update-surface
 # contract (#75895/#83634): loader, one title, one line, no dashboard.
 $script:UiState = [hashtable]::Synchronized(@{
-    status  = "running"      # running | done | error
-    message = ""
+    status     = "running"      # running | done | manual | error
+    message    = $script:UiStage
+    clock      = $script:UiStopwatch
 })
 $script:UiServer = $null     # @{ Listener; Runspace; PowerShell; Port; EdgeProc }
 
@@ -158,9 +161,11 @@ function Start-UiServer([string]$HtmlPath) {
                     # Drain headers so the client doesn't see a reset mid-send.
                     while ($true) { $h = $reader.ReadLine(); if ($null -eq $h -or $h -eq "") { break } }
                     if ($request -match "^GET /progress") {
+                        $elapsed = [Math]::Floor($State.clock.Elapsed.TotalSeconds)
                         $snapshot = @{
-                            status  = $State.status
-                            message = $State.message
+                            status          = $State.status
+                            message         = $State.message
+                            elapsed_seconds = $elapsed
                         } | ConvertTo-Json -Compress
                         Send-Response $stream "200 OK" "application/json; charset=utf-8" ([System.Text.Encoding]::UTF8.GetBytes($snapshot))
                     } elseif ($request -match "^GET / ") {
@@ -210,9 +215,36 @@ function Publish-UiEvent([string]$Status, [string]$Message) {
     if ($script:UiServer) { Start-Sleep -Milliseconds 900 }
 }
 
+function Get-UiElapsedText {
+    $elapsed = [Math]::Floor($script:UiStopwatch.Elapsed.TotalSeconds)
+    if ($elapsed -lt 60) { return "${elapsed}s elapsed" }
+    $minutes = [Math]::Floor($elapsed / 60)
+    $seconds = $elapsed % 60
+    return "${minutes}m ${seconds}s elapsed"
+}
+
+function Get-UiProgressLine {
+    return "$script:UiStage`r`n$(Get-UiElapsedText)"
+}
+
+function Publish-UiProgress([string]$Message) {
+    # Stages come from the orchestrator's own control flow. Child stdout and
+    # stderr remain asynchronously drained in Invoke-HermesStep and are never
+    # read or parsed for UI updates.
+    $script:UiStage = $Message
+    $script:UiState.message = $Message
+    $script:UiState.status = "running"
+    if ($script:Ui) {
+        try {
+            $script:Ui.Sub.Text = Get-UiProgressLine
+            [System.Windows.Forms.Application]::DoEvents()
+        } catch {}
+    }
+}
+
 # ── Fallback card (no Edge / no HTML): same shape in WinForms ──────────────
-# Matches the shim pixel-for-pixel in spirit -- loader, one title, one static
-# line, OS light/dark -- so degrading is invisible to the user.
+# Matches the shim pixel-for-pixel in spirit -- loader, one title, one live
+# stage/elapsed line, OS light/dark -- so degrading is invisible to the user.
 function Get-AppsUseLightTheme {
     try {
         $v = Get-ItemProperty -Path "HKCU:\Software\Microsoft\Windows\CurrentVersion\Themes\Personalize" -Name AppsUseLightTheme -ErrorAction Stop
@@ -291,7 +323,7 @@ function Show-ProgressWindow {
         $title.TextAlign = "MiddleCenter"
         $title.SetBounds(16, 156, 248, 28)
         $sub = New-Object System.Windows.Forms.Label
-        $sub.Text = "Hermes will open once done."
+        $sub.Text = Get-UiProgressLine
         $sub.Font = New-Object System.Drawing.Font("Segoe UI", 9)
         $sub.ForeColor = $mute
         $sub.TextAlign = "TopCenter"
@@ -309,7 +341,16 @@ function Show-ProgressWindow {
             if ($script:Win32) { [HermesHandoff.Win32]::SetForegroundWindow($form.Handle) | Out-Null }
         } catch {}
         [System.Windows.Forms.Application]::DoEvents()
-        $script:Ui = [pscustomobject]@{ Form = $form; Bar = $bar; Title = $title; Sub = $sub }
+        $script:Ui = [pscustomobject]@{ Form = $form; Bar = $bar; Title = $title; Sub = $sub; Timer = $null }
+        $timer = New-Object System.Windows.Forms.Timer
+        $timer.Interval = 1000
+        $timer.Add_Tick({
+            if ($script:Ui -and $script:Ui.Sub) {
+                $script:Ui.Sub.Text = Get-UiProgressLine
+            }
+        })
+        $script:Ui.Timer = $timer
+        $timer.Start()
     } catch {
         # Headless session / WinForms unavailable: degrade to log-only.
         $script:Ui = $null
@@ -331,6 +372,7 @@ function Show-ErrorFinale([string]$Message) {
     if (-not $script:Ui) { return }
     try {
         $ui = $script:Ui
+        if ($ui.Timer) { $ui.Timer.Stop() }
         $ui.Bar.Visible = $false
         $ui.Title.Text = "Failed to update"
         $ui.Sub.Text = "Run `"hermes debug share`" in a terminal to send a report."
@@ -372,6 +414,7 @@ function Show-ManualFinale([string]$Message) {
     if (-not $script:Ui) { return }
     try {
         $ui = $script:Ui
+        if ($ui.Timer) { $ui.Timer.Stop() }
         $ui.Bar.Visible = $false
         $ui.Title.Text = "Update complete"
         $ui.Sub.Text = $Message
@@ -404,7 +447,13 @@ function Close-ProgressWindow {
         Stop-UiServer
     }
     if ($script:Ui) {
-        try { $script:Ui.Form.Close() } catch {}
+        try {
+            if ($script:Ui.Timer) {
+                $script:Ui.Timer.Stop()
+                $script:Ui.Timer.Dispose()
+            }
+            $script:Ui.Form.Close()
+        } catch {}
         $script:Ui = $null
     }
 }
@@ -535,8 +584,8 @@ function Start-DesktopRelaunch {
 }
 
 function Invoke-HermesStep([string]$Exe, [string[]]$HermesArgs, [string]$Tag) {
-    # The window shows nothing live, so no line-pump: both pipes drain
-    # asynchronously (no deadlock however chatty the child) while a small
+    # The window does not stream child output, so no line-pump: both pipes
+    # drain asynchronously (no deadlock however chatty the child) while a small
     # DoEvents loop keeps the marquee animating through long silent
     # stretches (pip installs) -- the old EndOfStream pump blocked on quiet
     # children and froze it. Full output still lands in the hand-off log
@@ -606,7 +655,17 @@ if ($SelfTestUi) {
     Write-HandoffLog "SELF-TEST: shim simulation (no update will run)"
     $hold = 6
     if ($env:HERMES_SELFTEST_HOLD_SECONDS) { $hold = [int]$env:HERMES_SELFTEST_HOLD_SECONDS }
-    Start-Sleep -Seconds $hold
+    Publish-UiProgress "Testing quiet update"
+    if ($env:HERMES_SELFTEST_SILENT_CHILD) {
+        $pythonExe = $env:HERMES_SELFTEST_PYTHON
+        if (-not $pythonExe -or -not (Test-Path -LiteralPath $pythonExe)) {
+            throw "HERMES_SELFTEST_PYTHON must name a Python executable for the silent-child self-test"
+        }
+        $quiet = Invoke-HermesStep $pythonExe @("-c", "import time; time.sleep($hold)") "self-test"
+        Write-HandoffLog "SELF-TEST: silent child exit code: $($quiet.Code)"
+    } else {
+        Start-Sleep -Seconds $hold
+    }
     if ($env:HERMES_SELFTEST_FAIL) {
         Show-ErrorFinale "self-test error state"
     } else {
@@ -633,6 +692,7 @@ try {
     }
 
     # -- 1. Wait for the Desktop to exit (FAIL CLOSED) ----------------------
+    Publish-UiProgress "Waiting for Hermes to close"
     if ($DesktopPid -gt 0) {
         $deadline = (Get-Date).AddSeconds(30)
         while ((Get-Date) -lt $deadline) {
@@ -653,6 +713,7 @@ try {
     }
 
     # -- 2. Wait for the venv shim to unlock (FAIL CLOSED) ------------------
+    Publish-UiProgress "Preparing Hermes files"
     $shim = Join-Path $InstallRoot "venv\Scripts\hermes.exe"
     if (Test-Path -LiteralPath $shim) {
         $unlocked = $false
@@ -725,6 +786,7 @@ try {
     }
     $updateArgs = @("-m", "hermes_cli.main", "update", "--yes", "--gateway", "--force", "--branch", $Branch)
     Write-HandoffLog ("running: python " + ($updateArgs -join " "))
+    Publish-UiProgress "Updating code and dependencies"
     $res = Invoke-HermesStep $pythonExe $updateArgs "update"
     Write-HandoffLog "hermes update exit code: $($res.Code)"
 
@@ -732,6 +794,7 @@ try {
         # One retry for the update-boundary class (fresh code on disk, stale
         # code in memory). Exit 2 ("close all Hermes windows") is not retryable.
         Write-HandoffLog "first attempt failed; retrying once (freshly pulled fix loads on the second run)"
+        Publish-UiProgress "Retrying update"
         $res = Invoke-HermesStep $pythonExe $updateArgs "update"
         Write-HandoffLog "retry exit code: $($res.Code)"
     }
@@ -744,6 +807,7 @@ try {
     $desktopBuildFailed = $false
     if ($res.Code -eq 0 -and $res.Output -match "Desktop build failed") {
         Write-HandoffLog "hermes update reported a desktop build failure (non-fatal there, fatal here); retrying build"
+        Publish-UiProgress "Rebuilding Desktop"
         $rebuild = Invoke-HermesStep $pythonExe @("-m", "hermes_cli.main", "desktop", "--force-build", "--build-only") "rebuild"
         Write-HandoffLog "desktop rebuild exit code: $($rebuild.Code)"
         if ($rebuild.Code -ne 0) { $desktopBuildFailed = $true }
@@ -775,6 +839,7 @@ try {
         Close-ProgressWindow
         [void](Start-DesktopRelaunch)
     } else {
+        Publish-UiProgress "Opening Hermes"
         $cameBack = Start-DesktopRelaunch
         if (-not $cameBack -and $RelaunchExe) {
             # Launch was due and did not verifiably land: truthful result
diff --git a/tests/test_desktop_update_windows_progress.py b/tests/test_desktop_update_windows_progress.py
new file mode 100644
index 0000000000..a03d919df1
--- /dev/null
+++ b/tests/test_desktop_update_windows_progress.py
@@ -0,0 +1,87 @@
+"""Behavioral coverage for quiet Windows Desktop updater progress."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+import re
+import shutil
+import subprocess
+import sys
+import time
+from urllib.request import urlopen
+
+import pytest
+
+
+pytestmark = pytest.mark.windows_only
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+WINDOWS_UPDATE_PS1 = REPO_ROOT / "scripts" / "desktop-update" / "windows.ps1"
+
+
+def _read_progress(url: str) -> dict[str, object]:
+    with urlopen(f"{url}progress", timeout=2) as response:
+        return json.loads(response.read().decode("utf-8"))
+
+
+def test_progress_advances_while_update_child_is_silent(tmp_path: Path) -> None:
+    powershell = shutil.which("powershell.exe")
+    assert powershell, "Windows updater tests require Windows PowerShell."
+
+    output_path = tmp_path / "self-test-output.log"
+    env = os.environ.copy()
+    env["TEMP"] = str(tmp_path)
+    env["TMP"] = str(tmp_path)
+    env["HERMES_SELFTEST_HOLD_SECONDS"] = "3"
+    env["HERMES_SELFTEST_SILENT_CHILD"] = "1"
+    env["HERMES_SELFTEST_PYTHON"] = sys.executable
+
+    with output_path.open("wb") as output:
+        process = subprocess.Popen(
+            [
+                powershell,
+                "-NoProfile",
+                "-ExecutionPolicy",
+                "Bypass",
+                "-File",
+                str(WINDOWS_UPDATE_PS1),
+                "-SelfTestUi",
+                "-NoUi",
+            ],
+            stdout=output,
+            stderr=subprocess.STDOUT,
+            env=env,
+        )
+
+    try:
+        deadline = time.monotonic() + 10
+        shim_url = None
+        while time.monotonic() < deadline:
+            text = output_path.read_text(encoding="utf-8", errors="replace")
+            match = re.search(r"SELF-TEST: shim at (http://127\.0\.0\.1:\d+/)", text)
+            if match:
+                shim_url = match.group(1)
+                break
+            if process.poll() is not None:
+                break
+            time.sleep(0.1)
+
+        assert shim_url, output_path.read_text(encoding="utf-8", errors="replace")
+        first = _read_progress(shim_url)
+        time.sleep(1.2)
+        second = _read_progress(shim_url)
+
+        assert first["status"] == "running"
+        assert first["message"] == "Testing quiet update"
+        assert second["message"] == first["message"]
+        assert int(second["elapsed_seconds"]) > int(first["elapsed_seconds"])
+
+        assert process.wait(timeout=10) == 0
+        final_output = output_path.read_text(encoding="utf-8", errors="replace")
+        assert "SELF-TEST: silent child exit code: 0" in final_output
+    finally:
+        if process.poll() is None:
+            process.kill()
+            process.wait(timeout=5)

From 7a94b1fbf77123140de2c0e1d8c8eca2209ca8c2 Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 19 Aug 2026 13:11:35 -0500
Subject: [PATCH 36/48] fix(update): resolve the project venv as venv or .venv
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`uv venv` writes `.venv` while our installers write `venv`, and every venv
lookup in the update/repair paths hardcoded `venv`. On a `.venv` install
`_venv_scripts_dir()` returned None, so the Windows shim-lock preflight, the
quarantine, and the console-script verification all silently skipped
themselves — the update walked straight into the failure they exist to catch.

Adds `hermes_constants.project_venv_dir()` as the single resolver and routes
both `_venv_scripts_dir()` implementations plus the two VIRTUAL_ENV call
sites through it.

Refs #79542
---
 hermes_cli/_install_repair.py | 15 +++++++++------
 hermes_cli/main.py            | 12 ++++++++----
 hermes_constants.py           | 16 ++++++++++++++++
 3 files changed, 33 insertions(+), 10 deletions(-)

diff --git a/hermes_cli/_install_repair.py b/hermes_cli/_install_repair.py
index 9a4953bfc7..76e78adb98 100644
--- a/hermes_cli/_install_repair.py
+++ b/hermes_cli/_install_repair.py
@@ -92,7 +92,9 @@ def _resolve_install_target(root: Path) -> tuple[list[str], dict | None]:
     """
     uv_bin = _er._find_uv_binary()
     if uv_bin:
-        env = {**os.environ, "VIRTUAL_ENV": str(root / "venv")}
+        from hermes_constants import project_venv_dir
+
+        env = {**os.environ, "VIRTUAL_ENV": str(project_venv_dir(root) or root / "venv")}
         if _is_termux_env(env):
             env.pop("PYTHONPATH", None)
             env.pop("PYTHONHOME", None)
@@ -102,13 +104,14 @@ def _resolve_install_target(root: Path) -> tuple[list[str], dict | None]:
 
 def _venv_scripts_dir(root: Path) -> Path | None:
     """Project venv Scripts/bin dir, when present. stdlib-only."""
-    venv_dir = root / "venv"
-    if not venv_dir.is_dir():
-        return None
-    # hermes_constants is stdlib-only, so the canonical layout helper is safe
+    # hermes_constants is stdlib-only, so the canonical layout helpers are safe
     # to use from this corrupted-venv repair path (#76105: never open-code
     # the Scripts/bin split).
-    from hermes_constants import venv_bin_dir
+    from hermes_constants import project_venv_dir, venv_bin_dir
+
+    venv_dir = project_venv_dir(root)
+    if venv_dir is None:
+        return None
 
     scripts = venv_bin_dir(venv_dir, windows=_is_windows())
     return scripts if scripts.is_dir() else None
diff --git a/hermes_cli/main.py b/hermes_cli/main.py
index 7432f1f018..cb456a0385 100644
--- a/hermes_cli/main.py
+++ b/hermes_cli/main.py
@@ -8785,7 +8785,10 @@ def _default_venv_install_target() -> tuple[list[str], dict[str, str] | None]:
     except Exception:
         uv_bin = None
     if uv_bin:
-        env = {**os.environ, "VIRTUAL_ENV": str(PROJECT_ROOT / "venv")}
+        from hermes_constants import project_venv_dir
+
+        venv_dir = project_venv_dir(PROJECT_ROOT) or PROJECT_ROOT / "venv"
+        env = {**os.environ, "VIRTUAL_ENV": str(venv_dir)}
         if _is_termux_env(env):
             env.pop("PYTHONPATH", None)
             env.pop("PYTHONHOME", None)
@@ -8838,10 +8841,11 @@ def _is_windows() -> bool:
 
 def _venv_scripts_dir() -> Path | None:
     """Return the venv Scripts directory if we're running inside the project venv."""
-    venv_dir = PROJECT_ROOT / "venv"
-    if not venv_dir.is_dir():
+    from hermes_constants import project_venv_dir, venv_bin_dir
+
+    venv_dir = project_venv_dir(PROJECT_ROOT)
+    if venv_dir is None:
         return None
-    from hermes_constants import venv_bin_dir
 
     scripts = venv_bin_dir(venv_dir, windows=_is_windows())
     return scripts if scripts.is_dir() else None
diff --git a/hermes_constants.py b/hermes_constants.py
index 13602e20d6..e7af188397 100644
--- a/hermes_constants.py
+++ b/hermes_constants.py
@@ -1610,6 +1610,22 @@ def venv_bin_dir(venv_dir, *, windows: bool | None = None) -> Path:
     return Path(venv_dir) / ("Scripts" if windows else "bin")
 
 
+def project_venv_dir(project_root) -> Path | None:
+    """The project's venv directory, ``venv`` or ``.venv``, when one exists.
+
+    ``uv venv`` defaults to ``.venv`` while our installers create ``venv``, so
+    both layouts are in the wild. Call sites that only knew about ``venv``
+    silently no-oped on a ``.venv`` install — that is how the Windows
+    shim-lock preflight skipped itself entirely (#79542). ``venv`` wins when
+    both exist, matching what the installers write.
+    """
+    for name in ("venv", ".venv"):
+        candidate = Path(project_root) / name
+        if candidate.is_dir():
+            return candidate
+    return None
+
+
 def venv_python_path(venv_dir, *, windows: bool | None = None) -> Path:
     """Path to the Python interpreter inside *venv_dir* (may not exist)."""
     if windows is None:

From 867ab54e20cf491bae62133614fa4708ccaef96d Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 19 Aug 2026 13:13:09 -0500
Subject: [PATCH 37/48] fix(update): re-run Windows updates off the console
 shim
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`hermes update` launched as venv\Scripts\hermes.exe can never finish on
Windows. The launcher runs the interpreter with the shim as its script and
holds it open without FILE_SHARE_DELETE for the whole command, so the
quarantine rename is refused and uv fails to replace hermes.exe with
os error 32 — every time, with no Desktop, gateway or AV involved. The
concurrent-instance preflight cannot catch it because it excludes this
process and its ancestors by design.

Detect the shim from both the process ancestry and this process's own launch
paths (argv[0], __main__.__file__, the spec origin — the runpy/zipapp launch
puts <shim>\__main__.py there), intersected with the project venv's shims so
an unrelated hermes.exe never matches. When it matches, re-run the same
argv as `venv\Scripts\python.exe -m hermes_cli.main ...` and return, which
releases the shim before the child installs anything.

The hand-off sits ahead of the update lock so the child claims the marker
itself rather than adopting one the parent immediately releases, and any
failure falls through to the previous in-process behaviour with the manual
command printed.

Refs #88838, #89599, #86093
---
 hermes_cli/main.py | 130 +++++++++++++++++++++++++++++++++++++++------
 1 file changed, 114 insertions(+), 16 deletions(-)

diff --git a/hermes_cli/main.py b/hermes_cli/main.py
index cb456a0385..a29bf923cb 100644
--- a/hermes_cli/main.py
+++ b/hermes_cli/main.py
@@ -8741,38 +8741,128 @@ def _recover_core_update_marker_locked() -> None:
             print(f"    {sys.executable} -m pip install -e '.[all]'")
 
 
-def _windows_running_hermes_launcher_locked() -> bool:
-    """True when a venv ``hermes*.exe`` shim is this process or an ancestor.
+def _norm_exe_path(path) -> str:
+    """Case-folded resolved path, for comparing executables on Windows."""
+    try:
+        return str(Path(path).resolve()).lower()
+    except OSError:
+        return str(path).lower()
 
-    Best-effort: returns False when psutil is unavailable or inspection fails.
+
+def _windows_shim_in_process_chain() -> Path | None:
+    """The venv console shim this process runs from or under, if any.
+
+    ``venv\\Scripts\\hermes.exe`` is a launcher that runs the interpreter with
+    the shim itself as its script, and that keeps the shim open — without
+    ``FILE_SHARE_DELETE`` — for the whole process lifetime. So every
+    ``hermes ...`` command holds its own shim, and an editable install run
+    from one can never rewrite it (#88838, #89599).
+
+    Two independent probes, because either can come up empty. Process
+    ancestry finds the launcher when it is a separate parent process, but
+    needs psutil. This process's own launch paths (``sys.argv[0]``,
+    ``__main__.__file__``, the module spec origin) cover the rest — the
+    runpy/zipapp launch puts ``<shim>\\__main__.py`` there, which a plain
+    argv[0] check misses.
+
+    Candidates are intersected with the project venv's own shims, so a
+    ``hermes.exe`` belonging to some other install never matches.
     """
     if not _is_windows():
-        return False
+        return None
     scripts_dir = _venv_scripts_dir()
     if scripts_dir is None:
-        return False
-    shims = _hermes_exe_shims(scripts_dir)
+        return None
+    shims = {_norm_exe_path(shim): shim for shim in _hermes_exe_shims(scripts_dir)}
     if not shims:
-        return False
-    shim_set: set[str] = set()
-    for shim in shims:
-        try:
-            shim_set.add(str(shim.resolve()).lower())
-        except OSError:
-            shim_set.add(str(shim).lower())
+        return None
+
+    def _match(candidate) -> Path | None:
+        path = Path(candidate)
+        if path.name.lower() == "__main__.py":
+            path = path.parent
+        return shims.get(_norm_exe_path(path))
+
+    candidates: list[str] = list(sys.argv[:1])
+    main_mod = sys.modules.get("__main__")
+    for attr in (getattr(main_mod, "__file__", None),
+                 getattr(getattr(main_mod, "__spec__", None), "origin", None)):
+        if attr:
+            candidates.append(attr)
+    for candidate in candidates:
+        matched = _match(candidate)
+        if matched is not None:
+            return matched
+
     try:
         import psutil
 
         me = psutil.Process()
         for proc in [me] + list(me.parents()):
             try:
-                exe_norm = str(Path(proc.exe()).resolve()).lower()
+                matched = _match(proc.exe())
             except Exception:
                 continue
-            if exe_norm in shim_set:
-                return True
+            if matched is not None:
+                return matched
     except Exception:
+        return None
+    return None
+
+
+def _windows_running_hermes_launcher_locked() -> bool:
+    """True when a venv ``hermes*.exe`` shim is this process or an ancestor.
+
+    Best-effort: returns False when psutil is unavailable or inspection fails.
+    """
+    return _windows_shim_in_process_chain() is not None
+
+
+# Set on the re-exec'd child so it can never spawn another one.
+_UPDATE_REEXEC_ENV = "HERMES_UPDATE_REEXEC"
+
+
+def _reexec_update_off_windows_shim() -> bool:
+    """Hand this update to the venv interpreter, off the console shim.
+
+    Returns True when a child was spawned and the caller must return at once,
+    so this process exits and releases the shim before the child reaches
+    ``pip install -e .``. Returns False to continue in-process.
+
+    The child is spawned, not waited on — this process exiting IS the fix, so
+    the shell sees the spawn's status rather than the update's. The update
+    prints its own result, and ``--gateway`` writes the true exit code to
+    ``.update_exit_code`` for the gateway watcher before restarting.
+
+    Anything that stops the hand-off (no venv python, spawn refused) falls
+    through to the old in-process behaviour with the manual command printed,
+    so a broken venv still gets whatever the update can do rather than a
+    dead end.
+    """
+    if os.environ.get(_UPDATE_REEXEC_ENV) == "1":
         return False
+    shim = _windows_shim_in_process_chain()
+    if shim is None:
+        return False
+
+    from hermes_constants import venv_python_path
+
+    python_exe = venv_python_path(shim.parent.parent, windows=True)
+    cmd = [str(python_exe), "-m", "hermes_cli.main", *sys.argv[1:]]
+    if python_exe.is_file():
+        try:
+            subprocess.Popen(cmd, env={**os.environ, _UPDATE_REEXEC_ENV: "1"})
+            print(
+                f"→ Windows: {shim.name} cannot replace itself while it runs; "
+                "continuing the update under the venv Python."
+            )
+            print("  Progress continues below; this shell returns immediately.")
+            return True
+        except OSError as exc:
+            logger.debug("Update re-exec via %s failed: %s", python_exe, exc)
+    print(f"  ⚠ Could not re-run the update off {shim.name}. If the install")
+    print("    fails to replace it, run this from a fresh shell instead:")
+    print(f"    {subprocess.list2cmdline(cmd)}")
     return False
 
 
@@ -9968,6 +10058,14 @@ def cmd_update(args):
         )
         return
 
+    # Windows: an update launched through venv\Scripts\hermes.exe holds that
+    # shim open for its whole run, and the dependency sync has to replace it.
+    # Hand off to the venv interpreter before anything else — in particular
+    # before the update lock, so the child claims the marker itself instead of
+    # adopting one this process is about to release.
+    if _reexec_update_off_windows_shim():
+        return
+
     gateway_mode = getattr(args, "gateway", False)
 
     # Protect against mid-update terminal disconnects (SIGHUP) and tolerate

From a9eb99d1724a9efa4ad6723bbd46f930a2478889 Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 19 Aug 2026 13:14:33 -0500
Subject: [PATCH 38/48] fix(update): stop deferring shim renames to next boot
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

MOVEFILE_DELAY_UNTIL_REBOOT was the quarantine's last resort, and it is worse
than doing nothing. It writes to HKLM, so a non-elevated update — every
Desktop-driven one, and most terminal ones — gets ERROR_ACCESS_DENIED and
reports nothing. When it does succeed it frees nothing for the install
running right now, and the queued operation outlives that update: at the next
boot it moves aside whatever sits at the shim path, including a shim a later
repair just wrote.

Drops the fallback and sweeps entries older versions queued, matching only
our own <shim> -> <shim>.old.<stamp> pairs so unrelated installers keep
theirs.

Salvaged from #88121 by @fangliquanflq.
---
 hermes_cli/main.py                 | 142 +++++++++++++++++------------
 hermes_cli/subcommands/update.py   |   2 +-
 scripts/desktop-update/windows.ps1 |  14 +--
 3 files changed, 90 insertions(+), 68 deletions(-)

diff --git a/hermes_cli/main.py b/hermes_cli/main.py
index a29bf923cb..8402f228de 100644
--- a/hermes_cli/main.py
+++ b/hermes_cli/main.py
@@ -8980,19 +8980,15 @@ def _quarantine_running_hermes_exe(
 
     1. Retry up to ``max_attempts`` times with exponential backoff
        (100/250/500/1000 ms). Handles the AV-scanner case.
-    2. If all retries fail, schedule the .exe for replacement on next
-       reboot via ``MoveFileExW(MOVEFILE_DELAY_UNTIL_REBOOT)``. This still
-       lets uv create a fresh shim at the original path (Windows will keep
-       the old file's content under a new name until the reboot), so the
-       update can complete; the user just needs to reboot to fully unload
-       the stale image.
-    3. Print a clear warning naming the most likely culprit (running
-       Hermes Desktop / gateway / REPL) and pointing to ``--force``.
+    2. If all retries fail, print a clear warning naming the most likely
+       culprit (running Hermes Desktop / gateway / REPL).
+
+    The updater's own launcher is no longer one of those culprits: an update
+    started from ``hermes.exe`` re-runs itself under the venv Python before
+    reaching here (``_reexec_update_off_windows_shim``).
 
     Returns the list of (original, quarantined) pairs so the caller can roll
-    back if the install itself fails before uv writes a replacement. Pairs
-    where we used ``MOVEFILE_DELAY_UNTIL_REBOOT`` are NOT returned — they
-    are already deferred and roll-back is meaningless.
+    back if the install itself fails before uv writes a replacement.
     """
     moved: list[tuple[Path, Path]] = []
     if not _is_windows():
@@ -9028,27 +9024,13 @@ def _quarantine_running_hermes_exe(
         if last_exc is None:
             continue
 
-        # All in-process renames failed. Try MoveFileEx with
-        # MOVEFILE_DELAY_UNTIL_REBOOT as a last resort. This succeeds in the
-        # exact case where the inline rename failed (another process holds
-        # the handle without share-delete), at the cost of requiring a
-        # reboot to fully reclaim the old .exe.
-        scheduled = _schedule_replace_on_reboot(shim, target)
-        if scheduled:
-            print(
-                f"  ⚠ {shim.name} is locked by another process; scheduled "
-                f"replacement on next reboot."
-            )
-            print(
-                "    The new shim was written at the same path, but a "
-                "reboot is needed to fully unload the old one."
-            )
-            # Do NOT append to ``moved``: we don't want roll-back to undo a
-            # reboot-deferred operation.
-            continue
-
-        # Truly couldn't budge the .exe. Print an actionable warning and let
-        # uv try its luck — sometimes uv's own retry handling pulls through.
+        # Every rename failed. Deferring one to next boot via
+        # MOVEFILE_DELAY_UNTIL_REBOOT used to be the fallback here, but it
+        # cannot help: it needs elevation we don't have, and when it does
+        # land it frees nothing for the install running right now while
+        # queueing an operation that will move a later, freshly repaired shim
+        # aside at next boot. Report and let uv try its luck instead —
+        # sometimes its own retry handling pulls through.
         print(
             f"  ⚠ Could not quarantine {shim.name} ({last_exc.__class__.__name__}: "
             f"another process is holding it open)."
@@ -9061,39 +9043,78 @@ def _quarantine_running_hermes_exe(
     return moved
 
 
-def _schedule_replace_on_reboot(shim: Path, quarantine_target: Path) -> bool:
-    """Schedule ``shim`` -> ``quarantine_target`` via PendingFileRenameOperations.
+_PENDING_RENAME_KEY = r"SYSTEM\CurrentControlSet\Control\Session Manager"
+_PENDING_RENAME_VALUE = "PendingFileRenameOperations"
 
-    Uses Win32 ``MoveFileExW`` with ``MOVEFILE_REPLACE_EXISTING |
-    MOVEFILE_DELAY_UNTIL_REBOOT``. The OS persists the rename in
-    ``HKLM\\System\\CurrentControlSet\\Control\\Session Manager\\
-    PendingFileRenameOperations`` and applies it before any user-mode code
-    runs on next boot — at which point no process can hold the .exe.
 
-    Returns ``True`` if the schedule call succeeded, ``False`` otherwise
-    (non-Windows, ctypes failure, lack of privilege, etc.). Never raises.
+def _filter_pending_shim_renames(
+    entries: list[str], shims: list[Path]
+) -> tuple[list[str], int]:
+    """Drop shim-quarantine pairs from a PendingFileRenameOperations value.
+
+    The value is a flat REG_MULTI_SZ of (source, target) pairs, and other
+    installers share it, so only pairs matching our own
+    ``<shim>`` -> ``<shim>.old.<stamp>`` naming are removed. Returns the
+    entries to keep and how many pairs were dropped.
+    """
+    import ntpath
+
+    def _norm(value: str) -> str:
+        path = str(value).lstrip("!")
+        if path.startswith("\\??\\"):
+            path = path[4:]
+        return ntpath.normcase(ntpath.normpath(path))
+
+    shim_paths = {_norm(str(shim)) for shim in shims}
+    kept: list[str] = []
+    removed = 0
+    for index in range(0, len(entries) - 1, 2):
+        source, target = entries[index], entries[index + 1]
+        source_norm = _norm(source)
+        if source_norm in shim_paths and _norm(target).startswith(f"{source_norm}.old."):
+            removed += 1
+        else:
+            kept.extend((source, target))
+    if len(entries) % 2:
+        kept.append(entries[-1])
+    return kept, removed
+
+
+def _cleanup_pending_shim_renames(scripts_dir: Path) -> int:
+    """Drop reboot renames older Hermes versions queued for our shims.
+
+    Hermes used to fall back to ``MoveFileExW(MOVEFILE_DELAY_UNTIL_REBOOT)``
+    when the quarantine rename failed. Those entries outlive the update that
+    queued them, so at the next boot they move away whatever now sits at the
+    shim path — including a shim a later repair just wrote. Needs elevation
+    to remove (same as it needed to create); a no-op otherwise.
     """
     if not _is_windows():
-        return False
+        return 0
     try:
-        import ctypes
-        from ctypes import wintypes
+        import winreg
 
-        MOVEFILE_REPLACE_EXISTING = 0x1
-        MOVEFILE_DELAY_UNTIL_REBOOT = 0x4
-
-        MoveFileExW = ctypes.windll.kernel32.MoveFileExW
-        MoveFileExW.argtypes = [wintypes.LPCWSTR, wintypes.LPCWSTR, wintypes.DWORD]
-        MoveFileExW.restype = wintypes.BOOL
-
-        ok = MoveFileExW(
-            str(shim),
-            str(quarantine_target),
-            MOVEFILE_REPLACE_EXISTING | MOVEFILE_DELAY_UNTIL_REBOOT,
-        )
-        return bool(ok)
-    except Exception:
-        return False
+        with winreg.OpenKey(
+            winreg.HKEY_LOCAL_MACHINE,
+            _PENDING_RENAME_KEY,
+            0,
+            winreg.KEY_QUERY_VALUE | winreg.KEY_SET_VALUE,
+        ) as key:
+            entries, value_type = winreg.QueryValueEx(key, _PENDING_RENAME_VALUE)
+            if value_type != winreg.REG_MULTI_SZ or not isinstance(entries, list):
+                return 0
+            kept, removed = _filter_pending_shim_renames(
+                entries, _hermes_exe_shims(scripts_dir)
+            )
+            if not removed:
+                return 0
+            if kept:
+                winreg.SetValueEx(key, _PENDING_RENAME_VALUE, 0, winreg.REG_MULTI_SZ, kept)
+            else:
+                winreg.DeleteValue(key, _PENDING_RENAME_VALUE)
+            return removed
+    except (OSError, ValueError):
+        return 0
 
 
 def _restore_quarantined_exes(moved: list[tuple[Path, Path]]) -> None:
@@ -9146,7 +9167,7 @@ def _run_quarantined_install(
 
 
 def _cleanup_quarantined_exes(scripts_dir: Path | None = None) -> None:
-    """Sweep ``hermes.exe.old.*`` left by prior updates.
+    """Sweep ``hermes.exe.old.*`` and stale reboot renames left by prior updates.
 
     Called early on every hermes invocation. The .old files are unlocked once
     their owning process exited, so deletion succeeds the next run. Silent
@@ -9158,6 +9179,7 @@ def _cleanup_quarantined_exes(scripts_dir: Path | None = None) -> None:
         scripts_dir = _venv_scripts_dir()
     if scripts_dir is None:
         return
+    _cleanup_pending_shim_renames(scripts_dir)
     try:
         for stale in scripts_dir.glob("*.exe.old.*"):
             try:
diff --git a/hermes_cli/subcommands/update.py b/hermes_cli/subcommands/update.py
index f612001fa0..680693c393 100644
--- a/hermes_cli/subcommands/update.py
+++ b/hermes_cli/subcommands/update.py
@@ -65,7 +65,7 @@ def build_update_parser(subparsers, *, cmd_update: Callable) -> None:
         "--force",
         action="store_true",
         default=False,
-        help="Windows: proceed with the update even when another hermes.exe is detected. The concurrent process will likely cause WinError 32 warnings and may leave a reboot-deferred .exe replacement. Does NOT bypass the venv-process guard (see --force-venv).",
+        help="Windows: proceed with the update even when another hermes.exe is detected. The concurrent process will likely cause WinError 32 warnings. Does NOT bypass the venv-process guard (see --force-venv).",
     )
     update_parser.add_argument(
         "--force-venv",
diff --git a/scripts/desktop-update/windows.ps1 b/scripts/desktop-update/windows.ps1
index 247ca6cf5b..c5e68f85cd 100644
--- a/scripts/desktop-update/windows.ps1
+++ b/scripts/desktop-update/windows.ps1
@@ -703,13 +703,13 @@ try {
     # the next. Step 2's preflight cannot catch it, because the shim genuinely
     # IS unlocked at that moment.
     #
-    # When the rename loses that race, _schedule_replace_on_reboot is the last
-    # resort -- and it writes to HKLM\...\PendingFileRenameOperations, which
-    # requires elevation. A Desktop-driven update runs non-elevated, so it
-    # returns ERROR_ACCESS_DENIED and `uv pip install -e .` exits 2. The ZIP
-    # fallback repeats the identical sequence, so the desktop build stage is
-    # never reached and apps/desktop/release is left missing -- an install whose
-    # Start Menu shortcut points at a Hermes.exe that no longer exists.
+    # When the rename loses that race there is no recovery: `uv pip install -e .`
+    # exits 2 and the ZIP fallback repeats the identical sequence, so the desktop
+    # build stage is never reached and apps/desktop/release is left missing -- an
+    # install whose Start Menu shortcut points at a Hermes.exe that no longer
+    # exists. (A reboot-deferred rename was the old last resort here; it needed
+    # elevation a Desktop-driven update does not have, and freed nothing for the
+    # install already in flight.)
     #
     # Running the same code as `python.exe -m hermes_cli.main update` puts the
     # inherited handles on python.exe, which uv never has to replace.

From 3f6d4c6338b258245da98c1ab9f1537352bb6a32 Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 19 Aug 2026 13:15:02 -0500
Subject: [PATCH 39/48] fix(gateway): run Windows /update as a module, not
 through the shim

The Windows branch spawned the updater as `hermes.exe update --gateway`, so
the update held the very shim it had to replace and failed with os error 32.
Invoke it as `python -m hermes_cli.main update --gateway` under the same
interpreter the gateway already runs, which maps no shim.

Salvaged from #89970 by @Akloenx123.
---
 gateway/slash_commands.py | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/gateway/slash_commands.py b/gateway/slash_commands.py
index 1986bbd374..cd54164bd0 100644
--- a/gateway/slash_commands.py
+++ b/gateway/slash_commands.py
@@ -5958,8 +5958,11 @@ class GatewaySlashCommandsMixin:
                 import textwrap
                 from hermes_cli._subprocess_compat import windows_detach_popen_kwargs
 
-                # hermes_cmd is a list of argv parts we can pass directly
-                # (no shell-quoting needed).
+                # Invoke the updater as a module under this interpreter rather
+                # than through hermes_cmd (venv\Scripts\hermes.exe): the shim
+                # launcher holds its own file open for the whole run, and the
+                # update has to replace it. Going through python.exe maps no
+                # shim, so the entry points can be rewritten freely.
                 helper = textwrap.dedent(
                     """
                     import os, subprocess, sys
@@ -5979,7 +5982,8 @@ class GatewaySlashCommandsMixin:
                     [
                         sys.executable, "-c", helper,
                         str(output_path), str(exit_code_path),
-                        *hermes_cmd, "update", "--gateway",
+                        sys.executable, "-m", "hermes_cli.main",
+                        "update", "--gateway",
                     ],
                     stdout=subprocess.DEVNULL,
                     stderr=subprocess.DEVNULL,

From cf2ab8522ad957b011ea51465a159592ec015167 Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 19 Aug 2026 13:13:36 -0500
Subject: [PATCH 40/48] fix(update): one elapsed clock, served to the shim by
 both orchestrators

The shim is a shared page, but only windows.ps1 publishes a stage and an
elapsed count. On mac and Linux posix.sh publishes `running` with an empty
message and no clock, so the running branch rendered the h2 back into the
muted line ("Updating Hermes" twice) and started a clock in the browser,
losing "Hermes will open once done." on both platforms.

A clock started in the page measures when the window painted, not how long
the update has been running -- on posix that is the only clock there is, and
it reads zero after the desktop-exit wait has already burned 30s. That is the
hardcoded-milestone problem #75895 removed, in a new costume.

So: elapsed comes from the orchestrator or is not shown. serve-ui.py stamps
it per request from the hand-off start (a value written into the status file
would freeze between publishes, which are minutes apart -- exactly the stall
the line exists to disprove), matching what Windows' in-process listener
already does. posix.sh gets the stages it was missing, at the four gates it
genuinely waits on. Absent a stage the page keeps the settled copy, and an
old orchestrator that sends no clock simply shows no clock.
---
 scripts/desktop-update/posix.sh    | 21 +++++++++++++++++---
 scripts/desktop-update/serve-ui.py | 27 ++++++++++++++++++++------
 scripts/desktop-update/ui.html     | 31 ++++++++++++++++--------------
 scripts/desktop-update/windows.ps1 |  2 +-
 4 files changed, 57 insertions(+), 24 deletions(-)

diff --git a/scripts/desktop-update/posix.sh b/scripts/desktop-update/posix.sh
index 1459fe6aa7..714d8a1ad5 100755
--- a/scripts/desktop-update/posix.sh
+++ b/scripts/desktop-update/posix.sh
@@ -64,6 +64,7 @@ LOG_DIR="$HERMES_HOME/logs"; mkdir -p "$LOG_DIR" 2>/dev/null || true
 LOG="$LOG_DIR/desktop-update-handoff.log"
 RESULT="$HERMES_HOME/.hermes-update-result.json"
 STATUS="${TMPDIR:-/tmp}/hermes-update-status.$$"
+STARTED_AT="$(date +%s)"  # the shim's elapsed clock; see serve-ui.py
 
 UI_SERVER_PID="" UI_BROWSER_PID="" FINAL_CODE=1
 FINAL_MSG="update did not complete"
@@ -147,9 +148,19 @@ notify_fallback() { # status message — renderer-free recovery surface.
   log "NOTICE: no notification surface accepted; outcome reaches the user via the result dialog on next launch: $2"
 }
 
-publish() { # status message -- atomic replace; the server reads per poll
+write_status() { # status message -- atomic replace; the server reads per poll
   printf '{"status":"%s","message":"%s"}' "$(json_escape "$1")" "$(json_escape "$2")" > "$STATUS.tmp" \
     && mv -f "$STATUS.tmp" "$STATUS" 2>/dev/null || true
+}
+
+publish_stage() { # a long wait the orchestrator is already gating on. No poll
+  # beat (that would add a second per stage to every update) and no
+  # notification fallback (there is nothing here for the user to act on).
+  write_status "running" "$1"
+}
+
+publish() { # terminal event -- the page must render it before teardown
+  write_status "$1" "$2"
   [ -n "$UI_SERVER_PID" ] && sleep 1  # one poll beat to render the state
   [ -z "$UI_SERVER_PID" ] && notify_fallback "$1" "$2"
 }
@@ -178,7 +189,7 @@ start_ui() {
   browser="$(find_browser)"
   { [ -f "$html" ] && [ -n "$py" ] && [ -n "$browser" ]; } || { log "shim: no renderer; skipping UI"; return; }
 
-  publish "running" ""
+  publish_stage ""
   # The Desktop's final teardown targets the updater process group.  Put both
   # UI processes in their own sessions so neither the HTTP server nor a Chrome
   # renderer becomes collateral damage (Chrome surfaces that renderer death as
@@ -190,7 +201,7 @@ start_ui() {
   # window showed ERR_CONNECTION_REFUSED for the whole run; upstream #66753).
   # stop_ui ends the server with SIGKILL instead — it is stateless HTTP.
   "$py" -c 'import os, signal, sys; os.setsid(); signal.signal(signal.SIGTERM, signal.SIG_IGN); signal.signal(signal.SIGHUP, signal.SIG_IGN); os.execv(sys.argv[1], sys.argv[1:])' \
-    "$py" "$SCRIPT_DIR/serve-ui.py" "$html" "$STATUS" > "$LOG_DIR/desktop-update-ui-port" 2>>"$LOG" &
+    "$py" "$SCRIPT_DIR/serve-ui.py" "$html" "$STATUS" "$STARTED_AT" > "$LOG_DIR/desktop-update-ui-port" 2>>"$LOG" &
   UI_SERVER_PID=$!
   for i in $(seq 1 10); do
     port="$(tr -cd '0-9' < "$LOG_DIR/desktop-update-ui-port" 2>/dev/null)"
@@ -264,6 +275,7 @@ mac_swap() {
   # the copy in. Every step checked; a failed final move ROLLS BACK so the
   # user always has a launchable app, and the result file tells the truth.
   if [ "$FINAL_CODE" -eq 0 ] && [ -n "$rebuilt" ] && [ -d "$RELAUNCH_TARGET" ] && [ "$rebuilt" != "$RELAUNCH_TARGET" ]; then
+    publish_stage "Installing the new app"
     rm -rf "$RELAUNCH_TARGET.new" "$RELAUNCH_TARGET.old" 2>/dev/null || true
     if ! /usr/bin/ditto "$rebuilt" "$RELAUNCH_TARGET.new"; then
       rm -rf "$RELAUNCH_TARGET.new" 2>/dev/null || true
@@ -486,6 +498,7 @@ cd "$INSTALL_ROOT" || {
 }
 export PYTHONUNBUFFERED=1
 log "running: hermes update --yes --gateway --branch $BRANCH"
+publish_stage "Updating code and dependencies"
 OUT="$("$HERMES_BIN" update --yes --gateway --branch "$BRANCH" 2>&1)"; CODE=$?
 printf '%s\n' "$OUT" >> "$LOG" 2>/dev/null
 log "hermes update exit code: $CODE"
@@ -494,6 +507,7 @@ if [ "$CODE" -ne 0 ] && [ "$CODE" -ne 2 ]; then
   # Retry once: update-boundary class (fresh code on disk, stale in memory).
   # Exit 2 ("close all Hermes windows") is not retryable.
   log "retrying once (freshly pulled fix loads on the second run)"
+  publish_stage "Retrying update"
   OUT="$("$HERMES_BIN" update --yes --gateway --branch "$BRANCH" 2>&1)"; CODE=$?
   printf '%s\n' "$OUT" >> "$LOG" 2>/dev/null
   log "retry exit code: $CODE"
@@ -505,6 +519,7 @@ trap 'on_signal TERM' TERM
 # and call it success -- retry the build once, propagate honestly.
 if [ "$CODE" -eq 0 ] && printf '%s' "$OUT" | grep -q "Desktop build failed"; then
   log "desktop build failed inside hermes update; retrying build"
+  publish_stage "Rebuilding Desktop"
   "$HERMES_BIN" desktop --force-build --build-only >> "$LOG" 2>&1 || {
     FINAL_CODE=6 FINAL_MSG="Code and dependencies updated, but the Desktop app rebuild failed - you are running the previous build. Run hermes desktop --force-build from a terminal to retry."
     exit 6
diff --git a/scripts/desktop-update/serve-ui.py b/scripts/desktop-update/serve-ui.py
index 8d0a6bfe61..87801df099 100644
--- a/scripts/desktop-update/serve-ui.py
+++ b/scripts/desktop-update/serve-ui.py
@@ -4,30 +4,45 @@ Two GET routes: / serves ui.html, /progress serves the status file the
 orchestrator script writes ({"status": "running"|"done"|"error", ...}).
 Exists because a file:// page cannot receive events from a detached
 process. Prints the chosen ephemeral port on stdout, serves until killed.
+
+`elapsed_seconds` is stamped per request, not read from the status file:
+stages are minutes apart, so a value frozen at the last publish would sit
+still through the longest waits -- exactly the stall the page exists to
+disprove. Windows' in-process listener computes it the same way.
 """
 
 import http.server
 import json
 import socketserver
 import sys
+import time
 
 html_path, status_path = sys.argv[1], sys.argv[2]
+started_at = float(sys.argv[3]) if len(sys.argv) > 3 else time.time()
 with open(html_path, "rb") as f:
     HTML = f.read()
 
 
+def progress_body():
+    try:
+        with open(status_path, "rb") as f:
+            state = json.loads(f.read())
+        if not isinstance(state, dict):
+            raise ValueError(state)
+    except Exception:
+        state = {"status": "running", "message": ""}
+    state["elapsed_seconds"] = max(0, int(time.time() - started_at))
+
+    return json.dumps(state).encode("utf-8")
+
+
 class Handler(http.server.BaseHTTPRequestHandler):
     def log_message(self, format, *args):  # noqa: A002 - base class signature
         pass
 
     def do_GET(self):
         if self.path.startswith("/progress"):
-            try:
-                with open(status_path, "rb") as f:
-                    body = f.read()
-                json.loads(body)
-            except Exception:
-                body = b'{"status":"running","message":""}'
+            body = progress_body()
             ctype = "application/json; charset=utf-8"
         elif self.path == "/":
             body, ctype = HTML, "text/html; charset=utf-8"
diff --git a/scripts/desktop-update/ui.html b/scripts/desktop-update/ui.html
index 2b36bf6403..6e55cb694c 100644
--- a/scripts/desktop-update/ui.html
+++ b/scripts/desktop-update/ui.html
@@ -4,8 +4,9 @@
 
   Served over loopback by the orchestrator (windows.ps1 / posix.sh) into a
   chromeless browser app window. Pure veneer: polls /progress for the current
-  hand-off stage or a terminal event and reacts; owns nothing (relaunch, result file, marker hygiene
-  all live in the orchestrator, which runs identically with no UI at all).
+  hand-off stage or a terminal event and reacts; owns nothing (relaunch,
+  result file, marker hygiene all live in the orchestrator, which runs
+  identically with no UI at all).
 
   The visual is PR #75895's update hand-off screen, ported verbatim:
   - Loader: the desktop's "Fourier Flow" curve. Math + tuning lifted from
@@ -13,7 +14,9 @@
     apps/desktop/src/components/ui/loader.tsx 'fourier-flow'). Keep the
     constants in sync if the desktop's curve is retuned.
   - Layout: loader (size-20) + one title + one muted stage/elapsed line. No
-    progress bar, stage list, log pane, or cancel (see #75895 for the arguments).
+    progress bar, stage list, log pane, or cancel (see #75895 for the
+    arguments). Elapsed comes from the orchestrator or is omitted -- a clock
+    started here would measure when this window painted, not the update.
   - Appearance follows the OS. Dark seeds are the installer's neutral
     charcoal (#232323 base, foreground #d6d6d6) — never brand blue.
 -->
@@ -89,6 +92,7 @@
     font-size: 12px;
     line-height: 1.5;
     color: var(--muted-foreground);
+    white-space: pre-line;
   }
   p code {
     font-family: ui-monospace, SFMono-Regular, Consolas, monospace;
@@ -104,7 +108,7 @@
     <div id="loader" role="status" aria-label="Updating"></div>
     <div id="glyph"></div>
     <h2 id="title">Updating Hermes</h2>
-    <p id="line">Preparing update<br>0s elapsed</p>
+    <p id="line">Hermes will open once done.</p>
   </div>
 <script>
   /* ── Fourier Flow loader, ported verbatim from loader.tsx ─────────────── */
@@ -199,9 +203,12 @@
   const titleEl = document.getElementById('title')
   const lineEl = document.getElementById('line')
   const glyphEl = document.getElementById('glyph')
-  const clientStartedAt = Date.now()
+  const defaultLine = lineEl.textContent   /* what a stage-less run says */
   let settled = false
 
+  const elapsedText = s =>
+    s < 60 ? `${s}s elapsed` : `${Math.floor(s / 60)}m ${s % 60}s elapsed`
+
   function settle(state) {
     settled = true
     window.cancelAnimationFrame(frame)
@@ -211,15 +218,11 @@
   function apply(state) {
     if (settled) return
     if (state.status === 'running') {
-      const reported = Number(state.elapsed_seconds)
-      const elapsed = Number.isFinite(reported) && reported >= 0
-        ? Math.floor(reported)
-        : Math.floor((Date.now() - clientStartedAt) / 1000)
-      const elapsedText = elapsed < 60
-        ? `${elapsed}s elapsed`
-        : `${Math.floor(elapsed / 60)}m ${elapsed % 60}s elapsed`
-      lineEl.textContent = `${state.message || 'Updating Hermes'}\n${elapsedText}`
-      lineEl.style.whiteSpace = 'pre-line'
+      const stage = state.message || defaultLine
+      const elapsed = Number(state.elapsed_seconds)
+      lineEl.textContent = Number.isFinite(elapsed) && elapsed >= 0
+        ? `${stage}\n${elapsedText(Math.floor(elapsed))}`
+        : stage
     } else if (state.status === 'done') {
       settle('done')
       glyphEl.textContent = '\u2713'
diff --git a/scripts/desktop-update/windows.ps1 b/scripts/desktop-update/windows.ps1
index ad3db7e7ea..9c1deb4f28 100644
--- a/scripts/desktop-update/windows.ps1
+++ b/scripts/desktop-update/windows.ps1
@@ -83,7 +83,7 @@ $LogDir = Join-Path $HermesHome "logs"
 $LogPath = Join-Path $LogDir "desktop-update-handoff.log"
 $ResultPath = Join-Path $HermesHome ".hermes-update-result.json"
 $script:Ui = $null
-$script:UiStage = "Preparing update"
+$script:UiStage = "Hermes will open once done."   # until the first gate; matches ui.html
 $script:UiStopwatch = [System.Diagnostics.Stopwatch]::StartNew()
 
 function Write-HandoffLog([string]$Message) {

From e602225d86b3337f8b5ea1fabd5ec37cde4aeda3 Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 19 Aug 2026 13:15:11 -0500
Subject: [PATCH 41/48] test(update): cover the progress contract without a
 test hook in the updater

The self-test grew a branch that spawns a Python child so pytest could prove
progress advances during one. It doesn't need to: /progress is answered from
its own runspace, so the existing hold already blocks the main thread, and
the spawn only exercised Invoke-HermesStep, which nothing here changes.

The Windows test now asserts the invariant instead of the self-test's stage
string, and the posix half -- previously untested, and the half that broke --
gets real coverage: serve-ui.py's wire shape, and posix.sh driven end to end
with a stub `hermes` that reports which stage was on screen while it ran.
---
 scripts/desktop-update/posix.sh               |   3 +-
 scripts/desktop-update/windows.ps1            |  11 +-
 tests/test_desktop_update_shim_progress.py    | 195 ++++++++++++++++++
 tests/test_desktop_update_windows_progress.py |  36 ++--
 4 files changed, 219 insertions(+), 26 deletions(-)
 create mode 100644 tests/test_desktop_update_shim_progress.py

diff --git a/scripts/desktop-update/posix.sh b/scripts/desktop-update/posix.sh
index 714d8a1ad5..1ad37ecdb6 100755
--- a/scripts/desktop-update/posix.sh
+++ b/scripts/desktop-update/posix.sh
@@ -22,7 +22,8 @@
 #     [-- <args...>]           linux: filtered launch args to replay
 #
 # The shim (ui.html in a chromeless browser app window) is decoration: it
-# polls /progress for `done` or `error` and reacts. It owns nothing --
+# polls /progress for the current stage or a terminal event and reacts. The
+# stages come from the gates below, never from child output. It owns nothing --
 # relaunch, result file, marker hygiene all happen here, identically, when
 # no renderer exists. No chromium-family browser found = no UI, fine.
 #
diff --git a/scripts/desktop-update/windows.ps1 b/scripts/desktop-update/windows.ps1
index 9c1deb4f28..3c6b5da750 100644
--- a/scripts/desktop-update/windows.ps1
+++ b/scripts/desktop-update/windows.ps1
@@ -656,16 +656,7 @@ if ($SelfTestUi) {
     $hold = 6
     if ($env:HERMES_SELFTEST_HOLD_SECONDS) { $hold = [int]$env:HERMES_SELFTEST_HOLD_SECONDS }
     Publish-UiProgress "Testing quiet update"
-    if ($env:HERMES_SELFTEST_SILENT_CHILD) {
-        $pythonExe = $env:HERMES_SELFTEST_PYTHON
-        if (-not $pythonExe -or -not (Test-Path -LiteralPath $pythonExe)) {
-            throw "HERMES_SELFTEST_PYTHON must name a Python executable for the silent-child self-test"
-        }
-        $quiet = Invoke-HermesStep $pythonExe @("-c", "import time; time.sleep($hold)") "self-test"
-        Write-HandoffLog "SELF-TEST: silent child exit code: $($quiet.Code)"
-    } else {
-        Start-Sleep -Seconds $hold
-    }
+    Start-Sleep -Seconds $hold
     if ($env:HERMES_SELFTEST_FAIL) {
         Show-ErrorFinale "self-test error state"
     } else {
diff --git a/tests/test_desktop_update_shim_progress.py b/tests/test_desktop_update_shim_progress.py
new file mode 100644
index 0000000000..bf6bf6b712
--- /dev/null
+++ b/tests/test_desktop_update_shim_progress.py
@@ -0,0 +1,195 @@
+"""The shim's /progress contract, exercised against the real posix hand-off.
+
+`ui.html` is one page for three operating systems, so the stage-and-elapsed
+line it renders is only as good as the weakest orchestrator behind it. These
+drive the real `posix.sh` and the real `serve-ui.py` -- no mocks, no source
+reading -- because the posix half is the one that had no coverage.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+from urllib.request import urlopen
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SHIM_DIR = REPO_ROOT / "scripts" / "desktop-update"
+
+# posix.sh re-execs itself through these to detach from Electron's process
+# group; without them the hand-off never reaches its own main flow.
+requires_posix_handoff = pytest.mark.skipif(
+    not (os.path.exists("/bin/bash") and os.path.exists("/usr/bin/python3")),
+    reason="posix.sh detaches through /bin/bash and /usr/bin/python3",
+)
+
+
+# ── serve-ui.py: what the page actually receives ───────────────────────────
+
+
+@pytest.fixture
+def progress(tmp_path):
+    """The real loopback server, over a status file the test drives."""
+    status = tmp_path / "hermes-update-status"
+    proc = subprocess.Popen(
+        [
+            sys.executable,
+            str(SHIM_DIR / "serve-ui.py"),
+            str(SHIM_DIR / "ui.html"),
+            str(status),
+            str(time.time()),
+        ],
+        stdout=subprocess.PIPE,
+        text=True,
+    )
+    try:
+        port = int(proc.stdout.readline().strip())
+
+        class Progress:
+            def publish(self, state: str, message: str) -> None:
+                status.write_text(json.dumps({"status": state, "message": message}))
+
+            def corrupt(self) -> None:
+                status.write_text("}not json{")
+
+            def poll(self) -> dict:
+                with urlopen(f"http://127.0.0.1:{port}/progress", timeout=5) as r:
+                    return json.loads(r.read())
+
+        yield Progress()
+    finally:
+        proc.kill()
+        proc.wait(timeout=5)
+
+
+def test_elapsed_advances_between_publishes(progress):
+    """The clock is stamped per request, not frozen at the last publish.
+
+    Stages are minutes apart during a real update, so a value written into
+    the status file would sit still through exactly the long waits this line
+    exists to disprove.
+    """
+    progress.publish("running", "Updating code and dependencies")
+    first = progress.poll()
+    time.sleep(1.2)
+    second = progress.poll()
+
+    assert first["status"] == "running"
+    assert second["message"] == first["message"] == "Updating code and dependencies"
+    assert second["elapsed_seconds"] > first["elapsed_seconds"]
+
+
+def test_every_state_carries_a_clock(progress):
+    """Including the stage-less running state posix publishes at window open."""
+    for state, message in [
+        ("running", ""),
+        ("running", "Installing the new app"),
+        ("done", ""),
+        ("manual", "Reopen Hermes to finish."),
+        ("error", "Update failed."),
+    ]:
+        progress.publish(state, message)
+        served = progress.poll()
+
+        assert served["status"] == state
+        assert served["message"] == message
+        assert served["elapsed_seconds"] >= 0
+
+
+def test_unreadable_status_still_serves_a_running_state(progress):
+    """A window frozen on its last frame is the bug being fixed here."""
+    progress.corrupt()
+    served = progress.poll()
+
+    assert served["status"] == "running"
+    assert served["elapsed_seconds"] >= 0
+
+
+# ── posix.sh: the stages it publishes at its own gates ─────────────────────
+
+# Stands in for `hermes update`, and reports the stage that was on screen
+# while it ran -- the update child is the only thing that can observe the
+# window's state at the exact moment of the longest wait in the hand-off.
+FAKE_HERMES = """#!/bin/bash
+n="$(cat "$HERMES_TEST_CALLS" 2>/dev/null || echo 0)"; n=$((n + 1))
+printf '%s' "$n" > "$HERMES_TEST_CALLS"
+for f in "$TMPDIR"/hermes-update-status.[0-9]*; do
+  case "$f" in *.tmp) continue ;; esac
+  cp "$f" "$HERMES_TEST_CAPTURE.$n" 2>/dev/null
+done
+exit "$(cat "$HERMES_TEST_EXITS.$n" 2>/dev/null || echo 0)"
+"""
+
+
+def _run_handoff(tmp_path, exits: dict[int, int]) -> list[dict]:
+    """Run the real hand-off end to end; return the stage seen at each call."""
+    install_root = tmp_path / "hermes-agent"
+    (install_root / "venv" / "bin").mkdir(parents=True)
+    hermes = install_root / "venv" / "bin" / "hermes"
+    hermes.write_text(FAKE_HERMES)
+    hermes.chmod(0o755)
+
+    capture = tmp_path / "seen"
+    calls = tmp_path / "calls"
+    for call, code in exits.items():
+        (tmp_path / f"exits.{call}").write_text(str(code))
+
+    env = {
+        **os.environ,
+        "TMPDIR": str(tmp_path),
+        "HERMES_TEST_CAPTURE": str(capture),
+        "HERMES_TEST_CALLS": str(calls),
+        "HERMES_TEST_EXITS": str(tmp_path / "exits"),
+    }
+    # The hand-off daemonizes and the launcher exits immediately; the result
+    # file is the orchestrator's own completion signal.
+    subprocess.run(
+        [
+            "/bin/bash",
+            str(SHIM_DIR / "posix.sh"),
+            "--install-root",
+            str(install_root),
+            "--no-ui",
+        ],
+        env=env,
+        timeout=60,
+        check=True,
+    )
+
+    result = tmp_path / ".hermes-update-result.json"
+    deadline = time.monotonic() + 45
+    while time.monotonic() < deadline and not result.exists():
+        time.sleep(0.1)
+    assert result.exists(), "hand-off never wrote its result file"
+
+    seen = sorted(tmp_path.glob("seen.*"), key=lambda p: int(p.suffix[1:]))
+
+    return [json.loads(p.read_text()) for p in seen]
+
+
+@requires_posix_handoff
+def test_update_gate_publishes_its_stage_before_running(tmp_path):
+    """`hermes update` is the longest wait in the hand-off and the one the
+    Discord report sat through; the window must name it while it happens."""
+    stages = _run_handoff(tmp_path, {1: 0})
+
+    assert len(stages) == 1
+    assert stages[0]["status"] == "running"
+    assert stages[0]["message"] == "Updating code and dependencies"
+
+
+@requires_posix_handoff
+def test_retry_gate_publishes_a_distinct_stage(tmp_path):
+    """A failed first attempt doubles the wait -- the second pass must not
+    look like the first one hanging."""
+    stages = _run_handoff(tmp_path, {1: 1, 2: 0})
+
+    assert [s["message"] for s in stages] == [
+        "Updating code and dependencies",
+        "Retrying update",
+    ]
diff --git a/tests/test_desktop_update_windows_progress.py b/tests/test_desktop_update_windows_progress.py
index a03d919df1..d3f67a07e1 100644
--- a/tests/test_desktop_update_windows_progress.py
+++ b/tests/test_desktop_update_windows_progress.py
@@ -1,20 +1,25 @@
-"""Behavioral coverage for quiet Windows Desktop updater progress."""
+"""The Windows hand-off keeps serving progress while its main thread blocks.
+
+windows.ps1 answers /progress from a dedicated runspace precisely so the
+window keeps moving through the long silent stretches (`hermes update`, pip,
+the desktop rebuild) that made an 18-minute update look hung. This drives the
+real script and polls the real listener; the posix half of the same contract
+is covered in test_desktop_update_shim_progress.py.
+"""
 
 from __future__ import annotations
 
 import json
 import os
-from pathlib import Path
 import re
 import shutil
 import subprocess
-import sys
 import time
+from pathlib import Path
 from urllib.request import urlopen
 
 import pytest
 
-
 pytestmark = pytest.mark.windows_only
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
@@ -22,11 +27,11 @@ WINDOWS_UPDATE_PS1 = REPO_ROOT / "scripts" / "desktop-update" / "windows.ps1"
 
 
 def _read_progress(url: str) -> dict[str, object]:
-    with urlopen(f"{url}progress", timeout=2) as response:
+    with urlopen(f"{url}progress", timeout=5) as response:
         return json.loads(response.read().decode("utf-8"))
 
 
-def test_progress_advances_while_update_child_is_silent(tmp_path: Path) -> None:
+def test_progress_advances_while_the_orchestrator_blocks(tmp_path: Path) -> None:
     powershell = shutil.which("powershell.exe")
     assert powershell, "Windows updater tests require Windows PowerShell."
 
@@ -34,9 +39,7 @@ def test_progress_advances_while_update_child_is_silent(tmp_path: Path) -> None:
     env = os.environ.copy()
     env["TEMP"] = str(tmp_path)
     env["TMP"] = str(tmp_path)
-    env["HERMES_SELFTEST_HOLD_SECONDS"] = "3"
-    env["HERMES_SELFTEST_SILENT_CHILD"] = "1"
-    env["HERMES_SELFTEST_PYTHON"] = sys.executable
+    env["HERMES_SELFTEST_HOLD_SECONDS"] = "4"
 
     with output_path.open("wb") as output:
         process = subprocess.Popen(
@@ -56,7 +59,7 @@ def test_progress_advances_while_update_child_is_silent(tmp_path: Path) -> None:
         )
 
     try:
-        deadline = time.monotonic() + 10
+        deadline = time.monotonic() + 20
         shim_url = None
         while time.monotonic() < deadline:
             text = output_path.read_text(encoding="utf-8", errors="replace")
@@ -70,17 +73,20 @@ def test_progress_advances_while_update_child_is_silent(tmp_path: Path) -> None:
 
         assert shim_url, output_path.read_text(encoding="utf-8", errors="replace")
         first = _read_progress(shim_url)
-        time.sleep(1.2)
+        time.sleep(1.5)
         second = _read_progress(shim_url)
 
+        # The stage is whatever the orchestrator last published -- it must
+        # reach the page verbatim and must not churn on its own.
         assert first["status"] == "running"
-        assert first["message"] == "Testing quiet update"
+        assert first["message"]
         assert second["message"] == first["message"]
+        # The main thread is asleep for the whole window above. If elapsed
+        # only moved when the orchestrator published, it would be frozen here
+        # -- which is what a stalled update looks like to the user.
         assert int(second["elapsed_seconds"]) > int(first["elapsed_seconds"])
 
-        assert process.wait(timeout=10) == 0
-        final_output = output_path.read_text(encoding="utf-8", errors="replace")
-        assert "SELF-TEST: silent child exit code: 0" in final_output
+        assert process.wait(timeout=20) == 0
     finally:
         if process.poll() is None:
             process.kill()

From 268615cbb3aad3a36aec37151f5c6ef1652494e4 Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 19 Aug 2026 13:17:20 -0500
Subject: [PATCH 42/48] test(update): cover the Windows shim self-lock class

Detection across every launch variant (argv[0], the zipapp __main__.py, the
main-module spec origin, the ancestor chain) plus the venv scoping that keeps
an unrelated hermes.exe from triggering a hand-off; the re-exec's argv, env
marker, loop guard and both fall-through paths; the pending-rename filter;
and the venv/.venv layout split.

Retires the reboot-deferred quarantine assertion along with the fallback.

Launch-variant cases from #89970 by @Akloenx123, pending-rename cases from
#88121 by @fangliquanflq.
---
 .../test_update_concurrent_quarantine.py      |  34 +--
 .../hermes_cli/test_update_shim_self_lock.py  | 224 ++++++++++++++++++
 2 files changed, 237 insertions(+), 21 deletions(-)
 create mode 100644 tests/hermes_cli/test_update_shim_self_lock.py

diff --git a/tests/hermes_cli/test_update_concurrent_quarantine.py b/tests/hermes_cli/test_update_concurrent_quarantine.py
index 784c9f9bc4..7c6aef5f5f 100644
--- a/tests/hermes_cli/test_update_concurrent_quarantine.py
+++ b/tests/hermes_cli/test_update_concurrent_quarantine.py
@@ -139,7 +139,7 @@ def test_detect_concurrent_parents_call_robust_to_one_bad_hop(_winp, tmp_path):
 
 
 # ---------------------------------------------------------------------------
-# _quarantine_running_hermes_exe — retry + reboot-deferred fallback
+# _quarantine_running_hermes_exe — retry, then report
 # ---------------------------------------------------------------------------
 
 
@@ -160,36 +160,26 @@ def test_quarantine_succeeds_first_attempt(_winp, tmp_path):
 
 
 @patch.object(cli_main, "_is_windows", return_value=True)
-def test_quarantine_falls_back_to_reboot_schedule(_winp, tmp_path, capsys, monkeypatch):
-    """When every retry fails, we schedule via MoveFileEx and warn helpfully."""
+def test_quarantine_reports_a_lock_it_cannot_break(_winp, tmp_path, capsys, monkeypatch):
+    """Every retry failed: name the likely culprits, queue nothing for reboot."""
     shim = tmp_path / "hermes.exe"
     shim.write_bytes(b"locked")
 
     def always_fails(self, target):
         raise OSError(32, "The process cannot access the file (simulated lock)")
 
-    scheduled_calls: list[tuple[Path, Path]] = []
-
-    def fake_schedule(s: Path, q: Path) -> bool:
-        scheduled_calls.append((s, q))
-        return True
-
     monkeypatch.setattr(cli_main, "_hermes_exe_shims", lambda d: [shim])
-    with patch.object(Path, "rename", always_fails), patch.object(
-        cli_main, "_schedule_replace_on_reboot", fake_schedule
-    ), patch("time.sleep", lambda *_a, **_k: None):
+    with patch.object(Path, "rename", always_fails), patch(
+        "time.sleep", lambda *_a, **_k: None
+    ):
         pairs = cli_main._quarantine_running_hermes_exe(tmp_path)
 
-    captured = capsys.readouterr().out
+    captured = capsys.readouterr().out.lower()
 
-    # The reboot-deferred path was used.
-    assert scheduled_calls and scheduled_calls[0][0] == shim
-    # It is NOT added to the returned roll-back list (the issue calls this
-    # out — don't undo a deferred operation).
     assert pairs == []
-    # The user got a clear message, not raw [WinError 32].
-    assert "scheduled" in captured.lower()
-    assert "reboot" in captured.lower()
+    # A clear message, not raw [WinError 32], and no reboot promise we can't keep.
+    assert "could not quarantine" in captured
+    assert "reboot" not in captured
 
 
 
@@ -258,7 +248,9 @@ def test_pause_windows_gateways_for_update_stops_profile_and_unmapped_pids(
     assert waited_for == [101]
     assert terminated == [(202, True)]
 
-    marker = json.loads((profile_home / ".gateway-planned-stop.json").read_text())
+    marker = json.loads(
+        (profile_home / ".gateway-planned-stop.json").read_text(encoding="utf-8")
+    )
     assert marker["target_pid"] == 101
     assert marker["stopper_pid"] == os.getpid()
 
diff --git a/tests/hermes_cli/test_update_shim_self_lock.py b/tests/hermes_cli/test_update_shim_self_lock.py
new file mode 100644
index 0000000000..5bcc417bdc
--- /dev/null
+++ b/tests/hermes_cli/test_update_shim_self_lock.py
@@ -0,0 +1,224 @@
+"""The Windows console-shim update self-lock (#88838, #89599, #86093).
+
+``venv\\Scripts\\hermes.exe`` is a launcher that runs the interpreter with the
+shim itself as its script, keeping the file open without FILE_SHARE_DELETE for
+the whole command. An update started that way must therefore replace a file it
+is holding, which Windows refuses — so ``hermes update`` re-runs itself under
+``venv\\Scripts\\python.exe`` before touching anything.
+
+``_is_windows`` is patched so these paths are exercised on any host.
+"""
+
+from __future__ import annotations
+
+import sys
+import types
+from pathlib import Path
+
+import pytest
+
+from hermes_cli import main as cli_main
+
+SHIM_NAMES = ["hermes.exe", "hermes-agent.exe", "hermes-acp.exe", "hermes-gateway.exe"]
+
+
+@pytest.fixture
+def venv(tmp_path, monkeypatch):
+    """A Windows-shaped project venv with a python.exe, wired into main."""
+    scripts = tmp_path / "venv" / "Scripts"
+    scripts.mkdir(parents=True)
+    (scripts / "python.exe").write_bytes(b"")
+    monkeypatch.setattr(cli_main, "_is_windows", lambda: True)
+    monkeypatch.setattr(cli_main, "_venv_scripts_dir", lambda: scripts)
+    monkeypatch.setattr(sys, "argv", ["hermes", "update"])
+    monkeypatch.delenv(cli_main._UPDATE_REEXEC_ENV, raising=False)
+    _fake_psutil(monkeypatch, [])
+    return scripts
+
+
+def _fake_psutil(monkeypatch, ancestor_exes: list[str]):
+    """Stand in for psutil with a fixed self+ancestor executable chain."""
+
+    class _Proc:
+        def __init__(self, exe=None):
+            self._exe = exe
+
+        def exe(self):
+            if self._exe is None:
+                raise OSError("exe unavailable")
+            return self._exe
+
+        def parents(self):
+            return [_Proc(exe) for exe in ancestor_exes]
+
+    monkeypatch.setitem(sys.modules, "psutil", types.SimpleNamespace(Process=_Proc))
+
+
+def _capture_popen(monkeypatch, raises: Exception | None = None):
+    calls = []
+
+    def fake_popen(cmd, env=None, **kwargs):
+        if raises is not None:
+            raise raises
+        calls.append((list(cmd), dict(env or {})))
+        return object()
+
+    monkeypatch.setattr(cli_main.subprocess, "Popen", fake_popen)
+    return calls
+
+
+# ---------------------------------------------------------------------------
+# Shim detection
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize("shim_name", SHIM_NAMES)
+def test_detects_shim_as_argv0(venv, monkeypatch, shim_name):
+    monkeypatch.setattr(sys, "argv", [str(venv / shim_name), "update"])
+    assert cli_main._windows_shim_in_process_chain() == venv / shim_name
+
+
+def test_detects_shim_from_zipapp_main_py(venv, monkeypatch):
+    """runpy/zipapp launches put ``<shim>\\__main__.py`` in argv[0]."""
+    monkeypatch.setattr(sys, "argv", [str(venv / "hermes.exe" / "__main__.py")])
+    assert cli_main._windows_shim_in_process_chain() == venv / "hermes.exe"
+
+
+def test_detects_shim_from_main_module_spec_origin(venv, monkeypatch):
+    fake_main = types.SimpleNamespace(
+        __file__=None,
+        __spec__=types.SimpleNamespace(origin=str(venv / "hermes.exe")),
+    )
+    monkeypatch.setitem(sys.modules, "__main__", fake_main)
+    assert cli_main._windows_shim_in_process_chain() == venv / "hermes.exe"
+
+
+def test_detects_shim_in_ancestor_chain(venv, monkeypatch):
+    """The launcher is usually a separate parent process, not argv[0]."""
+    _fake_psutil(monkeypatch, [str(venv / "hermes.exe")])
+    assert cli_main._windows_shim_in_process_chain() == venv / "hermes.exe"
+
+
+def test_ignores_hermes_exe_outside_the_project_venv(venv, monkeypatch, tmp_path):
+    """A shim from some other install must never trigger a re-exec."""
+    other = tmp_path / "other" / "Scripts"
+    other.mkdir(parents=True)
+    monkeypatch.setattr(sys, "argv", [str(other / "hermes.exe"), "update"])
+    _fake_psutil(monkeypatch, [str(other / "hermes.exe")])
+    assert cli_main._windows_shim_in_process_chain() is None
+
+
+def test_no_shim_off_windows(venv, monkeypatch):
+    monkeypatch.setattr(cli_main, "_is_windows", lambda: False)
+    monkeypatch.setattr(sys, "argv", [str(venv / "hermes.exe"), "update"])
+    assert cli_main._windows_shim_in_process_chain() is None
+
+
+def test_no_shim_without_a_venv(venv, monkeypatch):
+    monkeypatch.setattr(cli_main, "_venv_scripts_dir", lambda: None)
+    monkeypatch.setattr(sys, "argv", [str(venv / "hermes.exe"), "update"])
+    assert cli_main._windows_shim_in_process_chain() is None
+
+
+# ---------------------------------------------------------------------------
+# Re-exec hand-off
+# ---------------------------------------------------------------------------
+
+
+def test_reexec_runs_same_args_under_venv_python(venv, monkeypatch, capsys):
+    monkeypatch.setattr(sys, "argv", [str(venv / "hermes.exe"), "update", "--yes"])
+    calls = _capture_popen(monkeypatch)
+
+    assert cli_main._reexec_update_off_windows_shim() is True
+    cmd, env = calls[0]
+    assert cmd == [
+        str(venv / "python.exe"), "-m", "hermes_cli.main", "update", "--yes",
+    ]
+    assert env[cli_main._UPDATE_REEXEC_ENV] == "1"
+    assert "under the venv Python" in capsys.readouterr().out
+
+
+def test_reexec_does_not_recurse(venv, monkeypatch):
+    monkeypatch.setattr(sys, "argv", [str(venv / "hermes.exe"), "update"])
+    monkeypatch.setenv(cli_main._UPDATE_REEXEC_ENV, "1")
+    calls = _capture_popen(monkeypatch)
+
+    assert cli_main._reexec_update_off_windows_shim() is False
+    assert calls == []
+
+
+def test_reexec_skipped_when_not_launched_from_a_shim(venv, monkeypatch):
+    calls = _capture_popen(monkeypatch)
+    assert cli_main._reexec_update_off_windows_shim() is False
+    assert calls == []
+
+
+def test_reexec_falls_through_when_venv_python_is_missing(venv, monkeypatch, capsys):
+    (venv / "python.exe").unlink()
+    monkeypatch.setattr(sys, "argv", [str(venv / "hermes.exe"), "update"])
+
+    assert cli_main._reexec_update_off_windows_shim() is False
+    assert "-m hermes_cli.main update" in capsys.readouterr().out
+
+
+def test_reexec_falls_through_when_spawn_fails(venv, monkeypatch, capsys):
+    monkeypatch.setattr(sys, "argv", [str(venv / "hermes.exe"), "update"])
+    _capture_popen(monkeypatch, raises=OSError("no exec"))
+
+    assert cli_main._reexec_update_off_windows_shim() is False
+    assert "-m hermes_cli.main update" in capsys.readouterr().out
+
+
+# ---------------------------------------------------------------------------
+# Reboot-deferred renames
+# ---------------------------------------------------------------------------
+
+
+def test_reboot_deferred_rename_fallback_is_gone():
+    """MOVEFILE_DELAY_UNTIL_REBOOT needed elevation and freed nothing."""
+    assert not hasattr(cli_main, "_schedule_replace_on_reboot")
+
+
+def test_pending_rename_filter_drops_only_our_shim_pairs():
+    shims = [Path(r"C:\hermes\venv\Scripts\hermes.exe")]
+    entries = [
+        r"\??\C:\other\thing.dll", r"!\??\C:\other\thing.dll.bak",
+        r"\??\C:\hermes\venv\Scripts\hermes.exe",
+        r"!\??\C:\hermes\venv\Scripts\hermes.exe.old.1755624735000",
+    ]
+    kept, removed = cli_main._filter_pending_shim_renames(entries, shims)
+    assert removed == 1
+    assert kept == entries[:2]
+
+
+def test_pending_rename_filter_keeps_a_shim_pair_with_a_foreign_target():
+    shims = [Path(r"C:\hermes\venv\Scripts\hermes.exe")]
+    entries = [
+        r"\??\C:\hermes\venv\Scripts\hermes.exe", r"!\??\C:\somewhere\else.exe",
+    ]
+    kept, removed = cli_main._filter_pending_shim_renames(entries, shims)
+    assert removed == 0
+    assert kept == entries
+
+
+def test_pending_rename_filter_preserves_a_trailing_delete_entry():
+    """A bare source with an empty target is a scheduled delete, not a pair."""
+    entries = [r"\??\C:\other\thing.dll", "", r"\??\C:\other\orphan.dll"]
+    kept, removed = cli_main._filter_pending_shim_renames(entries, [])
+    assert removed == 0
+    assert kept == entries
+
+
+# ---------------------------------------------------------------------------
+# venv layout
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize("venv_name", ["venv", ".venv"])
+def test_venv_scripts_dir_finds_both_layouts(tmp_path, monkeypatch, venv_name):
+    """uv writes .venv; our installers write venv. Both must resolve (#79542)."""
+    scripts = tmp_path / venv_name / "Scripts"
+    scripts.mkdir(parents=True)
+    monkeypatch.setattr(cli_main, "PROJECT_ROOT", tmp_path)
+    monkeypatch.setattr(cli_main, "_is_windows", lambda: True)
+    assert cli_main._venv_scripts_dir() == scripts

From 73243b0d2e4c5b2a1193730c6e6cc6c4329efed8 Mon Sep 17 00:00:00 2001
From: Yingliang Zhang <zhangyingliang@outlook.com>
Date: Sun, 2 Aug 2026 09:20:39 +0800
Subject: [PATCH 43/48] feat(config): per-provider reasoning_echo opt-in for
 custom providers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add model.reasoning_echo (default false) and per-fallback-entry
reasoning_echo to preserve assistant reasoning_content when
replaying history to custom providers and OpenAI-compatible gateways
that proxy thinking-mode models (Kimi K3, GLM-5.2, DeepSeek, etc.)
but are not matched by the built-in host-based _REASONING_ECHO_RULES.

The flag is per-active-provider, not a global toggle:
- Primary: read from model.reasoning_echo at init and switch_model
- Fallback: set by try_activate_fallback from the fallback entry
- Restore: restore_primary_runtime copies the switch_model snapshot

Unlike PR #76019 global agent.reasoning_echo toggle, the
per-provider flag travels with the active provider — falling back to
a strict provider (Mistral, Groq, Cerebras) correctly strips
reasoning_content even when the primary had the flag enabled,
because the flag is False for the strict fallback.

Complements PR #27361 (dynamic detection) which fires after the first
API response; this PR covers turn-1 and history-replay-on-fresh-session
where dynamic detection has not fired yet.

Closes #76018
Refs: #27297, #27361, #76019

Signed-off-by: Yingliang Zhang <zhangyingliang@outlook.com>
---
 agent/agent_init.py                           |  10 +
 agent/agent_runtime_helpers.py                |  12 ++
 agent/chat_completion_helpers.py              |   4 +
 hermes_cli/config_defaults.py                 |  14 ++
 run_agent.py                                  |  26 +++
 .../agent/test_message_sanitization_policy.py | 184 ++++++++++++++++++
 6 files changed, 250 insertions(+)

diff --git a/agent/agent_init.py b/agent/agent_init.py
index 938e13f612..155ddba578 100644
--- a/agent/agent_init.py
+++ b/agent/agent_init.py
@@ -913,6 +913,16 @@ def init_agent(
     # Model response configuration
     agent.max_tokens = max_tokens  # None = use model default
     agent.reasoning_config = reasoning_config  # None = use default (medium for OpenRouter)
+    # Per-provider reasoning_content echo opt-in (see _reasoning_echo_opt_in).
+    # Read once at init; switch_model / try_activate_fallback / restore
+    # keep it in sync with the active provider.
+    try:
+        from hermes_cli.config import load_config_readonly
+        agent._reasoning_echo_flag = bool(
+            (load_config_readonly().get("model") or {}).get("reasoning_echo")
+        )
+    except Exception:
+        agent._reasoning_echo_flag = False
     agent.service_tier = service_tier
     agent.request_overrides = dict(request_overrides or {})
     agent.prefill_messages = prefill_messages or []  # Prefilled conversation turns
diff --git a/agent/agent_runtime_helpers.py b/agent/agent_runtime_helpers.py
index 79cfe58135..451b3a0927 100644
--- a/agent/agent_runtime_helpers.py
+++ b/agent/agent_runtime_helpers.py
@@ -1349,6 +1349,7 @@ def try_recover_primary_transport(
         if hasattr(agent, "_transport_cache"):
             agent._transport_cache.clear()
         agent.api_key = rt["api_key"]
+        agent._reasoning_echo_flag = rt.get("reasoning_echo_flag", False)
 
         if agent.api_mode == "anthropic_messages":
             from agent.anthropic_adapter import build_anthropic_client
@@ -1579,6 +1580,7 @@ def restore_primary_runtime(agent) -> bool:
         if hasattr(agent, "_transport_cache"):
             agent._transport_cache.clear()
         agent.api_key = rt["api_key"]
+        agent._reasoning_echo_flag = rt.get("reasoning_echo_flag", False)
         agent._client_kwargs = dict(rt["client_kwargs"])
         agent._use_prompt_caching = rt["use_prompt_caching"]
         # Default to native layout when the restored snapshot predates the
@@ -2685,6 +2687,15 @@ def switch_model(agent, new_model, new_provider, api_key='', base_url='', api_mo
         agent.model = new_model
         agent.provider = new_provider
         agent.requested_provider = new_provider
+        # Re-read reasoning_echo from config so the flag reflects the new
+        # primary model's setting (see _reasoning_echo_opt_in).
+        try:
+            from hermes_cli.config import load_config_readonly
+            agent._reasoning_echo_flag = bool(
+                (load_config_readonly().get("model") or {}).get("reasoning_echo")
+            )
+        except Exception:
+            agent._reasoning_echo_flag = False
         # Use the new base_url when provided. When it's empty AND the
         # provider is actually changing, do NOT fall back to the current
         # (old provider's) URL — that silently pairs the new provider label
@@ -2970,6 +2981,7 @@ def switch_model(agent, new_model, new_provider, api_key='', base_url='', api_mo
         "use_prompt_caching": agent._use_prompt_caching,
         "use_native_cache_layout": agent._use_native_cache_layout,
         "reasoning_config": dict(agent.reasoning_config) if getattr(agent, "reasoning_config", None) else None,
+        "reasoning_echo_flag": getattr(agent, "_reasoning_echo_flag", False),
         "compressor_model": getattr(_cc, "model", agent.model) if _cc else agent.model,
         "compressor_base_url": getattr(_cc, "base_url", agent.base_url) if _cc else agent.base_url,
         "compressor_api_key": getattr(_cc, "api_key", "") if _cc else "",
diff --git a/agent/chat_completion_helpers.py b/agent/chat_completion_helpers.py
index 4805362731..7af486dc5b 100644
--- a/agent/chat_completion_helpers.py
+++ b/agent/chat_completion_helpers.py
@@ -2652,6 +2652,10 @@ def try_activate_fallback(agent, reason: "FailoverReason | None" = None) -> bool
         agent.requested_provider = fb_provider
         agent.base_url = fb_base_url
         agent.api_mode = fb_api_mode
+        # Per-provider reasoning_content echo opt-in (see _reasoning_echo_opt_in).
+        # Read from the fallback entry so the flag travels with the active
+        # provider; restore_primary_runtime will revert it from the snapshot.
+        agent._reasoning_echo_flag = bool(fb.get("reasoning_echo", False))
         if hasattr(agent, "_transport_cache"):
             agent._transport_cache.clear()
         agent._fallback_activated = True
diff --git a/hermes_cli/config_defaults.py b/hermes_cli/config_defaults.py
index 29ae25d7f7..e55b3d923d 100644
--- a/hermes_cli/config_defaults.py
+++ b/hermes_cli/config_defaults.py
@@ -328,6 +328,20 @@ DEFAULT_CONFIG = {
         # matches a key in this dict.
         # Edit directly in config.yaml (no CLI support due to dots in keys).
         "reasoning_overrides": {},
+
+        # Per-provider opt-in to preserve assistant ``reasoning_content``
+        # when replaying history.  The built-in echo families (DeepSeek,
+        # Kimi/Moonshot, Xiaomi MiMo) are auto-detected by provider name
+        # and base-URL host.  Custom providers and OpenAI-compatible
+        # gateways that proxy those same models (or other thinking-mode
+        # backends) are not covered by the host-based rules.
+        #
+        # Set ``reasoning_echo: true`` on a ``model:`` entry (primary) or a
+        # ``fallback_providers:`` entry (per-fallback) to preserve
+        # ``reasoning_content`` on replay for that provider only.  Default
+        # ``false`` keeps the historical strict-provider behavior (Mistral,
+        # Groq, Cerebras reject the field with HTTP 400).
+        "reasoning_echo": False,
     },
 
     "terminal": {
diff --git a/run_agent.py b/run_agent.py
index b4308f27a6..548c9953d8 100644
--- a/run_agent.py
+++ b/run_agent.py
@@ -7760,10 +7760,36 @@ class AIAgent:
             self._needs_deepseek_tool_reasoning()
             or self._needs_kimi_tool_reasoning()
             or self._needs_mimo_tool_reasoning()
+            or self._reasoning_echo_opt_in()
         )
         self._thinking_pad_cache = (key, result)
         return result
 
+    def _reasoning_echo_opt_in(self) -> bool:
+        """Return True when the user has opted in to ``reasoning_content``
+        echo-back for the *current* provider via config.
+
+        This covers custom providers and OpenAI-compatible gateways that
+        proxy thinking-mode models (e.g. a reverse proxy fronting Kimi K3
+        or GLM-5.2) but are not matched by the built-in host-based
+        ``_REASONING_ECHO_RULES`` (DeepSeek / Kimi / MiMo).
+
+        The flag is per-active-provider:
+
+        * **Primary** — read from ``model.reasoning_echo`` in config.yaml
+          at agent init and on ``switch_model()``.
+        * **Fallback** — set by ``try_activate_fallback()`` from the
+          fallback entry's ``reasoning_echo`` field.
+        * **Restore** — ``restore_primary_runtime()`` copies the snapshot
+          saved by ``switch_model()``.
+
+        Unlike a global toggle, this flag travels with the active
+        provider, so falling back to a strict provider (Mistral, Groq,
+        Cerebras) correctly strips ``reasoning_content`` even when the
+        primary had the flag enabled.
+        """
+        return bool(getattr(self, "_reasoning_echo_flag", False))
+
     def _needs_kimi_tool_reasoning(self) -> bool:
         """Return True when the current provider is Kimi / Moonshot thinking mode.
 
diff --git a/tests/agent/test_message_sanitization_policy.py b/tests/agent/test_message_sanitization_policy.py
index b363b73ff2..683d2d8df0 100644
--- a/tests/agent/test_message_sanitization_policy.py
+++ b/tests/agent/test_message_sanitization_policy.py
@@ -294,3 +294,187 @@ class TestReapplyReasoningEcho:
         assert reapply_reasoning_echo(msgs, True) == 0
         reapply_reasoning_echo(msgs, False)
         assert reapply_reasoning_echo(msgs, False) == 0
+
+
+# ---------------------------------------------------------------------------
+# Per-provider reasoning_echo config opt-in — preserves reasoning_content
+# on replay for custom providers / OpenAI-compatible gateways that proxy
+# thinking-mode models but are not matched by the built-in host-based
+# _REASONING_ECHO_RULES (DeepSeek / Kimi / MiMo).
+#
+# The flag is per-active-provider:
+#   - Primary: read from ``model.reasoning_echo`` in config at init / switch_model
+#   - Fallback: set by try_activate_fallback from the fallback entry's field
+#   - Restore: restore_primary_runtime copies the snapshot saved by switch_model
+#
+# Unlike a global toggle, the flag travels with the active provider, so
+# falling back to a strict provider (Mistral, Groq, Cerebras) correctly
+# strips reasoning_content even when the primary had the flag enabled.
+# ---------------------------------------------------------------------------
+
+class TestPerProviderReasoningEcho:
+    """Verify the per-provider reasoning_echo opt-in flag."""
+
+    def _make_agent(self, reasoning_echo_flag=False, provider="custom",
+                    model="my-model", base_url="https://gw.example.com/v1"):
+        """Build a minimal AIAgent-shaped object without full init."""
+        from run_agent import AIAgent
+        agent = object.__new__(AIAgent)
+        agent.provider = provider
+        agent.model = model
+        agent.base_url = base_url
+        agent._base_url_lower = base_url.lower()
+        agent._thinking_pad_cache = None
+        agent._reasoning_echo_flag = reasoning_echo_flag
+        agent._needs_deepseek_tool_reasoning = lambda: False
+        agent._needs_kimi_tool_reasoning = lambda: False
+        agent._needs_mimo_tool_reasoning = lambda: False
+        return agent
+
+    def test_default_false_strips_for_custom_provider(self):
+        """Default (flag=False): a custom gateway is NOT an echo family,
+        so reasoning_content is stripped — historical behavior."""
+        agent = self._make_agent(reasoning_echo_flag=False)
+        assert agent._needs_thinking_reasoning_pad() is False
+        assert agent._reasoning_echo_opt_in() is False
+
+    def test_opt_in_preserves_for_custom_provider(self):
+        """Flag on: even a non-echo-family custom gateway keeps
+        reasoning_content on replay."""
+        agent = self._make_agent(reasoning_echo_flag=True)
+        assert agent._needs_thinking_reasoning_pad() is True
+        assert agent._reasoning_echo_opt_in() is True
+
+    def test_opt_in_does_not_replace_family_detection(self):
+        """Kimi-coding family still gets echo-back regardless of the flag."""
+        agent = self._make_agent(
+            reasoning_echo_flag=False,
+            provider="kimi-coding",
+            model="t9s/kimi-k3",
+        )
+        agent._needs_kimi_tool_reasoning = lambda: True
+        assert agent._needs_thinking_reasoning_pad() is True
+
+    def test_opt_in_additive_with_family_detection(self):
+        """Flag on AND family match: both paths agree, still True."""
+        agent = self._make_agent(
+            reasoning_echo_flag=True,
+            provider="deepseek",
+            model="deepseek-v4-pro",
+        )
+        agent._needs_deepseek_tool_reasoning = lambda: True
+        assert agent._needs_thinking_reasoning_pad() is True
+
+    def test_strict_fallback_strips_despite_primary_opt_in(self):
+        """Primary has flag=True, fallback switches to a strict provider.
+        The fallback reconciling path (reapply_reasoning_echo_for_provider)
+        uses _needs_thinking_reasoning_pad which checks the *current*
+        provider's flag — strict providers have flag=False, so the field
+        is stripped (no HTTP 400)."""
+        agent = self._make_agent(reasoning_echo_flag=True)  # primary opt-in
+        # Simulate fallback to a strict provider
+        agent.provider = "mistral"
+        agent.model = "mistral-large"
+        agent.base_url = "https://api.mistral.ai/v1"
+        agent._base_url_lower = "https://api.mistral.ai/v1"
+        agent._thinking_pad_cache = None  # invalidate per-provider cache
+        agent._reasoning_echo_flag = False  # fallback entry has no opt-in
+        assert agent._needs_thinking_reasoning_pad() is False
+        # End-to-end: reapply_reasoning_echo strips the field
+        from agent.agent_runtime_helpers import reapply_reasoning_echo_for_provider
+        api_msgs = [
+            {"role": "user", "content": "hello"},
+            {"role": "assistant", "content": "hi", "reasoning_content": "thoughts"},
+            {"role": "assistant", "content": "hi2", "reasoning_content": " "},
+            {"role": "user", "content": "bye"},
+        ]
+        changed = reapply_reasoning_echo_for_provider(agent, api_msgs)
+        assert changed == 2
+        for m in api_msgs:
+            if m["role"] == "assistant":
+                assert "reasoning_content" not in m
+
+    def test_fallback_opt_in_preserves_reasoning(self):
+        """Fallback to a custom provider with reasoning_echo=True:
+        the field is preserved/re-padded."""
+        agent = self._make_agent(reasoning_echo_flag=False)  # primary no opt-in
+        # Simulate fallback to a custom provider with opt-in
+        agent.provider = "custom"
+        agent.model = "t9s/kimi-k3"
+        agent.base_url = "https://gw.example.com/v1"
+        agent._base_url_lower = "https://gw.example.com/v1"
+        agent._thinking_pad_cache = None
+        agent._reasoning_echo_flag = True  # fallback entry has opt-in
+        assert agent._needs_thinking_reasoning_pad() is True
+        # End-to-end: reapply_reasoning_echo re-pads
+        from agent.agent_runtime_helpers import reapply_reasoning_echo_for_provider
+        api_msgs = [
+            {"role": "user", "content": "hello"},
+            {"role": "assistant", "content": "hi"},  # no reasoning_content
+            {"role": "user", "content": "bye"},
+        ]
+        changed = reapply_reasoning_echo_for_provider(agent, api_msgs)
+        assert changed == 1
+        assert api_msgs[1].get("reasoning_content") == " "
+
+    def test_restore_primary_reverts_flag(self):
+        """After fallback, restore_primary_runtime reverts the flag
+        from the snapshot saved by switch_model."""
+        from run_agent import AIAgent
+        agent = object.__new__(AIAgent)
+        agent._reasoning_echo_flag = True  # primary had opt-in
+        agent._fallback_activated = True
+        agent._rate_limited_until = 0
+        agent._primary_runtime = {
+            "model": "glm-5.2",
+            "provider": "custom",
+            "requested_provider": "custom",
+            "base_url": "https://gw.example.com/v1",
+            "api_mode": "chat_completions",
+            "api_key": "sk-test",
+            "client_kwargs": {"api_key": "sk-test", "base_url": "https://gw.example.com/v1"},
+            "use_prompt_caching": True,
+            "use_native_cache_layout": False,
+            "reasoning_echo_flag": True,  # snapshot saved by switch_model
+        }
+        agent._transport_cache = {}
+        agent.client = None
+        agent._client_kwargs = {"api_key": "sk-fallback", "base_url": "https://fallback.com/v1"}
+        agent._use_prompt_caching = False
+        agent._use_native_cache_layout = False
+        agent.api_mode = "chat_completions"
+        agent.api_key = "sk-fallback"
+        agent.model = "fallback-model"
+        agent.provider = "fallback-provider"
+        agent.requested_provider = "fallback-provider"
+        agent.base_url = "https://fallback.com/v1"
+        agent.context_compressor = None
+        agent._config_context_length = None
+
+        # Simulate: fallback set the flag to False
+        agent._reasoning_echo_flag = False
+
+        from agent.agent_runtime_helpers import restore_primary_runtime
+        restore_primary_runtime(agent)
+
+        # Flag should be restored from snapshot
+        assert agent._reasoning_echo_flag is True
+        assert agent.model == "glm-5.2"
+
+    def test_apply_policy_preserves_with_opt_in(self):
+        """apply_reasoning_content_policy preserves reasoning_content
+        when needs_thinking_pad is True (via opt-in)."""
+        from agent.message_sanitization import apply_reasoning_content_policy
+        source = {"role": "assistant", "content": "hi", "reasoning_content": "my thoughts"}
+        api_msg = {"role": "assistant", "content": "hi"}
+        apply_reasoning_content_policy(source, api_msg, needs_thinking_pad=True)
+        assert api_msg["reasoning_content"] == "my thoughts"
+
+    def test_apply_policy_strips_without_opt_in(self):
+        """apply_reasoning_content_policy strips reasoning_content
+        when needs_thinking_pad is False (no opt-in, not echo family)."""
+        from agent.message_sanitization import apply_reasoning_content_policy
+        source = {"role": "assistant", "content": "hi", "reasoning_content": "my thoughts"}
+        api_msg = {"role": "assistant", "content": "hi"}
+        apply_reasoning_content_policy(source, api_msg, needs_thinking_pad=False)
+        assert "reasoning_content" not in api_msg

From 663fa68cd43486a29c783481c9e80ad6255e0fda Mon Sep 17 00:00:00 2001
From: Yingliang Zhang <zhangyingliang@outlook.com>
Date: Sun, 2 Aug 2026 09:48:47 +0800
Subject: [PATCH 44/48] fix: add reasoning_echo_flag to init snapshot and
 switch rollback
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Address review feedback on PR #76503:

1. Init-time primary snapshot (agent_init.py:2756) was missing
   reasoning_echo_flag — after fallback recovery the flag was
   restored as False even when model.reasoning_echo: true was set.

2. Switch transaction snapshot (agent_runtime_helpers.py:2284) was
   missing _reasoning_echo_flag — a failed client rebuild during
   switch_model would leave the old provider with the new provider
   echo policy.

Both omissions now fixed. No test regressions (56 passed).

Signed-off-by: Yingliang Zhang <zhangyingliang@outlook.com>
---
 agent/agent_init.py            | 1 +
 agent/agent_runtime_helpers.py | 1 +
 2 files changed, 2 insertions(+)

diff --git a/agent/agent_init.py b/agent/agent_init.py
index 155ddba578..da92e6f881 100644
--- a/agent/agent_init.py
+++ b/agent/agent_init.py
@@ -2961,6 +2961,7 @@ def init_agent(
         "client_kwargs": dict(agent._client_kwargs),
         "use_prompt_caching": agent._use_prompt_caching,
         "use_native_cache_layout": agent._use_native_cache_layout,
+        "reasoning_echo_flag": getattr(agent, "_reasoning_echo_flag", False),
         # Context engine state that _try_activate_fallback() overwrites.
         # Use getattr for model/base_url/api_key/provider since plugin
         # engines may not have these (they're ContextCompressor-specific).
diff --git a/agent/agent_runtime_helpers.py b/agent/agent_runtime_helpers.py
index 451b3a0927..bcb1cc3a04 100644
--- a/agent/agent_runtime_helpers.py
+++ b/agent/agent_runtime_helpers.py
@@ -2654,6 +2654,7 @@ def switch_model(agent, new_model, new_provider, api_key='', base_url='', api_mo
             "_anthropic_base_url",
             "_is_anthropic_oauth",
             "_config_context_length",
+            "_reasoning_echo_flag",
         )
     }
     # _client_kwargs is a dict — snapshot a shallow copy so mutating the

From 4ee8a9a169c74253ca37a4166b739fac2052b0a8 Mon Sep 17 00:00:00 2001
From: Caleb DeLeeuw <caleb.deleeuw@gmail.com>
Date: Tue, 4 Aug 2026 07:25:26 -0700
Subject: [PATCH 45/48] test: production-shape resolver + init-read coverage
 for reasoning_echo

Salvaged from #73811 per the consolidation triage on #76503, adapted to this
PR's per-active-provider model.reasoning_echo design.

Existing reasoning_echo tests hand-set _reasoning_echo_flag; none drives the
real config path init_agent uses:
    load_config_readonly().get("model").get("reasoning_echo")
which is wrapped in `except Exception: False`, so a broken read would silently
disable the feature untested. This adds a temp-HERMES_HOME test that resolves a
named custom provider via the real resolve_runtime_provider (asserting
provider == "custom"), materializes the flag from a real config file, and
checks reasoning_content is preserved with the flag on and stripped with it off.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ab7R4NizLNbNyQZShtciKg
---
 .../test_reasoning_echo_resolver_e2e.py       | 108 ++++++++++++++++++
 1 file changed, 108 insertions(+)
 create mode 100644 tests/run_agent/test_reasoning_echo_resolver_e2e.py

diff --git a/tests/run_agent/test_reasoning_echo_resolver_e2e.py b/tests/run_agent/test_reasoning_echo_resolver_e2e.py
new file mode 100644
index 0000000000..4373dca4f3
--- /dev/null
+++ b/tests/run_agent/test_reasoning_echo_resolver_e2e.py
@@ -0,0 +1,108 @@
+"""Production-shape coverage for reasoning_echo: real resolver + real init read.
+
+Salvaged from #73811 per the consolidation triage on #76503 and adapted to this
+PR's per-active-provider `model.reasoning_echo` design.
+
+Every existing reasoning_echo test hand-sets `agent._reasoning_echo_flag` (and
+`provider`/`base_url`). None drives the REAL config path that `init_agent` uses:
+
+    agent._reasoning_echo_flag = bool(
+        (load_config_readonly().get("model") or {}).get("reasoning_echo"))
+
+...which is wrapped in `except Exception: False`, so if that read ever breaks the
+feature silently dies and no current test catches it. This test closes that gap.
+
+It also pins the named-custom-provider case: a provider declared under
+`providers.<name>` resolves at runtime to `provider == "custom"` (see
+`hermes_cli/runtime_provider.py`), and the echo flag must still take effect for
+it. A future refactor keying the flag on provider *name* would reintroduce that
+miss; this test is the tripwire.
+
+Uses a temp HERMES_HOME + real `load_config_readonly` (the config cache is
+path-keyed, so this is hermetic) — no live server, no hand-set flag.
+"""
+
+from __future__ import annotations
+
+from hermes_cli.runtime_provider import resolve_runtime_provider
+from agent.agent_runtime_helpers import copy_reasoning_content_for_api
+from run_agent import AIAgent
+
+
+def _write_home(tmp_path, monkeypatch, reasoning_echo: bool):
+    """Point HERMES_HOME at a temp profile declaring a named custom provider."""
+    home = tmp_path / "hermes"
+    home.mkdir()
+    lines = [
+        "model:",
+        "  default: kimi-k3",
+        "  provider: llamacpp-k3",
+    ]
+    if reasoning_echo:
+        lines.append("  reasoning_echo: true")
+    lines += [
+        "providers:",
+        "  llamacpp-k3:",
+        "    base_url: http://127.0.0.1:8098/v1",
+        "    key_env: LLAMACPP_KEY",
+    ]
+    (home / "config.yaml").write_text("\n".join(lines) + "\n")
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    # Drop any path-keyed config cache from a prior test.
+    try:
+        from hermes_cli import config as _cfg
+        for name in ("_CONFIG_CACHE", "_config_cache"):
+            if hasattr(_cfg, name):
+                getattr(_cfg, name).clear()
+    except Exception:
+        pass
+
+
+def _agent_with_init_flag() -> AIAgent:
+    """Build an agent and materialize the echo flag the way init_agent does."""
+    from hermes_cli.config import load_config_readonly
+    agent = object.__new__(AIAgent)
+    agent._reasoning_echo_flag = bool(
+        (load_config_readonly().get("model") or {}).get("reasoning_echo")
+    )
+    agent.provider = "custom"          # what the resolver returns for a named custom provider
+    agent.base_url = "http://127.0.0.1:8098/v1"
+    agent.model = "kimi-k3"
+    agent.verbose_logging = False
+    return agent
+
+
+class TestReasoningEchoResolverE2E:
+    def test_named_custom_provider_resolves_to_custom(self, tmp_path, monkeypatch):
+        """The provider config path really does collapse to provider == 'custom'."""
+        _write_home(tmp_path, monkeypatch, reasoning_echo=True)
+        rt = resolve_runtime_provider(requested="llamacpp-k3")
+        assert rt["provider"] == "custom"
+        assert rt["base_url"].rstrip("/") == "http://127.0.0.1:8098/v1"
+
+    def test_flag_materializes_from_real_config_and_echoes(self, tmp_path, monkeypatch):
+        """reasoning_echo: true -> flag True via the real init read -> reasoning kept."""
+        _write_home(tmp_path, monkeypatch, reasoning_echo=True)
+        agent = _agent_with_init_flag()
+        assert agent._reasoning_echo_flag is True
+        assert agent._reasoning_echo_opt_in() is True
+        assert agent._needs_thinking_reasoning_pad() is True
+
+        source = {"role": "assistant", "content": "calling a tool",
+                  "reasoning_content": "the model's chain of thought"}
+        api_msg = dict(source)
+        copy_reasoning_content_for_api(agent, source, api_msg)
+        assert api_msg["reasoning_content"] == "the model's chain of thought"
+
+    def test_flag_absent_strips(self, tmp_path, monkeypatch):
+        """No reasoning_echo -> flag False -> reasoning_content stripped on replay."""
+        _write_home(tmp_path, monkeypatch, reasoning_echo=False)
+        agent = _agent_with_init_flag()
+        assert agent._reasoning_echo_flag is False
+        assert agent._reasoning_echo_opt_in() is False
+
+        source = {"role": "assistant", "content": "calling a tool",
+                  "reasoning_content": "should be stripped"}
+        api_msg = dict(source)
+        copy_reasoning_content_for_api(agent, source, api_msg)
+        assert "reasoning_content" not in api_msg

From 8d0e3ab8145a8cd38da7b0a21628c2aa74dadaa7 Mon Sep 17 00:00:00 2001
From: a <a@l>
Date: Sat, 8 Aug 2026 12:13:37 +0800
Subject: [PATCH 46/48] chore: map contributor email for yingliang-zhang

---
 contributors/emails/zhangyingliang@outlook.com | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 contributors/emails/zhangyingliang@outlook.com

diff --git a/contributors/emails/zhangyingliang@outlook.com b/contributors/emails/zhangyingliang@outlook.com
new file mode 100644
index 0000000000..7dedf20d94
--- /dev/null
+++ b/contributors/emails/zhangyingliang@outlook.com
@@ -0,0 +1 @@
+yingliang-zhang

From 7e3775de2ec35b21a3f8573056cac0cbd5ac290c Mon Sep 17 00:00:00 2001
From: Yingliang Zhang <zhangyingliang@outlook.com>
Date: Wed, 12 Aug 2026 11:06:31 +0800
Subject: [PATCH 47/48] chore: map contributor emails

---
 contributors/emails/a@l                     | 2 ++
 contributors/emails/caleb.deleeuw@gmail.com | 2 ++
 2 files changed, 4 insertions(+)
 create mode 100644 contributors/emails/a@l
 create mode 100644 contributors/emails/caleb.deleeuw@gmail.com

diff --git a/contributors/emails/a@l b/contributors/emails/a@l
new file mode 100644
index 0000000000..ce1876107f
--- /dev/null
+++ b/contributors/emails/a@l
@@ -0,0 +1,2 @@
+yingliang-zhang
+# attribution repair: commits authored with misconfigured local identity (a@l) belong to yingliang-zhang
diff --git a/contributors/emails/caleb.deleeuw@gmail.com b/contributors/emails/caleb.deleeuw@gmail.com
new file mode 100644
index 0000000000..ed0c1d1bd3
--- /dev/null
+++ b/contributors/emails/caleb.deleeuw@gmail.com
@@ -0,0 +1,2 @@
+SolshineCode
+# salvaged test authored by Caleb DeLeeuw (GitHub: SolshineCode), from fork PR #1 / upstream #73811

From b2057c16856fc01eeb17a40aa65853a68e61b981 Mon Sep 17 00:00:00 2001
From: kshitij kapoor <kshitijk4poor@users.noreply.github.com>
Date: Wed, 19 Aug 2026 23:48:08 +0530
Subject: [PATCH 48/48] refactor: extract duplicated load_config_readonly
 try/except into helper
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The identical 6-line try/except block for reading model.reasoning_echo
from config appeared in both agent_init.py (init) and
agent_runtime_helpers.py (switch_model). Extracted into
AIAgent._read_reasoning_echo_from_config() static method — net -1 LOC.
---
 agent/agent_init.py            |  8 +-------
 agent/agent_runtime_helpers.py |  8 +-------
 run_agent.py                   | 11 +++++++++++
 3 files changed, 13 insertions(+), 14 deletions(-)

diff --git a/agent/agent_init.py b/agent/agent_init.py
index da92e6f881..20e44607bb 100644
--- a/agent/agent_init.py
+++ b/agent/agent_init.py
@@ -916,13 +916,7 @@ def init_agent(
     # Per-provider reasoning_content echo opt-in (see _reasoning_echo_opt_in).
     # Read once at init; switch_model / try_activate_fallback / restore
     # keep it in sync with the active provider.
-    try:
-        from hermes_cli.config import load_config_readonly
-        agent._reasoning_echo_flag = bool(
-            (load_config_readonly().get("model") or {}).get("reasoning_echo")
-        )
-    except Exception:
-        agent._reasoning_echo_flag = False
+    agent._reasoning_echo_flag = agent._read_reasoning_echo_from_config()
     agent.service_tier = service_tier
     agent.request_overrides = dict(request_overrides or {})
     agent.prefill_messages = prefill_messages or []  # Prefilled conversation turns
diff --git a/agent/agent_runtime_helpers.py b/agent/agent_runtime_helpers.py
index bcb1cc3a04..dbbb0d11e9 100644
--- a/agent/agent_runtime_helpers.py
+++ b/agent/agent_runtime_helpers.py
@@ -2690,13 +2690,7 @@ def switch_model(agent, new_model, new_provider, api_key='', base_url='', api_mo
         agent.requested_provider = new_provider
         # Re-read reasoning_echo from config so the flag reflects the new
         # primary model's setting (see _reasoning_echo_opt_in).
-        try:
-            from hermes_cli.config import load_config_readonly
-            agent._reasoning_echo_flag = bool(
-                (load_config_readonly().get("model") or {}).get("reasoning_echo")
-            )
-        except Exception:
-            agent._reasoning_echo_flag = False
+        agent._reasoning_echo_flag = agent._read_reasoning_echo_from_config()
         # Use the new base_url when provided. When it's empty AND the
         # provider is actually changing, do NOT fall back to the current
         # (old provider's) URL — that silently pairs the new provider label
diff --git a/run_agent.py b/run_agent.py
index 548c9953d8..ad8dc8d65d 100644
--- a/run_agent.py
+++ b/run_agent.py
@@ -7790,6 +7790,17 @@ class AIAgent:
         """
         return bool(getattr(self, "_reasoning_echo_flag", False))
 
+    @staticmethod
+    def _read_reasoning_echo_from_config() -> bool:
+        """Read ``model.reasoning_echo`` from config; False on any error."""
+        try:
+            from hermes_cli.config import load_config_readonly
+            return bool(
+                (load_config_readonly().get("model") or {}).get("reasoning_echo")
+            )
+        except Exception:
+            return False
+
     def _needs_kimi_tool_reasoning(self) -> bool:
         """Return True when the current provider is Kimi / Moonshot thinking mode.