From 0645729f68e12526f8227369747cc931dc920a85 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sat, 29 Aug 2026 16:01:16 -0700
Subject: [PATCH 01/31] perf(worktrees): resolve watcher targets concurrently
 (#17166)

---
 ...ktree-base-directory-watch-targets.test.ts | 232 ++++++++++++++++++
 .../worktree-base-directory-watch-targets.ts  |  54 +++-
 2 files changed, 276 insertions(+), 10 deletions(-)
 create mode 100644 src/main/ipc/worktree-base-directory-watch-targets.test.ts

diff --git a/src/main/ipc/worktree-base-directory-watch-targets.test.ts b/src/main/ipc/worktree-base-directory-watch-targets.test.ts
new file mode 100644
index 00000000000..250b3d7625d
--- /dev/null
+++ b/src/main/ipc/worktree-base-directory-watch-targets.test.ts
@@ -0,0 +1,232 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { join, sep } from 'node:path'
+import type { GlobalSettings } from '../../shared/global-settings-types'
+import type { Repo } from '../../shared/repo-types'
+
+const { getSshFilesystemProviderMock, readFileMock, realpathMock, statMock } = vi.hoisted(() => ({
+  getSshFilesystemProviderMock: vi.fn(),
+  readFileMock: vi.fn(),
+  realpathMock: vi.fn(),
+  statMock: vi.fn()
+}))
+
+vi.mock('node:fs/promises', () => ({
+  readFile: readFileMock,
+  realpath: realpathMock,
+  stat: statMock
+}))
+
+vi.mock('../providers/ssh-filesystem-dispatch', () => ({
+  getSshFilesystemProvider: getSshFilesystemProviderMock
+}))
+
+import {
+  buildWorktreeBaseDirectoryWatchTargets,
+  clearWorktreeBaseDirectoryWatchTargetWarnings,
+  WORKTREE_BASE_TARGET_RESOLUTION_CONCURRENCY
+} from './worktree-base-directory-watch-targets'
+
+const absolutePath = (...parts: string[]): string => join(sep, ...parts)
+const WORKTREE_ROOT = absolutePath('workspace', 'worktrees')
+const PROJECT_ROOT = absolutePath('workspace', 'projects')
+const localDirectoryStat = { isDirectory: () => true }
+const remoteDirectoryStat = { type: 'directory', size: 0, mtime: 0 }
+const settings = {
+  workspaceDir: WORKTREE_ROOT,
+  nestWorkspaces: true
+} as GlobalSettings
+
+function makeRepo(index: number, overrides: Partial<Repo> = {}): Repo {
+  return {
+    id: `repo-${index}`,
+    path: join(PROJECT_ROOT, `project-${index}`),
+    displayName: `Project ${index}`,
+    badgeColor: '#000000',
+    addedAt: index,
+    ...overrides
+  } as Repo
+}
+
+function makeStore(repos: Repo[]) {
+  return {
+    getSettings: () => settings,
+    getRepos: () => repos
+  }
+}
+
+function makeRemoteProvider() {
+  return {
+    stat: vi.fn(async () => remoteDirectoryStat),
+    realpath: vi.fn(async (path: string) => path),
+    readFile: vi.fn(async () => ({ content: '', isBinary: false }))
+  }
+}
+
+describe('worktree base directory watch target resolution', () => {
+  let warnSpy: ReturnType<typeof vi.spyOn>
+
+  beforeEach(() => {
+    statMock.mockReset().mockResolvedValue(localDirectoryStat)
+    realpathMock.mockReset().mockImplementation(async (path: string) => path)
+    readFileMock.mockReset().mockResolvedValue('')
+    getSshFilesystemProviderMock.mockReset().mockReturnValue(undefined)
+    warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+  })
+
+  afterEach(() => {
+    clearWorktreeBaseDirectoryWatchTargetWarnings()
+    warnSpy.mockRestore()
+  })
+
+  it('bounds resolution concurrency and starts one successor per released slot', async () => {
+    const repos = Array.from(
+      { length: WORKTREE_BASE_TARGET_RESOLUTION_CONCURRENCY + 4 },
+      (_, index) => makeRepo(index)
+    )
+    const gates = repos.map(() => Promise.withResolvers<void>())
+    let startedRootStats = 0
+    let activeRootStats = 0
+    let peakRootStats = 0
+    statMock.mockImplementation(async (path: string) => {
+      if (path === WORKTREE_ROOT) {
+        const gate = gates[startedRootStats++]
+        activeRootStats++
+        peakRootStats = Math.max(peakRootStats, activeRootStats)
+        await gate.promise
+        activeRootStats--
+      }
+      return localDirectoryStat
+    })
+
+    const resultPromise = buildWorktreeBaseDirectoryWatchTargets(makeStore(repos) as never)
+    await vi.waitFor(() => {
+      expect(startedRootStats).toBe(WORKTREE_BASE_TARGET_RESOLUTION_CONCURRENCY)
+    })
+    expect(peakRootStats).toBe(WORKTREE_BASE_TARGET_RESOLUTION_CONCURRENCY)
+
+    gates[0].resolve()
+    await vi.waitFor(() => {
+      expect(startedRootStats).toBe(WORKTREE_BASE_TARGET_RESOLUTION_CONCURRENCY + 1)
+    })
+    expect(peakRootStats).toBe(WORKTREE_BASE_TARGET_RESOLUTION_CONCURRENCY)
+
+    for (const gate of gates) {
+      gate.resolve()
+    }
+    await resultPromise
+    expect(startedRootStats).toBe(repos.length)
+    expect(peakRootStats).toBe(WORKTREE_BASE_TARGET_RESOLUTION_CONCURRENCY)
+  })
+
+  it('merges targets and shared repo membership in store order after reverse completion', async () => {
+    const repos = Array.from({ length: 4 }, (_, index) => makeRepo(index))
+    const gates = repos.map(() => Promise.withResolvers<void>())
+    const gitStatStarted = new Set<number>()
+    const completionOrder: number[] = []
+    statMock.mockImplementation(async (path: string) => {
+      const index = repos.findIndex((repo) => path === join(repo.path, '.git'))
+      if (index !== -1) {
+        gitStatStarted.add(index)
+        await gates[index].promise
+        completionOrder.push(index)
+      }
+      return localDirectoryStat
+    })
+
+    const resultPromise = buildWorktreeBaseDirectoryWatchTargets(makeStore(repos) as never)
+    await vi.waitFor(() => expect(gitStatStarted.size).toBe(repos.length))
+    for (let index = repos.length - 1; index >= 0; index--) {
+      gates[index].resolve()
+      await vi.waitFor(() => expect(completionOrder).toContain(index))
+    }
+    const targets = await resultPromise
+
+    expect(completionOrder).toEqual([3, 2, 1, 0])
+    expect([...targets.values()].map((target) => [target.kind, target.path])).toEqual([
+      ['base', WORKTREE_ROOT],
+      ...repos.map((repo) => ['git-common', join(repo.path, '.git')])
+    ])
+    expect([...([...targets.values()][0]?.repos.keys() ?? [])]).toEqual(
+      repos.map((repo) => repo.id)
+    )
+  })
+
+  it('isolates missing paths to the affected repo', async () => {
+    const missing = Object.assign(new Error('missing'), { code: 'ENOENT' })
+    const goodBefore = makeRepo(0, { worktreeBasePath: absolutePath('worktrees', 'before') })
+    const unavailable = makeRepo(1, { worktreeBasePath: absolutePath('worktrees', 'missing') })
+    const goodAfter = makeRepo(2, { worktreeBasePath: absolutePath('worktrees', 'after') })
+    statMock.mockImplementation(async (path: string) => {
+      if (path === unavailable.worktreeBasePath || path === join(unavailable.path, '.git')) {
+        throw missing
+      }
+      return localDirectoryStat
+    })
+
+    const targets = await buildWorktreeBaseDirectoryWatchTargets(
+      makeStore([goodBefore, unavailable, goodAfter]) as never
+    )
+    const repoIds = [...targets.values()].flatMap((target) => [...target.repos.keys()])
+
+    expect(repoIds).toContain(goodBefore.id)
+    expect(repoIds).not.toContain(unavailable.id)
+    expect(repoIds).toContain(goodAfter.id)
+  })
+
+  it('keeps identical SSH paths isolated by connection and provider', async () => {
+    const providerA = makeRemoteProvider()
+    const providerB = makeRemoteProvider()
+    getSshFilesystemProviderMock.mockImplementation((connectionId: string) =>
+      connectionId === 'ssh-a' ? providerA : connectionId === 'ssh-b' ? providerB : undefined
+    )
+    const sharedPath = '/srv/project'
+    const repos = [
+      makeRepo(0, { path: sharedPath, connectionId: 'ssh-a' }),
+      makeRepo(1, { path: sharedPath, connectionId: 'ssh-b' })
+    ]
+
+    const targets = await buildWorktreeBaseDirectoryWatchTargets(makeStore(repos) as never)
+
+    expect(providerA.stat).toHaveBeenCalledTimes(2)
+    expect(providerA.realpath).toHaveBeenCalledTimes(2)
+    expect(providerB.stat).toHaveBeenCalledTimes(2)
+    expect(providerB.realpath).toHaveBeenCalledTimes(2)
+    expect([...targets.values()].map((target) => target.connectionId)).toEqual([
+      'ssh-a',
+      'ssh-a',
+      'ssh-b',
+      'ssh-b'
+    ])
+    expect(new Set(targets.keys()).size).toBe(4)
+  })
+
+  it('skips folder workspaces, unavailable SSH providers, and WSL UNC roots', async () => {
+    const folder = makeRepo(0, { kind: 'folder' })
+    const unavailableSsh = makeRepo(1, { connectionId: 'missing', path: '/srv/missing' })
+    const wslPath = '\\\\wsl.localhost\\Ubuntu\\home\\alice\\project'
+    const wsl = makeRepo(2, { path: wslPath, worktreeBasePath: wslPath })
+
+    const targets = await buildWorktreeBaseDirectoryWatchTargets(
+      makeStore([folder, unavailableSsh, wsl]) as never
+    )
+
+    expect(targets.size).toBe(0)
+    expect(statMock).not.toHaveBeenCalled()
+    expect(getSshFilesystemProviderMock).toHaveBeenCalledWith('missing')
+  })
+
+  it('does not publish ordered partial targets when a repo resolver rejects unexpectedly', async () => {
+    const completed = makeRepo(0)
+    const broken = makeRepo(1)
+    Object.defineProperty(broken, 'path', {
+      get: () => {
+        throw new Error('unexpected resolver failure')
+      }
+    })
+
+    await expect(
+      buildWorktreeBaseDirectoryWatchTargets(makeStore([completed, broken]) as never)
+    ).rejects.toThrow('unexpected resolver failure')
+    expect(statMock).toHaveBeenCalled()
+  })
+})
diff --git a/src/main/ipc/worktree-base-directory-watch-targets.ts b/src/main/ipc/worktree-base-directory-watch-targets.ts
index cfa825e09ab..5300475593d 100644
--- a/src/main/ipc/worktree-base-directory-watch-targets.ts
+++ b/src/main/ipc/worktree-base-directory-watch-targets.ts
@@ -15,6 +15,7 @@ import {
   resolveRuntimePath
 } from '../../shared/cross-platform-path'
 import { isWslUncPath } from '../../shared/wsl-paths'
+import { mapWithConcurrency } from '../../shared/map-with-concurrency'
 import { getSshFilesystemProvider } from '../providers/ssh-filesystem-dispatch'
 import {
   computeWorkspaceRoot,
@@ -32,6 +33,9 @@ import type {
 const missingRootWarnings = new Set<string>()
 const skippedWslWarnings = new Set<string>()
 
+// Why: match existing worktree probe caps while bounding aggregate SSH filesystem RPC pressure.
+export const WORKTREE_BASE_TARGET_RESOLUTION_CONCURRENCY = 8
+
 function normalizeWatchKey(pathValue: string): string {
   return normalizeRuntimePathForComparison(normalize(pathValue))
 }
@@ -177,21 +181,51 @@ async function maybeAddBaseTarget(
   }
 }
 
+async function resolveRepoTargets(
+  repo: Repo,
+  settings: GlobalSettings
+): Promise<Map<string, WorktreeBaseWatchTarget>> {
+  const targets = new Map<string, WorktreeBaseWatchTarget>()
+  if (isFolderRepo(repo)) {
+    return targets
+  }
+  const executionHostId = getRepoExecutionHostId(repo)
+  if (executionHostId === LOCAL_EXECUTION_HOST_ID) {
+    await maybeAddBaseTarget(targets, repo, settings)
+  } else if (repo.connectionId) {
+    await maybeAddBaseTarget(targets, repo, settings, repo.connectionId)
+  }
+  return targets
+}
+
+function mergeRepoTargets(
+  targets: Map<string, WorktreeBaseWatchTarget>,
+  repoTargets: Map<string, WorktreeBaseWatchTarget>
+): void {
+  for (const [key, target] of repoTargets) {
+    const existing = targets.get(key)
+    if (!existing) {
+      targets.set(key, target)
+      continue
+    }
+    for (const [repoId, config] of target.repos) {
+      existing.repos.set(repoId, config)
+    }
+  }
+}
+
 export async function buildWorktreeBaseDirectoryWatchTargets(
   store: Store
 ): Promise<Map<string, WorktreeBaseWatchTarget>> {
   const settings = store.getSettings()
+  const resolvedRepoTargets = await mapWithConcurrency(
+    store.getRepos(),
+    WORKTREE_BASE_TARGET_RESOLUTION_CONCURRENCY,
+    (repo) => resolveRepoTargets(repo, settings)
+  )
   const targets = new Map<string, WorktreeBaseWatchTarget>()
-  for (const repo of store.getRepos()) {
-    if (isFolderRepo(repo)) {
-      continue
-    }
-    const executionHostId = getRepoExecutionHostId(repo)
-    if (executionHostId === LOCAL_EXECUTION_HOST_ID) {
-      await maybeAddBaseTarget(targets, repo, settings)
-    } else if (repo.connectionId) {
-      await maybeAddBaseTarget(targets, repo, settings, repo.connectionId)
-    }
+  for (const repoTargets of resolvedRepoTargets) {
+    mergeRepoTargets(targets, repoTargets)
   }
   return targets
 }

From bf884ea8667817727f7dce6a86aa2c0e68c42be6 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sat, 29 Aug 2026 16:01:20 -0700
Subject: [PATCH 02/31] perf(startup): skip disabled diagnostic serialization
 (#17176)

---
 ...rsistence-loading-store-extraction.test.ts | 81 ++++++++++++++++++-
 .../loading-store/loaded-state-parsing.ts     | 14 ++--
 2 files changed, 86 insertions(+), 9 deletions(-)

diff --git a/src/main/persistence-loading-store-extraction.test.ts b/src/main/persistence-loading-store-extraction.test.ts
index dafb6deadee..e48971d6c5c 100644
--- a/src/main/persistence-loading-store-extraction.test.ts
+++ b/src/main/persistence-loading-store-extraction.test.ts
@@ -2,14 +2,22 @@ import { afterEach, beforeEach, describe, expect, expectTypeOf, it, vi } from 'v
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { getDefaultWorkspaceSession } from '../shared/constants'
+import { getDefaultPersistedState, getDefaultWorkspaceSession } from '../shared/constants'
 import type { PersistedState } from '../shared/persisted-state-types'
+import type * as StartupDiagnosticsModule from './startup/startup-diagnostics'
 import type { Store as PersistenceStore } from './persistence/loading-store/store'
-import { createStore, dataFile, makeRepo, testState } from './persistence-test-harness'
+import {
+  createStore,
+  dataFile,
+  makeRepo,
+  testState,
+  writeDataFile
+} from './persistence-test-harness'
 
-const { trackMock, getCohortAtEmitMock } = vi.hoisted(() => ({
+const { trackMock, getCohortAtEmitMock, logStartupDiagnosticMock } = vi.hoisted(() => ({
   trackMock: vi.fn(),
-  getCohortAtEmitMock: vi.fn(() => ({ nth_repo_added: 2 }))
+  getCohortAtEmitMock: vi.fn(() => ({ nth_repo_added: 2 })),
+  logStartupDiagnosticMock: vi.fn()
 }))
 
 vi.mock('electron', () => ({
@@ -33,6 +41,10 @@ vi.mock('./ssh/ssh-config-parser', () => ({
   loadUserSshConfig: vi.fn(() => ({ hosts: [] })),
   sshConfigHostsToTargets: vi.fn(() => [])
 }))
+vi.mock('./startup/startup-diagnostics', async (importOriginal) => {
+  const actual = await importOriginal<typeof StartupDiagnosticsModule>()
+  return { ...actual, logStartupDiagnostic: logStartupDiagnosticMock }
+})
 
 describe('loading Store extraction seams', () => {
   beforeEach(() => {
@@ -40,9 +52,70 @@ describe('loading Store extraction seams', () => {
   })
 
   afterEach(() => {
+    vi.unstubAllEnvs()
+    logStartupDiagnosticMock.mockReset()
     rmSync(testState.dir, { recursive: true, force: true })
   })
 
+  it('does not serialize the workspace session when startup diagnostics are disabled', () => {
+    const sentinel = 'startup-diagnostics-workspace-session-sentinel-disabled'
+    vi.stubEnv('ORCA_STARTUP_DIAGNOSTICS', '')
+    const state = getDefaultPersistedState(testState.dir)
+    state.workspaceSession = { ...state.workspaceSession, activeTabId: sentinel }
+    writeDataFile(state)
+
+    const stringifySpy = vi.spyOn(JSON, 'stringify')
+    const store = createStore()
+    store.freezeWrites()
+
+    const workspaceSessionStringifyCalls = stringifySpy.mock.calls.filter(
+      ([value]) =>
+        value &&
+        typeof value === 'object' &&
+        (value as { activeTabId?: unknown }).activeTabId === sentinel
+    )
+    stringifySpy.mockRestore()
+
+    expect(store.getWorkspaceSession().activeTabId).toBe(sentinel)
+    expect(workspaceSessionStringifyCalls).toHaveLength(0)
+    expect(
+      logStartupDiagnosticMock.mock.calls.some(([event]) => event === 'persistence-load-done')
+    ).toBe(false)
+  })
+
+  it('reports the unchanged workspace-session byte count when startup diagnostics are enabled', () => {
+    const sentinel = 'startup-diagnostics-workspace-session-sentinel-enabled'
+    vi.stubEnv('ORCA_STARTUP_DIAGNOSTICS', '1')
+    const state = getDefaultPersistedState(testState.dir)
+    state.workspaceSession = { ...state.workspaceSession, activeTabId: sentinel }
+    writeDataFile(state)
+
+    const stringifySpy = vi.spyOn(JSON, 'stringify')
+    const store = createStore()
+    store.freezeWrites()
+
+    const workspaceSessionStringifyCalls = stringifySpy.mock.calls.filter(
+      ([value]) =>
+        value &&
+        typeof value === 'object' &&
+        (value as { activeTabId?: unknown }).activeTabId === sentinel
+    )
+    stringifySpy.mockRestore()
+
+    expect(store.getWorkspaceSession().activeTabId).toBe(sentinel)
+    expect(workspaceSessionStringifyCalls).toHaveLength(1)
+    const loadDoneCall = logStartupDiagnosticMock.mock.calls.find(
+      ([event]) => event === 'persistence-load-done'
+    )
+    expect(loadDoneCall).toBeDefined()
+    const details = loadDoneCall?.[1] as Record<string, unknown> | undefined
+    expect(details).toEqual({
+      t: expect.any(Number),
+      repos: state.repos.length,
+      workspaceSessionBytes: Buffer.byteLength(JSON.stringify(store.getWorkspaceSession()))
+    })
+  })
+
   it('accepts the first JSON-parseable backup even when an older backup has richer state', async () => {
     mkdirSync(testState.dir, { recursive: true })
     writeFileSync(dataFile(), '{{corrupt-primary', 'utf-8')
diff --git a/src/main/persistence/loading-store/loaded-state-parsing.ts b/src/main/persistence/loading-store/loaded-state-parsing.ts
index 2f28c771508..5bd6e572ab1 100644
--- a/src/main/persistence/loading-store/loaded-state-parsing.ts
+++ b/src/main/persistence/loading-store/loaded-state-parsing.ts
@@ -42,13 +42,17 @@ import { prepareLoadedTerminalSettings } from './prepare-loaded-terminal-setting
 import { prepareLoadedProfileSettings } from './prepare-loaded-profile-settings'
 import { normalizeLoadedProfileState } from './normalize-loaded-profile-state'
 
+type PersistenceStartupDetails = Record<string, unknown> | (() => Record<string, unknown>)
+
 function logPersistenceStartupMilestone(
   event: string,
-  details: Record<string, unknown> = {}
+  details: PersistenceStartupDetails = {}
 ): void {
-  if (isStartupDiagnosticsEnabled()) {
-    logStartupDiagnostic(event, { t: Math.round(performance.now()), ...details })
+  if (!isStartupDiagnosticsEnabled()) {
+    return
   }
+  const resolvedDetails = typeof details === 'function' ? details() : details
+  logStartupDiagnostic(event, { t: Math.round(performance.now()), ...resolvedDetails })
 }
 
 import type { StoreRuntimeState } from './store-runtime-state'
@@ -279,10 +283,10 @@ export class LoadedStateParsingOperations {
       migrated.githubCache = readGithubCacheSnapshot(this.runtime.dataFile) ?? migrated.githubCache
     }
 
-    logPersistenceStartupMilestone('persistence-load-done', {
+    logPersistenceStartupMilestone('persistence-load-done', () => ({
       repos: migrated.repos.length,
       workspaceSessionBytes: Buffer.byteLength(JSON.stringify(migrated.workspaceSession))
-    })
+    }))
     return migrated
   }
 }

From 80a0595449d78f12b9610c704da80b5ff40df6a9 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sat, 29 Aug 2026 16:01:23 -0700
Subject: [PATCH 03/31] perf(startup): stop rescanning persisted pane tabs
 (#17179)

* perf(startup): index persisted pane tabs once

* perf(startup): lazily resolve persisted pane tabs
---
 .../pane-identity-migration.ts                |  66 ++++++-
 ...workspace-pane-normalization-index.test.ts | 184 ++++++++++++++++++
 .../workspace-pane-normalization.ts           |   9 +-
 3 files changed, 247 insertions(+), 12 deletions(-)
 create mode 100644 src/main/persistence/restoring-sessions/workspace-pane-normalization-index.test.ts

diff --git a/src/main/persistence/restoring-sessions/pane-identity-migration.ts b/src/main/persistence/restoring-sessions/pane-identity-migration.ts
index e07e9995286..98d97a649a3 100644
--- a/src/main/persistence/restoring-sessions/pane-identity-migration.ts
+++ b/src/main/persistence/restoring-sessions/pane-identity-migration.ts
@@ -1,5 +1,5 @@
 import type { LegacyPaneKeyAliasEntry } from '../../../shared/persisted-state-types'
-import type { TerminalLayoutSnapshot } from '../../../shared/terminal-tab-types'
+import type { TerminalLayoutSnapshot, TerminalTab } from '../../../shared/terminal-tab-types'
 import type { WorkspaceSessionState } from '../../../shared/workspace-session-state-types'
 import { isTerminalLeafId, makePaneKey } from '../../../shared/stable-pane-id'
 import { agentHookServer } from '../../agent-hooks/server'
@@ -17,23 +17,69 @@ export function findWorktreeIdForTab(
   return undefined
 }
 
+export type TerminalTabLookup = {
+  get(tabId: string): TerminalTab | undefined
+}
+
+/** Resolves tabs on demand while retaining first-match ordering and scan progress. */
+export function createLazyTerminalTabLookup(session: WorkspaceSessionState): TerminalTabLookup {
+  const tabsByWorktree = Object.entries(session.tabsByWorktree ?? {})
+  const tabsById = new Map<string, TerminalTab>()
+  let worktreeIndex = 0
+  let tabIndex = 0
+  let exhausted = false
+
+  return {
+    get(requestedTabId: string): TerminalTab | undefined {
+      if (tabsById.has(requestedTabId)) {
+        return tabsById.get(requestedTabId)
+      }
+      if (exhausted) {
+        return undefined
+      }
+
+      while (worktreeIndex < tabsByWorktree.length) {
+        const tabs = tabsByWorktree[worktreeIndex][1]
+        while (tabIndex < tabs.length) {
+          const currentIndex = tabIndex
+          tabIndex += 1
+          // Array#some, used by the prior lookup, skips sparse holes.
+          if (!(currentIndex in tabs)) {
+            continue
+          }
+          const tab = tabs[currentIndex]
+          const tabId = tab.id
+          // Preserve first-match behavior when persisted IDs collide.
+          if (!tabsById.has(tabId)) {
+            tabsById.set(tabId, tab)
+          }
+          if (tabId === requestedTabId) {
+            return tabsById.get(requestedTabId)
+          }
+        }
+        worktreeIndex += 1
+        tabIndex = 0
+      }
+
+      exhausted = true
+      return undefined
+    }
+  }
+}
+
 /** Bridges a tab's legacy numeric pane keys to stable ones; returns the alias rows worth persisting. */
 export function registerLegacyPaneKeyAliasesForTab(args: {
-  session: WorkspaceSessionState
   tabId: string
+  tab: TerminalTab | undefined
   inputLayout: TerminalLayoutSnapshot
   normalizedLayout: TerminalLayoutSnapshot
   leafIdByInputLeafId: Map<string, string>
 }): LegacyPaneKeyAliasEntry[] {
-  const worktreeId = findWorktreeIdForTab(args.session, args.tabId)
-  const tab = worktreeId
-    ? args.session.tabsByWorktree?.[worktreeId]?.find((entry) => entry.id === args.tabId)
-    : undefined
   const legacyPaneKeyAliasEntries: LegacyPaneKeyAliasEntry[] = []
   const registeredLegacyPaneKeys = new Set<string>()
   const hasLeafPtyBindings = Object.keys(args.inputLayout.ptyIdsByLeafId ?? {}).length > 0
   const fallbackPtyId =
-    !hasLeafPtyBindings && typeof tab?.ptyId === 'string' ? tab.ptyId : undefined
+    !hasLeafPtyBindings && typeof args.tab?.ptyId === 'string' ? args.tab.ptyId : undefined
   const registerLegacyAlias = (inputLeafId: string, leafId: string, ptyId?: string): boolean => {
     if (!isTerminalLeafId(leafId)) {
       return false
@@ -80,7 +126,7 @@ export function registerLegacyPaneKeyAliasesForTab(args: {
       )
     }
   }
-  if (tab?.ptyId && !hasLeafPtyBindings) {
+  if (args.tab?.ptyId && !hasLeafPtyBindings) {
     const fallbackLeafId =
       args.normalizedLayout.activeLeafId ?? firstLayoutLeafId(args.normalizedLayout.root)
     let paneKey: string | undefined
@@ -96,9 +142,9 @@ export function registerLegacyPaneKeyAliasesForTab(args: {
         if (registeredLegacyPaneKeys.has(legacyPaneKey)) {
           continue
         }
-        agentHookServer.registerPaneKeyAlias(legacyPaneKey, paneKey, tab.ptyId)
+        agentHookServer.registerPaneKeyAlias(legacyPaneKey, paneKey, args.tab.ptyId)
         legacyPaneKeyAliasEntries.push({
-          ptyId: tab.ptyId,
+          ptyId: args.tab.ptyId,
           legacyPaneKey,
           stablePaneKey: paneKey,
           updatedAt: Date.now()
diff --git a/src/main/persistence/restoring-sessions/workspace-pane-normalization-index.test.ts b/src/main/persistence/restoring-sessions/workspace-pane-normalization-index.test.ts
new file mode 100644
index 00000000000..9cebe041544
--- /dev/null
+++ b/src/main/persistence/restoring-sessions/workspace-pane-normalization-index.test.ts
@@ -0,0 +1,184 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { TerminalLayoutSnapshot, TerminalTab } from '../../../shared/terminal-tab-types'
+import type { WorkspaceSessionState } from '../../../shared/workspace-session-state-types'
+import { createLazyTerminalTabLookup } from './pane-identity-migration'
+import { normalizeWorkspaceSessionPaneIdentities } from './workspace-pane-normalization'
+
+const { registerPaneKeyAliasMock } = vi.hoisted(() => ({
+  registerPaneKeyAliasMock: vi.fn()
+}))
+
+vi.mock('../../agent-hooks/server', () => ({
+  agentHookServer: {
+    registerPaneKeyAlias: registerPaneKeyAliasMock
+  }
+}))
+
+const STABLE_LEAF_ID = '00000000-0000-4000-8000-000000000001'
+
+function terminalTab(id: string, worktreeId: string, ptyId: string | null): TerminalTab {
+  return {
+    id,
+    worktreeId,
+    ptyId,
+    title: 'Terminal',
+    customTitle: null,
+    color: null,
+    sortOrder: 0,
+    createdAt: 1
+  }
+}
+
+function workspaceSession(
+  tabsByWorktree: Record<string, TerminalTab[]>,
+  terminalLayoutsByTabId: Record<string, TerminalLayoutSnapshot>
+): WorkspaceSessionState {
+  return {
+    activeRepoId: null,
+    activeWorktreeId: null,
+    activeTabId: null,
+    tabsByWorktree,
+    terminalLayoutsByTabId
+  }
+}
+
+function legacyLayout(): TerminalLayoutSnapshot {
+  return {
+    root: { type: 'leaf', leafId: 'pane:1' },
+    activeLeafId: 'pane:1',
+    expandedLeafId: null
+  }
+}
+
+function stableLayout(): TerminalLayoutSnapshot {
+  return {
+    root: { type: 'leaf', leafId: STABLE_LEAF_ID },
+    activeLeafId: STABLE_LEAF_ID,
+    expandedLeafId: null
+  }
+}
+
+describe('workspace pane normalization tab index', () => {
+  beforeEach(() => {
+    registerPaneKeyAliasMock.mockReset()
+  })
+
+  it('keeps the first tab when duplicate ids occur across worktrees', () => {
+    const result = normalizeWorkspaceSessionPaneIdentities(
+      workspaceSession(
+        {
+          first: [terminalTab('duplicate-tab', 'first', 'first-pty')],
+          second: [terminalTab('duplicate-tab', 'second', 'second-pty')]
+        },
+        { 'duplicate-tab': legacyLayout() }
+      )
+    )
+
+    expect(result.legacyPaneKeyAliasEntries).not.toHaveLength(0)
+    expect(result.legacyPaneKeyAliasEntries.every((entry) => entry.ptyId === 'first-pty')).toBe(
+      true
+    )
+  })
+
+  it('keeps missing tab ids without inventing persisted aliases', () => {
+    const result = normalizeWorkspaceSessionPaneIdentities(
+      workspaceSession({}, { 'missing-tab': legacyLayout() })
+    )
+
+    expect(result.legacyPaneKeyAliasEntries).toEqual([])
+  })
+
+  it('reads each tab id once regardless of the number of layouts', () => {
+    const tabCount = 256
+    let idReads = 0
+    const tabs = Array.from({ length: tabCount }, (_, index) => {
+      const id = `tab-${index}`
+      const tab = terminalTab(id, 'worktree', null)
+      Object.defineProperty(tab, 'id', {
+        enumerable: true,
+        get: () => {
+          idReads += 1
+          return id
+        }
+      })
+      return tab
+    })
+    const layouts = Object.fromEntries(
+      Array.from({ length: tabCount }, (_, index) => [`tab-${index}`, stableLayout()])
+    )
+
+    normalizeWorkspaceSessionPaneIdentities(workspaceSession({ worktree: tabs }, layouts))
+
+    expect(idReads).toBe(tabCount)
+  })
+
+  it('does not inspect tabs after an early match', () => {
+    const first = terminalTab('first', 'worktree', 'first-pty')
+    const later = terminalTab('later', 'worktree', 'later-pty')
+    Object.defineProperty(later, 'id', {
+      enumerable: true,
+      get: () => {
+        throw new Error('later tab should not be inspected')
+      }
+    })
+
+    const lookup = createLazyTerminalTabLookup(workspaceSession({ worktree: [first, later] }, {}))
+
+    expect(lookup.get('first')).toBe(first)
+  })
+
+  it('resumes scanning and makes later misses constant-time', () => {
+    const reads: string[] = []
+    const tabs = ['first', 'second', 'third'].map((id) => {
+      const tab = terminalTab(id, 'worktree', null)
+      Object.defineProperty(tab, 'id', {
+        enumerable: true,
+        get: () => {
+          reads.push(id)
+          return id
+        }
+      })
+      return tab
+    })
+    const lookup = createLazyTerminalTabLookup(workspaceSession({ worktree: tabs }, {}))
+
+    expect(lookup.get('first')).toBe(tabs[0])
+    expect(reads).toEqual(['first'])
+    expect(lookup.get('second')).toBe(tabs[1])
+    expect(reads).toEqual(['first', 'second'])
+    expect(lookup.get('missing')).toBeUndefined()
+    expect(reads).toEqual(['first', 'second', 'third'])
+    expect(lookup.get('missing')).toBeUndefined()
+    expect(reads).toEqual(['first', 'second', 'third'])
+  })
+
+  it('skips sparse tab-array holes', () => {
+    const tabs: TerminalTab[] = []
+    tabs.length = 3
+    tabs[1] = terminalTab('target', 'worktree', null)
+    const lookup = createLazyTerminalTabLookup(workspaceSession({ worktree: tabs }, {}))
+
+    expect(lookup.get('target')).toBe(tabs[1])
+    expect(lookup.get('missing')).toBeUndefined()
+  })
+
+  it('does not read tab ids when every layout is skipped', () => {
+    const tab = terminalTab('skipped', 'worktree', null)
+    let idReads = 0
+    Object.defineProperty(tab, 'id', {
+      enumerable: true,
+      get: () => {
+        idReads += 1
+        return 'skipped'
+      }
+    })
+
+    normalizeWorkspaceSessionPaneIdentities(
+      workspaceSession({ worktree: [tab] }, { skipped: legacyLayout() }),
+      {},
+      { skipAliasTabIds: new Set(['skipped']) }
+    )
+
+    expect(idReads).toBe(0)
+  })
+})
diff --git a/src/main/persistence/restoring-sessions/workspace-pane-normalization.ts b/src/main/persistence/restoring-sessions/workspace-pane-normalization.ts
index a977134bd0e..2bfafebae9f 100644
--- a/src/main/persistence/restoring-sessions/workspace-pane-normalization.ts
+++ b/src/main/persistence/restoring-sessions/workspace-pane-normalization.ts
@@ -10,7 +10,10 @@ import {
 import type { SshRemotePtyLease } from '../../../shared/ssh-types'
 import { isTerminalLeafId, makePaneKey, parsePaneKey } from '../../../shared/stable-pane-id'
 import { findCrossHostPaneTabIds, withoutPaneTabIds } from './cross-host-pane-tab-ids'
-import { registerLegacyPaneKeyAliasesForTab } from './pane-identity-migration'
+import {
+  createLazyTerminalTabLookup,
+  registerLegacyPaneKeyAliasesForTab
+} from './pane-identity-migration'
 import { normalizeTerminalLayoutSnapshotForPersistence } from './terminal-layout-normalization'
 import {
   legacyMigrationUnsupportedRowsToAliasEntries,
@@ -40,6 +43,7 @@ export function normalizeWorkspaceSessionPaneIdentities(
   const migrationUnsupportedEntries: MigrationUnsupportedPtyEntry[] = []
   const legacyPaneKeyAliasEntries: LegacyPaneKeyAliasEntry[] = []
   const terminalLayoutsByTabId: Record<string, TerminalLayoutSnapshot> = {}
+  let tabsById: ReturnType<typeof createLazyTerminalTabLookup> | null = null
   for (const [tabId, layout] of Object.entries(session.terminalLayoutsByTabId ?? {})) {
     const normalized = normalizeTerminalLayoutSnapshotForPersistence(
       layout,
@@ -48,9 +52,10 @@ export function normalizeWorkspaceSessionPaneIdentities(
     terminalLayoutsByTabId[tabId] = normalized.snapshot
     leafIdByInputLeafIdByTabId.set(tabId, normalized.leafIdByInputLeafId)
     if (!options.skipAliasTabIds?.has(tabId)) {
+      tabsById ??= createLazyTerminalTabLookup(session)
       const tabAliasEntries = registerLegacyPaneKeyAliasesForTab({
-        session,
         tabId,
+        tab: tabsById.get(tabId),
         inputLayout: layout,
         normalizedLayout: normalized.snapshot,
         leafIdByInputLeafId: normalized.leafIdByInputLeafId

From eb6cd6721965f959476cedc550a0fb2e69fa715e Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sat, 29 Aug 2026 16:01:27 -0700
Subject: [PATCH 04/31] perf(editor): skip unchanged review-note reflows
 (#17212)

---
 .../DiffCommentCard.resize.test.tsx           | 51 ++++++++++++++++++-
 .../diff-comments/DiffCommentCard.tsx         | 18 ++++---
 2 files changed, 62 insertions(+), 7 deletions(-)

diff --git a/src/renderer/src/components/diff-comments/DiffCommentCard.resize.test.tsx b/src/renderer/src/components/diff-comments/DiffCommentCard.resize.test.tsx
index f17dfbb7613..648b33357d4 100644
--- a/src/renderer/src/components/diff-comments/DiffCommentCard.resize.test.tsx
+++ b/src/renderer/src/components/diff-comments/DiffCommentCard.resize.test.tsx
@@ -1,5 +1,5 @@
 // @vitest-environment happy-dom
-import { act, cleanup, render } from '@testing-library/react'
+import { act, cleanup, fireEvent, render } from '@testing-library/react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { DiffCommentCard } from './DiffCommentCard'
 
@@ -44,6 +44,7 @@ describe('DiffCommentCard content resize', () => {
 
   afterEach(() => {
     cleanup()
+    vi.restoreAllMocks()
     vi.unstubAllGlobals()
   })
 
@@ -101,4 +102,52 @@ describe('DiffCommentCard content resize', () => {
     expect(constructObserver).not.toHaveBeenCalled()
     expect(onContentResize).not.toHaveBeenCalled()
   })
+
+  it('requests rail reflow only when the editing textarea height changes', () => {
+    const onContentResize = vi.fn()
+    let scrollHeight = 60
+    vi.spyOn(HTMLTextAreaElement.prototype, 'scrollHeight', 'get').mockImplementation(
+      () => scrollHeight
+    )
+    const view = render(
+      <DiffCommentCard
+        lineNumber={26}
+        body="A saved note"
+        onContentResize={onContentResize}
+        onSubmitEdit={async () => true}
+      />
+    )
+
+    fireEvent.click(view.getByRole('button', { name: 'Edit note' }))
+    expect(onContentResize).toHaveBeenCalledOnce()
+
+    const textarea = view.getByRole('textbox')
+    expect(textarea.style.height).toBe('60px')
+    fireEvent.change(textarea, { target: { value: 'A saved note!' } })
+    expect(onContentResize).toHaveBeenCalledOnce()
+
+    for (let index = 0; index < 50; index++) {
+      fireEvent.change(textarea, { target: { value: `A saved note! ${index}` } })
+    }
+    expect(textarea.style.height).toBe('60px')
+    expect(onContentResize).toHaveBeenCalledOnce()
+
+    scrollHeight = 400
+    fireEvent.change(textarea, { target: { value: 'A much taller saved note' } })
+    expect(textarea.style.height).toBe('240px')
+    expect(onContentResize).toHaveBeenCalledTimes(2)
+
+    scrollHeight = 480
+    fireEvent.change(textarea, { target: { value: 'A still taller saved note' } })
+    expect(textarea.style.height).toBe('240px')
+    expect(onContentResize).toHaveBeenCalledTimes(2)
+
+    scrollHeight = 80
+    fireEvent.change(textarea, { target: { value: 'A shorter saved note' } })
+    expect(textarea.style.height).toBe('80px')
+    expect(onContentResize).toHaveBeenCalledTimes(3)
+
+    fireEvent.click(view.getByRole('button', { name: 'Cancel' }))
+    expect(onContentResize).toHaveBeenCalledTimes(4)
+  })
 })
diff --git a/src/renderer/src/components/diff-comments/DiffCommentCard.tsx b/src/renderer/src/components/diff-comments/DiffCommentCard.tsx
index 9e7ddf229ce..6becfe1fb34 100644
--- a/src/renderer/src/components/diff-comments/DiffCommentCard.tsx
+++ b/src/renderer/src/components/diff-comments/DiffCommentCard.tsx
@@ -35,6 +35,13 @@ type Props = {
   headerActions?: ReactNode
 }
 
+function resizeDiffCommentTextarea(textarea: HTMLTextAreaElement): boolean {
+  const previousHeight = textarea.style.height
+  textarea.style.height = 'auto'
+  textarea.style.height = `${Math.min(textarea.scrollHeight, 240)}px`
+  return textarea.style.height !== previousHeight
+}
+
 export function DiffCommentCard({
   lineNumber,
   startLine,
@@ -116,8 +123,7 @@ export function DiffCommentCard({
     if (!el) {
       return
     }
-    el.style.height = 'auto'
-    el.style.height = `${Math.min(el.scrollHeight, 240)}px`
+    resizeDiffCommentTextarea(el)
     el.focus()
     el.setSelectionRange(el.value.length, el.value.length)
     onContentResizeRef.current?.()
@@ -281,10 +287,10 @@ export function DiffCommentCard({
               value={draft}
               onChange={(e) => {
                 setDraft(e.target.value)
-                const el = e.currentTarget
-                el.style.height = 'auto'
-                el.style.height = `${Math.min(el.scrollHeight, 240)}px`
-                onContentResizeRef.current?.()
+                // Why: rich-review layout measures every note; skip it when this card stayed put.
+                if (resizeDiffCommentTextarea(e.currentTarget)) {
+                  onContentResizeRef.current?.()
+                }
               }}
               onKeyDown={(e) => {
                 if (e.key === 'Escape') {

From 7879dead69b1101301c9b861e494702800ee8220 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sat, 29 Aug 2026 16:01:29 -0700
Subject: [PATCH 05/31] perf(ssh): cache legacy worktree clean fallback
 (#17213)

---
 .../ssh-git-provider-worktree.test.ts         | 225 ++++++++++++++++--
 .../providers/ssh-git-worktree-provider.ts    |  69 +++---
 2 files changed, 247 insertions(+), 47 deletions(-)

diff --git a/src/main/providers/ssh-git-provider-worktree.test.ts b/src/main/providers/ssh-git-provider-worktree.test.ts
index 10f36acc8fd..6ddff0a1f68 100644
--- a/src/main/providers/ssh-git-provider-worktree.test.ts
+++ b/src/main/providers/ssh-git-provider-worktree.test.ts
@@ -1,6 +1,16 @@
 import { describe, expect, it, vi, beforeEach } from 'vitest'
 import { SshGitProvider } from './ssh-git-provider'
-import { createMockMux, type MockMultiplexer } from './ssh-git-provider-test-harness'
+import {
+  createMockMux,
+  waitForRequestCount,
+  type MockMultiplexer
+} from './ssh-git-provider-test-harness'
+
+function methodNotFound(method: string): Error & { code: number } {
+  return Object.assign(new Error(`Method not found: ${method}`), { code: -32601 })
+}
+
+const CLEAN_STATUS = { entries: [], conflictOperation: 'unknown' }
 
 describe('SshGitProvider', () => {
   let mux: MockMultiplexer
@@ -67,6 +77,40 @@ describe('SshGitProvider', () => {
     expect(result).toEqual(cleanResult)
   })
 
+  it('keeps supported clean checks on the preferred relay RPC', async () => {
+    let resolveProbe!: (result: { clean: boolean }) => void
+    let resolveRemaining!: (result: { clean: boolean }) => void
+    const probe = new Promise<{ clean: boolean }>((resolve) => {
+      resolveProbe = resolve
+    })
+    const remaining = new Promise<{ clean: boolean }>((resolve) => {
+      resolveRemaining = resolve
+    })
+    let preferredRequestCount = 0
+    mux.request.mockImplementation((method) => {
+      expect(method).toBe('git.worktreeIsClean')
+      preferredRequestCount += 1
+      return preferredRequestCount === 1 ? probe : remaining
+    })
+    const checks = Array.from({ length: 10 }, (_, index) =>
+      provider.worktreeIsClean(`/repo/worktree-${index}`)
+    )
+
+    await waitForRequestCount(mux.request, 1)
+    expect(mux.request).toHaveBeenCalledOnce()
+    resolveProbe({ clean: true })
+    await waitForRequestCount(mux.request, 10)
+    expect(mux.request).toHaveBeenCalledTimes(10)
+    resolveRemaining({ clean: true })
+    await expect(Promise.all(checks)).resolves.toEqual(
+      Array.from({ length: 10 }, () => ({ clean: true }))
+    )
+    expect(
+      mux.request.mock.calls.filter(([method]) => method === 'git.worktreeIsClean')
+    ).toHaveLength(10)
+    expect(mux.request.mock.calls.some(([method]) => method === 'git.status')).toBe(false)
+  })
+
   it('worktreeIsClean can ignore untracked files', async () => {
     const cleanResult = { clean: true }
     mux.request.mockResolvedValue(cleanResult)
@@ -113,10 +157,7 @@ describe('SshGitProvider', () => {
   })
 
   it('worktreeIsClean falls back to git.status for old relays', async () => {
-    const methodNotFound = Object.assign(new Error('Method not found: git.worktreeIsClean'), {
-      code: -32601
-    })
-    mux.request.mockRejectedValueOnce(methodNotFound).mockResolvedValueOnce({
+    mux.request.mockRejectedValueOnce(methodNotFound('git.worktreeIsClean')).mockResolvedValueOnce({
       entries: [{ path: 'scratch.txt', status: 'untracked', area: 'untracked' }],
       conflictOperation: 'unknown'
     })
@@ -140,26 +181,180 @@ describe('SshGitProvider', () => {
     }
   })
 
-  it('worktreeIsClean filters untracked entries in old-relay fallback', async () => {
-    const methodNotFound = Object.assign(new Error('Method not found: git.worktreeIsClean'), {
-      code: -32601
+  it('probes an old relay once across sequential clean checks', async () => {
+    mux.request.mockImplementation(async (method) => {
+      if (method === 'git.worktreeIsClean') {
+        throw methodNotFound(method)
+      }
+      return CLEAN_STATUS
     })
-    mux.request.mockRejectedValueOnce(methodNotFound).mockResolvedValueOnce({
-      entries: [{ path: 'scratch.txt', status: 'untracked', area: 'untracked' }],
-      conflictOperation: 'unknown'
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const worktreePaths = Array.from({ length: 10 }, (_, index) => `/repo/worktree-${index}`)
+
+    try {
+      for (const worktreePath of worktreePaths) {
+        await expect(provider.worktreeIsClean(worktreePath)).resolves.toEqual({ clean: true })
+      }
+
+      expect(
+        mux.request.mock.calls.filter(([method]) => method === 'git.worktreeIsClean')
+      ).toHaveLength(1)
+      expect(mux.request.mock.calls.filter(([method]) => method === 'git.status')).toHaveLength(10)
+      expect(mux.request).toHaveBeenCalledTimes(11)
+      expect(warnSpy).toHaveBeenCalledOnce()
+    } finally {
+      warnSpy.mockRestore()
+    }
+  })
+
+  it('shares one old-relay probe across concurrent clean checks', async () => {
+    let rejectProbe!: (error: Error) => void
+    const probe = new Promise((_resolve, reject) => {
+      rejectProbe = reject
+    })
+    mux.request.mockImplementation((method) => {
+      if (method === 'git.worktreeIsClean') {
+        return probe
+      }
+      return Promise.resolve(CLEAN_STATUS)
+    })
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const checks = Array.from({ length: 10 }, (_, index) =>
+      provider.worktreeIsClean(`/repo/worktree-${index}`)
+    )
+
+    try {
+      await waitForRequestCount(mux.request, 1)
+      rejectProbe(methodNotFound('git.worktreeIsClean'))
+      await expect(Promise.all(checks)).resolves.toEqual(
+        Array.from({ length: 10 }, () => ({ clean: true }))
+      )
+
+      expect(
+        mux.request.mock.calls.filter(([method]) => method === 'git.worktreeIsClean')
+      ).toHaveLength(1)
+      expect(mux.request.mock.calls.filter(([method]) => method === 'git.status')).toHaveLength(10)
+      expect(mux.request).toHaveBeenCalledTimes(11)
+      expect(warnSpy).toHaveBeenCalledOnce()
+    } finally {
+      warnSpy.mockRestore()
+    }
+  })
+
+  it('retries the preferred clean RPC after a transport failure', async () => {
+    const transportError = Object.assign(new Error('Method not found: git.worktreeIsClean'), {
+      code: -32602
+    })
+    mux.request.mockRejectedValueOnce(transportError).mockResolvedValueOnce({ clean: true })
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    try {
+      await expect(provider.worktreeIsClean('/repo/first')).rejects.toBe(transportError)
+      await expect(provider.worktreeIsClean('/repo/second')).resolves.toEqual({ clean: true })
+      expect(mux.request.mock.calls.map(([method]) => method)).toEqual([
+        'git.worktreeIsClean',
+        'git.worktreeIsClean'
+      ])
+      expect(warnSpy).not.toHaveBeenCalled()
+    } finally {
+      warnSpy.mockRestore()
+    }
+  })
+
+  it('lets concurrent waiters retry after a transient probe failure', async () => {
+    const transportError = new Error('connection closed')
+    let rejectProbe!: (error: Error) => void
+    let resolveRetries!: (result: { clean: boolean }) => void
+    const probe = new Promise((_resolve, reject) => {
+      rejectProbe = reject
+    })
+    const retries = new Promise<{ clean: boolean }>((resolve) => {
+      resolveRetries = resolve
+    })
+    let preferredRequestCount = 0
+    mux.request.mockImplementation((method) => {
+      expect(method).toBe('git.worktreeIsClean')
+      preferredRequestCount += 1
+      return preferredRequestCount === 1 ? probe : retries
+    })
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const checks = Array.from({ length: 3 }, (_, index) =>
+      provider.worktreeIsClean(`/repo/worktree-${index}`)
+    )
+    const settledChecks = Promise.allSettled(checks)
+
+    try {
+      await waitForRequestCount(mux.request, 1)
+      rejectProbe(transportError)
+      await waitForRequestCount(mux.request, 3)
+      resolveRetries({ clean: true })
+
+      const results = await settledChecks
+      expect(results[0]).toEqual({ status: 'rejected', reason: transportError })
+      expect(results.slice(1)).toEqual([
+        { status: 'fulfilled', value: { clean: true } },
+        { status: 'fulfilled', value: { clean: true } }
+      ])
+      await expect(provider.worktreeIsClean('/repo/later')).resolves.toEqual({ clean: true })
+      expect(mux.request).toHaveBeenCalledTimes(4)
+      expect(warnSpy).not.toHaveBeenCalled()
+    } finally {
+      warnSpy.mockRestore()
+    }
+  })
+
+  it('re-probes clean support after the provider is replaced', async () => {
+    mux.request.mockImplementation(async (method) => {
+      if (method === 'git.worktreeIsClean') {
+        throw methodNotFound(method)
+      }
+      return CLEAN_STATUS
     })
     const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
 
     try {
+      await expect(provider.worktreeIsClean('/repo/first')).resolves.toEqual({ clean: true })
+      const replacement = new SshGitProvider('conn-1', mux as never)
+      await expect(replacement.worktreeIsClean('/repo/second')).resolves.toEqual({ clean: true })
+
+      expect(
+        mux.request.mock.calls.filter(([method]) => method === 'git.worktreeIsClean')
+      ).toHaveLength(2)
+      expect(warnSpy).toHaveBeenCalledTimes(2)
+    } finally {
+      warnSpy.mockRestore()
+    }
+  })
+
+  it('worktreeIsClean filters untracked entries in old-relay fallback', async () => {
+    mux.request.mockImplementation(async (method) => {
+      if (method === 'git.worktreeIsClean') {
+        throw methodNotFound(method)
+      }
+      return {
+        entries: [{ path: 'scratch.txt', status: 'untracked', area: 'untracked' }],
+        conflictOperation: 'unknown'
+      }
+    })
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    try {
+      await expect(provider.worktreeIsClean('/home/user/feat')).resolves.toEqual({
+        clean: false,
+        stdout: 'untracked untracked: scratch.txt'
+      })
       await expect(
         provider.worktreeIsClean('/home/user/feat', { includeUntracked: false })
       ).resolves.toEqual({ clean: true })
       expect(mux.request).toHaveBeenNthCalledWith(
-        2,
+        3,
         'git.status',
         { worktreePath: '/home/user/feat' },
         { signal: expect.any(AbortSignal) }
       )
+      expect(
+        mux.request.mock.calls.filter(([method]) => method === 'git.worktreeIsClean')
+      ).toHaveLength(1)
     } finally {
       warnSpy.mockRestore()
     }
@@ -183,11 +378,7 @@ describe('SshGitProvider', () => {
   })
 
   it('forceDeletePreservedBranch maps old relays to the reconnect message', async () => {
-    const methodNotFound = Object.assign(
-      new Error('Method not found: git.forceDeletePreservedBranch'),
-      { code: -32601 }
-    )
-    mux.request.mockRejectedValueOnce(methodNotFound)
+    mux.request.mockRejectedValueOnce(methodNotFound('git.forceDeletePreservedBranch'))
 
     await expect(
       provider.forceDeletePreservedBranch('/home/user/repo', 'you/fix-auth', 'abc123')
diff --git a/src/main/providers/ssh-git-worktree-provider.ts b/src/main/providers/ssh-git-worktree-provider.ts
index ce509ccf847..d5cf9b5a5e1 100644
--- a/src/main/providers/ssh-git-worktree-provider.ts
+++ b/src/main/providers/ssh-git-worktree-provider.ts
@@ -1,9 +1,12 @@
 import type { GitStatusResult } from '../../shared/git-status-types'
 import type { RemoveWorktreeResult } from '../../shared/worktree/create-types'
 import type { GitWorktreeInfo } from '../../shared/worktree/types'
+import { CapabilityProbeCache } from '../../shared/capability-probe-cache'
 import { isJsonRpcMethodNotFoundError } from './ssh-git-relay-errors'
 import { SshGitReviewHeadProvider } from './ssh-git-review-head-provider'
 
+const WORKTREE_IS_CLEAN_CAPABILITY = 'git.worktreeIsClean' as const
+
 function formatStatusEntriesForCleanCheck(entries: GitStatusResult['entries']): string | undefined {
   if (entries.length === 0) {
     return undefined
@@ -20,6 +23,10 @@ function filterUntrackedPorcelainStatus(stdout: string | undefined): string | un
 
 export class SshGitWorktreeProvider extends SshGitReviewHeadProvider {
   private loggedWorktreeIsCleanFallback = false
+  // Why: reconnect replaces this provider, so an upgraded relay is naturally re-probed.
+  private readonly worktreeIsCleanCapabilityCache = new CapabilityProbeCache<
+    typeof WORKTREE_IS_CLEAN_CAPABILITY
+  >(Number.POSITIVE_INFINITY)
 
   async listWorktrees(
     repoPath: string,
@@ -67,37 +74,39 @@ export class SshGitWorktreeProvider extends SshGitReviewHeadProvider {
     worktreePath: string,
     options: { includeUntracked?: boolean } = {}
   ): Promise<{ clean: boolean; stdout?: string }> {
-    try {
-      const result = (await this.mux.request('git.worktreeIsClean', {
-        worktreePath,
-        ...(options.includeUntracked === false ? { includeUntracked: false } : {})
-      })) as { clean: boolean; stdout?: string }
-      if (options.includeUntracked === false) {
-        if (!result.clean && result.stdout === undefined) {
-          return result
+    return this.worktreeIsCleanCapabilityCache.runWithFallback(
+      WORKTREE_IS_CLEAN_CAPABILITY,
+      async () => {
+        const result = (await this.mux.request('git.worktreeIsClean', {
+          worktreePath,
+          ...(options.includeUntracked === false ? { includeUntracked: false } : {})
+        })) as { clean: boolean; stdout?: string }
+        if (options.includeUntracked === false) {
+          if (!result.clean && result.stdout === undefined) {
+            return result
+          }
+          const trackedStdout = filterUntrackedPorcelainStatus(result.stdout)
+          return { clean: !trackedStdout, ...(trackedStdout ? { stdout: trackedStdout } : {}) }
         }
-        const trackedStdout = filterUntrackedPorcelainStatus(result.stdout)
-        return { clean: !trackedStdout, ...(trackedStdout ? { stdout: trackedStdout } : {}) }
-      }
-      return result
-    } catch (error) {
-      if (!isJsonRpcMethodNotFoundError(error)) {
-        throw error
-      }
-      if (!this.loggedWorktreeIsCleanFallback) {
-        this.loggedWorktreeIsCleanFallback = true
-        console.warn(
-          '[ssh-git] Relay does not implement git.worktreeIsClean; falling back to git.status clean check'
-        )
-      }
-      const status = await this.getStatus(worktreePath)
-      const entries =
-        options.includeUntracked === false
-          ? status.entries.filter((entry) => entry.area !== 'untracked')
-          : status.entries
-      const clean = entries.length === 0
-      return { clean, stdout: formatStatusEntriesForCleanCheck(entries) }
-    }
+        return result
+      },
+      async () => {
+        if (!this.loggedWorktreeIsCleanFallback) {
+          this.loggedWorktreeIsCleanFallback = true
+          console.warn(
+            '[ssh-git] Relay does not implement git.worktreeIsClean; falling back to git.status clean check'
+          )
+        }
+        const status = await this.getStatus(worktreePath)
+        const entries =
+          options.includeUntracked === false
+            ? status.entries.filter((entry) => entry.area !== 'untracked')
+            : status.entries
+        const clean = entries.length === 0
+        return { clean, stdout: formatStatusEntriesForCleanCheck(entries) }
+      },
+      isJsonRpcMethodNotFoundError
+    )
   }
 
   async refreshLocalBaseRefForWorktreeCreate(args: {

From ad499df8937e11559909205afe8577a38b49b4ee Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sat, 29 Aug 2026 16:01:33 -0700
Subject: [PATCH 06/31] perf(markdown): reuse rich eligibility state (#17219)

---
 ...orContent.markdown-classification.test.tsx | 292 ++++++++++++++++++
 .../EditorContent.monaco-lifecycle.test.tsx   |   5 +
 .../components/editor/EditorContent.test.tsx  |   4 +
 .../src/components/editor/EditorContent.tsx   |   4 +
 .../editor/EditorEditFileSurface.tsx          |   4 +
 .../editor/EditorMarkdownFileSurface.tsx      |  17 +-
 .../components/editor/EditorPanelShell.tsx    |   1 +
 .../editor/editor-panel-render-model.ts       |  46 ++-
 .../components/editor/markdown-render-mode.ts |   5 +
 9 files changed, 355 insertions(+), 23 deletions(-)
 create mode 100644 src/renderer/src/components/editor/EditorContent.markdown-classification.test.tsx

diff --git a/src/renderer/src/components/editor/EditorContent.markdown-classification.test.tsx b/src/renderer/src/components/editor/EditorContent.markdown-classification.test.tsx
new file mode 100644
index 00000000000..7d8767071be
--- /dev/null
+++ b/src/renderer/src/components/editor/EditorContent.markdown-classification.test.tsx
@@ -0,0 +1,292 @@
+// @vitest-environment happy-dom
+import { cleanup, render } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { OpenFile } from '@/store/slices/editor'
+import type { FileContent } from './editor-panel-content-types'
+
+const classifiers = vi.hoisted(() => ({
+  getUnsupportedMessage: vi.fn<(content: string) => string | null>(),
+  exceedsSizeLimit: vi.fn<(content: string) => boolean>()
+}))
+
+vi.mock('./markdown-rich-mode', () => ({
+  getMarkdownRichModeUnsupportedMessage: classifiers.getUnsupportedMessage
+}))
+
+vi.mock('./markdown-rich-size-limit', () => ({
+  exceedsMarkdownRichModeSizeLimit: classifiers.exceedsSizeLimit
+}))
+
+vi.mock('./editor-lazy-views', () => {
+  const view = (name: string) => () => <div data-editor-view={name} />
+  return {
+    MonacoEditor: view('source'),
+    DiffViewer: view('diff'),
+    CombinedDiffViewer: view('combined-diff'),
+    RichMarkdownEditor: view('rich-editor'),
+    MarkdownPreview: view('preview'),
+    ImageViewer: view('image'),
+    ImageDiffViewer: view('image-diff'),
+    MermaidViewer: view('mermaid'),
+    CsvViewer: view('csv'),
+    IpynbViewer: view('notebook')
+  }
+})
+
+vi.mock('./RichMarkdownErrorBoundary', () => ({
+  RichMarkdownErrorBoundary: ({ children }: { children: React.ReactNode }) => children
+}))
+
+vi.mock('./useMarkdownDocuments', () => ({
+  useMarkdownDocuments: () => ({
+    markdownDocuments: [],
+    onOpenDocLink: () => {},
+    previewProps: { markdownDocuments: [], onOpenDocument: async () => {} },
+    mdSave: async () => true
+  })
+}))
+
+vi.mock('./useEditorConflictNavigation', () => ({
+  useEditorConflictNavigation: () => () => undefined
+}))
+
+vi.mock('@/store', () => {
+  const state = {
+    markdownRichModeSizeOverride: {},
+    setMarkdownRichModeSizeOverride: () => {},
+    reloadOpenCheckRunDetailsTab: () => {}
+  }
+  return {
+    useAppStore: Object.assign(
+      (selector: (storeState: typeof state) => unknown) => selector(state),
+      { getState: () => state }
+    )
+  }
+})
+
+import { EditorContent } from './EditorContent'
+import { getEditorPanelRenderModel } from './editor-panel-render-model'
+
+function openFile(
+  language: 'markdown' | 'typescript' = 'markdown',
+  mode: 'edit' | 'markdown-preview' = 'edit'
+): OpenFile {
+  const extension = language === 'markdown' ? 'md' : 'ts'
+  return {
+    id: `/repo/notes.${extension}`,
+    filePath: `/repo/notes.${extension}`,
+    relativePath: `notes.${extension}`,
+    worktreeId: 'wt-1',
+    language,
+    mode,
+    isDirty: false
+  }
+}
+
+function renderEditPath({
+  content,
+  language = 'markdown',
+  viewMode = 'rich',
+  mode = 'edit'
+}: {
+  content: string
+  language?: 'markdown' | 'typescript'
+  viewMode?: 'source' | 'rich' | 'preview'
+  mode?: 'edit' | 'markdown-preview'
+}) {
+  const activeFile = openFile(language, mode)
+  const fileContents = {
+    [activeFile.id]: { content: '# Saved', isBinary: false }
+  }
+  const editorDrafts = { [activeFile.id]: content }
+  const model = getEditorPanelRenderModel({
+    activeFile,
+    fileContents,
+    editorDrafts,
+    gitStatusEntries: undefined,
+    gitBranchEntries: undefined,
+    markdownViewMode: { [activeFile.id]: viewMode },
+    markdownRichModeSizeOverride: {},
+    isChangesMode: false,
+    canOpenWorkspaceFileBrowser: true
+  })
+  const view = render(
+    <EditorContent
+      activeFile={activeFile}
+      viewStateScopeId={activeFile.id}
+      fileContents={fileContents}
+      diffContents={{}}
+      editBuffers={editorDrafts}
+      openFiles={[activeFile]}
+      worktreeEntries={[]}
+      resolvedLanguage={model.resolvedLanguage}
+      isMarkdown={model.isMarkdown}
+      isMermaid={model.isMermaid}
+      isCsv={model.isCsv}
+      isNotebook={model.isNotebook}
+      mdViewMode={model.mdViewMode}
+      inlineMarkdownRenderState={model.inlineMarkdownRenderState}
+      isChangesMode={false}
+      sideBySide={false}
+      pendingEditorReveal={null}
+      handleContentChange={vi.fn()}
+      handleContentChangeForFile={vi.fn()}
+      handleDirtyStateHint={vi.fn()}
+      handleSave={vi.fn()}
+      handleSaveForFile={vi.fn()}
+      reloadContent={vi.fn()}
+    />
+  )
+
+  return { model, view }
+}
+
+function getGuardedRenderModel({
+  activeFileOverrides,
+  fileContent = { content: '# Saved', isBinary: false },
+  includeFileContent = true,
+  isChangesMode = false
+}: {
+  activeFileOverrides?: Partial<OpenFile>
+  fileContent?: FileContent
+  includeFileContent?: boolean
+  isChangesMode?: boolean
+}) {
+  const activeFile = { ...openFile(), ...activeFileOverrides }
+  return getEditorPanelRenderModel({
+    activeFile,
+    fileContents: includeFileContent ? { [activeFile.id]: fileContent } : {},
+    editorDrafts: { [activeFile.id]: '# Draft' },
+    gitStatusEntries: undefined,
+    gitBranchEntries: undefined,
+    markdownViewMode: { [activeFile.id]: 'rich' },
+    markdownRichModeSizeOverride: {},
+    isChangesMode,
+    canOpenWorkspaceFileBrowser: true
+  })
+}
+
+beforeEach(() => {
+  classifiers.getUnsupportedMessage.mockImplementation((content) =>
+    content.includes('[reference]:') ? 'Reference links require source mode.' : null
+  )
+  classifiers.exceedsSizeLimit.mockImplementation((content) => content.includes('oversized'))
+})
+
+afterEach(() => {
+  cleanup()
+  vi.clearAllMocks()
+})
+
+describe('inline Markdown render classification', () => {
+  it('classifies each rich draft once, including after content changes', () => {
+    const first = renderEditPath({ content: '# First draft' })
+
+    expect(first.view.container.innerHTML).toContain('data-editor-view="rich-editor"')
+    expect(classifiers.getUnsupportedMessage).toHaveBeenCalledTimes(1)
+    expect(classifiers.getUnsupportedMessage).toHaveBeenLastCalledWith('# First draft')
+    expect(classifiers.exceedsSizeLimit).toHaveBeenCalledTimes(1)
+    expect(classifiers.exceedsSizeLimit).toHaveBeenLastCalledWith('# First draft')
+
+    first.view.unmount()
+    const second = renderEditPath({ content: '# Changed draft' })
+
+    expect(second.view.container.innerHTML).toContain('data-editor-view="rich-editor"')
+    expect(classifiers.getUnsupportedMessage).toHaveBeenCalledTimes(2)
+    expect(classifiers.getUnsupportedMessage).toHaveBeenLastCalledWith('# Changed draft')
+    expect(classifiers.exceedsSizeLimit).toHaveBeenCalledTimes(2)
+    expect(classifiers.exceedsSizeLimit).toHaveBeenLastCalledWith('# Changed draft')
+  })
+
+  it.each([
+    {
+      name: 'source Markdown',
+      args: { content: '# Source', viewMode: 'source' as const },
+      expectedView: 'source',
+      canExport: false
+    },
+    {
+      name: 'Markdown preview',
+      args: { content: '# Preview', mode: 'markdown-preview' as const },
+      expectedView: 'preview',
+      canExport: true
+    },
+    {
+      name: 'TypeScript',
+      args: { content: 'const value = 1', language: 'typescript' as const },
+      expectedView: 'source',
+      canExport: false
+    }
+  ])('skips rich eligibility scans for $name', ({ args, expectedView, canExport }) => {
+    const result = renderEditPath(args)
+
+    expect(result.view.container.innerHTML).toContain(`data-editor-view="${expectedView}"`)
+    expect(result.model.canExportMarkdownToPdf).toBe(canExport)
+    expect(classifiers.getUnsupportedMessage).not.toHaveBeenCalled()
+    expect(classifiers.exceedsSizeLimit).not.toHaveBeenCalled()
+  })
+
+  it.each([
+    { name: 'Changes mode', args: { isChangesMode: true } },
+    { name: 'content that is still loading', args: { includeFileContent: false } },
+    {
+      name: 'binary content',
+      args: { fileContent: { content: '', isBinary: true } }
+    },
+    {
+      name: 'content with a load error',
+      args: { fileContent: { content: '', isBinary: false, loadError: 'Read failed' } }
+    },
+    {
+      name: 'read-only Markdown',
+      args: { activeFileOverrides: { readOnly: true } }
+    },
+    {
+      name: 'an unresolved conflict',
+      args: {
+        activeFileOverrides: {
+          conflict: {
+            kind: 'conflict-editable' as const,
+            conflictKind: 'both_modified' as const,
+            conflictStatus: 'unresolved' as const,
+            conflictStatusSource: 'git' as const
+          }
+        }
+      }
+    },
+    {
+      name: 'a conflict placeholder',
+      args: {
+        activeFileOverrides: {
+          conflict: {
+            kind: 'conflict-placeholder' as const,
+            conflictKind: 'both_deleted' as const,
+            conflictStatus: 'unresolved' as const,
+            conflictStatusSource: 'git' as const
+          }
+        }
+      }
+    }
+  ])('skips rich eligibility scans for $name', ({ args }) => {
+    const model = getGuardedRenderModel(args)
+
+    expect(model.inlineMarkdownRenderState).toBeNull()
+    expect(classifiers.getUnsupportedMessage).not.toHaveBeenCalled()
+    expect(classifiers.exceedsSizeLimit).not.toHaveBeenCalled()
+  })
+
+  it('preserves unsupported and oversized rich-mode fallbacks', () => {
+    const unsupported = renderEditPath({ content: '[reference]: https://example.com' })
+
+    expect(unsupported.model.canExportMarkdownToPdf).toBe(false)
+    expect(unsupported.view.getByText('Reference links require source mode.')).toBeTruthy()
+    expect(unsupported.view.queryByText('Open anyway')).toBeNull()
+    unsupported.view.unmount()
+
+    const oversized = renderEditPath({ content: '# oversized' })
+
+    expect(oversized.model.canExportMarkdownToPdf).toBe(false)
+    expect(oversized.view.getByText(/File is larger than the .* rich editing limit/)).toBeTruthy()
+    expect(oversized.view.getByText('Open anyway')).toBeTruthy()
+  })
+})
diff --git a/src/renderer/src/components/editor/EditorContent.monaco-lifecycle.test.tsx b/src/renderer/src/components/editor/EditorContent.monaco-lifecycle.test.tsx
index 53eec01d0d8..00ded9527d2 100644
--- a/src/renderer/src/components/editor/EditorContent.monaco-lifecycle.test.tsx
+++ b/src/renderer/src/components/editor/EditorContent.monaco-lifecycle.test.tsx
@@ -184,6 +184,7 @@ function props(activeFile: OpenFile, content: string) {
     isCsv: false,
     isNotebook: false,
     mdViewMode: 'rich' as const,
+    inlineMarkdownRenderState: null,
     isChangesMode: false,
     sideBySide: false,
     pendingEditorReveal: null,
@@ -326,6 +327,10 @@ describe('EditorContent Monaco lifecycle boundary', () => {
         resolvedLanguage="markdown"
         isMarkdown
         mdViewMode="rich"
+        inlineMarkdownRenderState={{
+          renderMode: 'rich-editor',
+          richModeUnsupportedMessage: null
+        }}
       />
     )
 
diff --git a/src/renderer/src/components/editor/EditorContent.test.tsx b/src/renderer/src/components/editor/EditorContent.test.tsx
index 130c92abe35..8086851a81c 100644
--- a/src/renderer/src/components/editor/EditorContent.test.tsx
+++ b/src/renderer/src/components/editor/EditorContent.test.tsx
@@ -67,6 +67,7 @@ describe('EditorContent', () => {
         isCsv={false}
         isNotebook
         mdViewMode="rich"
+        inlineMarkdownRenderState={null}
         isChangesMode={false}
         sideBySide={false}
         pendingEditorReveal={null}
@@ -108,6 +109,7 @@ describe('EditorContent', () => {
         isCsv={false}
         isNotebook={false}
         mdViewMode="rich"
+        inlineMarkdownRenderState={null}
         isChangesMode={false}
         sideBySide={false}
         pendingEditorReveal={null}
@@ -153,6 +155,7 @@ describe('EditorContent', () => {
         isCsv={false}
         isNotebook={false}
         mdViewMode="rich"
+        inlineMarkdownRenderState={null}
         isChangesMode={false}
         sideBySide={false}
         pendingEditorReveal={null}
@@ -200,6 +203,7 @@ describe('EditorContent', () => {
         isCsv={false}
         isNotebook={false}
         mdViewMode="preview"
+        inlineMarkdownRenderState={null}
         isChangesMode={false}
         sideBySide={false}
         pendingEditorReveal={null}
diff --git a/src/renderer/src/components/editor/EditorContent.tsx b/src/renderer/src/components/editor/EditorContent.tsx
index ca12823e846..9fab1cd5665 100644
--- a/src/renderer/src/components/editor/EditorContent.tsx
+++ b/src/renderer/src/components/editor/EditorContent.tsx
@@ -12,6 +12,7 @@ import type { FileContent } from './editor-panel-content-types'
 import { translate } from '@/i18n/i18n'
 import { useEditorConflictNavigation } from './useEditorConflictNavigation'
 import { useMarkdownDocuments } from './useMarkdownDocuments'
+import type { MarkdownRenderState } from './markdown-render-mode'
 
 const noopCloseMarkdownTableOfContents = (): void => {}
 
@@ -47,6 +48,7 @@ export function EditorContent({
   isCsv,
   isNotebook,
   mdViewMode,
+  inlineMarkdownRenderState,
   isChangesMode,
   sideBySide,
   showMarkdownTableOfContents = false,
@@ -74,6 +76,7 @@ export function EditorContent({
   isCsv: boolean
   isNotebook: boolean
   mdViewMode: MarkdownViewMode
+  inlineMarkdownRenderState: MarkdownRenderState | null
   isChangesMode: boolean
   sideBySide: boolean
   showMarkdownTableOfContents?: boolean
@@ -238,6 +241,7 @@ export function EditorContent({
         isCsv={isCsv}
         isNotebook={isNotebook}
         mdViewMode={mdViewMode}
+        inlineMarkdownRenderState={inlineMarkdownRenderState}
         isChangesMode={isChangesMode}
         sideBySide={sideBySide}
         showMarkdownTableOfContents={showMarkdownTableOfContents}
diff --git a/src/renderer/src/components/editor/EditorEditFileSurface.tsx b/src/renderer/src/components/editor/EditorEditFileSurface.tsx
index d0b83539ee6..06a7bb3f909 100644
--- a/src/renderer/src/components/editor/EditorEditFileSurface.tsx
+++ b/src/renderer/src/components/editor/EditorEditFileSurface.tsx
@@ -17,6 +17,7 @@ import type { FileContent } from './editor-panel-content-types'
 import { ExternalFileChangeBanner } from './ExternalFileChangeBanner'
 import type { useMarkdownDocuments } from './useMarkdownDocuments'
 import { EditorMarkdownFileSurface } from './EditorMarkdownFileSurface'
+import type { MarkdownRenderState } from './markdown-render-mode'
 
 const noopEditorContentChange = (_content: string): void => {}
 const noopEditorSave = async (_content: string): Promise<boolean> => false
@@ -39,6 +40,7 @@ export function EditorEditFileSurface({
   isCsv,
   isNotebook,
   mdViewMode,
+  inlineMarkdownRenderState,
   isChangesMode,
   sideBySide,
   showMarkdownTableOfContents,
@@ -69,6 +71,7 @@ export function EditorEditFileSurface({
   isCsv: boolean
   isNotebook: boolean
   mdViewMode: MarkdownViewMode
+  inlineMarkdownRenderState: MarkdownRenderState | null
   isChangesMode: boolean
   sideBySide: boolean
   showMarkdownTableOfContents: boolean
@@ -210,6 +213,7 @@ export function EditorEditFileSurface({
       editorViewStateKey={editorViewStateKey}
       currentContent={currentContent}
       mdViewMode={mdViewMode}
+      inlineMarkdownRenderState={inlineMarkdownRenderState}
       showMarkdownTableOfContents={showMarkdownTableOfContents}
       showMarkdownFrontmatter={showMarkdownFrontmatter}
       onCloseMarkdownTableOfContents={onCloseMarkdownTableOfContents}
diff --git a/src/renderer/src/components/editor/EditorMarkdownFileSurface.tsx b/src/renderer/src/components/editor/EditorMarkdownFileSurface.tsx
index 6d5cfea1bdf..fda81b98462 100644
--- a/src/renderer/src/components/editor/EditorMarkdownFileSurface.tsx
+++ b/src/renderer/src/components/editor/EditorMarkdownFileSurface.tsx
@@ -5,10 +5,8 @@ import { Button } from '@/components/ui/button'
 import { RICH_MARKDOWN_MAX_SIZE_BYTES } from '../../../../shared/constants'
 import { formatBytes } from '../status-bar/workspace-space-format'
 import { MarkdownPreview, RichMarkdownEditor } from './editor-lazy-views'
-import { exceedsMarkdownRichModeSizeLimit } from './markdown-rich-size-limit'
 import { extractFrontMatter, prependFrontMatter } from './markdown-frontmatter'
-import { getMarkdownRenderMode } from './markdown-render-mode'
-import { getMarkdownRichModeUnsupportedMessage } from './markdown-rich-mode'
+import type { MarkdownRenderState } from './markdown-render-mode'
 import { RichMarkdownErrorBoundary } from './RichMarkdownErrorBoundary'
 import type { useMarkdownDocuments } from './useMarkdownDocuments'
 
@@ -20,6 +18,7 @@ export function EditorMarkdownFileSurface({
   editorViewStateKey,
   currentContent,
   mdViewMode,
+  inlineMarkdownRenderState,
   showMarkdownTableOfContents,
   showMarkdownFrontmatter,
   onCloseMarkdownTableOfContents,
@@ -35,6 +34,7 @@ export function EditorMarkdownFileSurface({
   editorViewStateKey: string
   currentContent: string
   mdViewMode: MarkdownViewMode
+  inlineMarkdownRenderState: MarkdownRenderState | null
   showMarkdownTableOfContents: boolean
   showMarkdownFrontmatter: boolean
   onCloseMarkdownTableOfContents: () => void
@@ -45,18 +45,15 @@ export function EditorMarkdownFileSurface({
   handleDirtyStateHint: (dirty: boolean) => void
   monacoEditor: React.JSX.Element
 }): React.JSX.Element {
-  const sizeOverridden = useAppStore((s) => s.markdownRichModeSizeOverride[activeFile.id] === true)
   const setSizeOverride = useAppStore((s) => s.setMarkdownRichModeSizeOverride)
-  const richModeUnsupportedMessage = getMarkdownRichModeUnsupportedMessage(currentContent)
-  const renderMode = getMarkdownRenderMode({
-    exceedsRichModeSizeLimit: !sizeOverridden && exceedsMarkdownRichModeSizeLimit(currentContent),
-    hasRichModeUnsupportedContent: richModeUnsupportedMessage !== null,
-    viewMode: mdViewMode
-  })
 
   if (activeFile.conflict?.conflictStatus === 'unresolved') {
     return <div className="h-full min-h-0">{monacoEditor}</div>
   }
+  if (!inlineMarkdownRenderState) {
+    return <div className="h-full min-h-0">{monacoEditor}</div>
+  }
+  const { renderMode, richModeUnsupportedMessage } = inlineMarkdownRenderState
   if (renderMode === 'source' && mdViewMode === 'rich') {
     // Why: only a size fallback is recoverable — unsupported syntax would round-trip badly, so it gets no override.
     const isSizeFallback = richModeUnsupportedMessage === null
diff --git a/src/renderer/src/components/editor/EditorPanelShell.tsx b/src/renderer/src/components/editor/EditorPanelShell.tsx
index 62b399c3b3c..dd15231cefe 100644
--- a/src/renderer/src/components/editor/EditorPanelShell.tsx
+++ b/src/renderer/src/components/editor/EditorPanelShell.tsx
@@ -149,6 +149,7 @@ export function EditorPanelShell({
           isCsv={model.isCsv}
           isNotebook={model.isNotebook}
           mdViewMode={model.mdViewMode}
+          inlineMarkdownRenderState={model.inlineMarkdownRenderState}
           isChangesMode={model.isDiffSurface && !model.isSingleDiff}
           sideBySide={sideBySide}
           pendingEditorReveal={pendingEditorReveal}
diff --git a/src/renderer/src/components/editor/editor-panel-render-model.ts b/src/renderer/src/components/editor/editor-panel-render-model.ts
index 2dc9fe87382..8a479794f83 100644
--- a/src/renderer/src/components/editor/editor-panel-render-model.ts
+++ b/src/renderer/src/components/editor/editor-panel-render-model.ts
@@ -12,7 +12,7 @@ import { getEditorHeaderOpenFileState } from './editor-header'
 import type { EditorToggleValue } from './EditorViewToggle'
 import type { FileContent } from './editor-panel-content-types'
 import { canUseChangesModeForFile } from './editor-panel-file-mode'
-import { getMarkdownRenderMode } from './markdown-render-mode'
+import { getMarkdownRenderMode, type MarkdownRenderState } from './markdown-render-mode'
 import { getMarkdownRichModeUnsupportedMessage } from './markdown-rich-mode'
 import { exceedsMarkdownRichModeSizeLimit } from './markdown-rich-size-limit'
 
@@ -129,17 +129,36 @@ export function getEditorPanelRenderModel({
   const shouldShowMarkdownExportAction =
     viewerLanguage === 'markdown' &&
     (activeFile.mode === 'edit' || activeFile.mode === 'markdown-preview')
-  const inlineMarkdownRenderMode =
-    activeFile.mode === 'edit' && inlineMarkdownContent !== null
-      ? getMarkdownRenderMode({
-          exceedsRichModeSizeLimit:
-            markdownRichModeSizeOverride[activeFile.id] !== true &&
-            exceedsMarkdownRichModeSizeLimit(inlineMarkdownContent),
-          hasRichModeUnsupportedContent:
-            getMarkdownRichModeUnsupportedMessage(inlineMarkdownContent) !== null,
-          viewMode: mdViewMode
-        })
+  const inlineFileContent = activeFile.mode === 'edit' ? fileContents[activeFile.id] : undefined
+  const canRenderInlineMarkdown =
+    viewerLanguage === 'markdown' &&
+    activeFile.mode === 'edit' &&
+    inlineMarkdownContent !== null &&
+    !isChangesMode &&
+    inlineFileContent !== undefined &&
+    inlineFileContent.isBinary !== true &&
+    !inlineFileContent.loadError &&
+    activeFile.conflict?.kind !== 'conflict-placeholder' &&
+    activeFile.conflict?.conflictStatus !== 'unresolved'
+  let inlineMarkdownRenderState: MarkdownRenderState | null = null
+  if (canRenderInlineMarkdown) {
+    const shouldClassifyRichMode = mdViewMode === 'rich'
+    const exceedsRichModeSizeLimit =
+      shouldClassifyRichMode &&
+      markdownRichModeSizeOverride[activeFile.id] !== true &&
+      exceedsMarkdownRichModeSizeLimit(inlineMarkdownContent)
+    const richModeUnsupportedMessage = shouldClassifyRichMode
+      ? getMarkdownRichModeUnsupportedMessage(inlineMarkdownContent)
       : null
+    inlineMarkdownRenderState = {
+      renderMode: getMarkdownRenderMode({
+        exceedsRichModeSizeLimit,
+        hasRichModeUnsupportedContent: richModeUnsupportedMessage !== null,
+        viewMode: mdViewMode
+      }),
+      richModeUnsupportedMessage
+    }
+  }
   const canExportMarkdownToPdf =
     shouldShowMarkdownExportAction &&
     ((activeFile.mode === 'markdown-preview' &&
@@ -149,8 +168,8 @@ export function getEditorPanelRenderModel({
       (activeFile.mode === 'edit' &&
         fileContents[activeFile.id] !== undefined &&
         !isChangesMode &&
-        inlineMarkdownRenderMode !== null &&
-        inlineMarkdownRenderMode !== 'source' &&
+        inlineMarkdownRenderState !== null &&
+        inlineMarkdownRenderState.renderMode !== 'source' &&
         fileContents[activeFile.id]?.isBinary !== true &&
         !fileContents[activeFile.id]?.loadError &&
         activeFile.conflict?.conflictStatus !== 'unresolved'))
@@ -180,6 +199,7 @@ export function getEditorPanelRenderModel({
     isMarkdownTableOfContentsDisabled: hasViewModeToggle && mdViewMode === 'source',
     shouldShowMarkdownExportAction,
     canExportMarkdownToPdf,
+    inlineMarkdownRenderState,
     canShowMarkdownTableOfContents:
       viewerLanguage === 'markdown' &&
       (hasViewModeToggle || activeFile.mode === 'markdown-preview'),
diff --git a/src/renderer/src/components/editor/markdown-render-mode.ts b/src/renderer/src/components/editor/markdown-render-mode.ts
index b8cbc499986..f188dcbb814 100644
--- a/src/renderer/src/components/editor/markdown-render-mode.ts
+++ b/src/renderer/src/components/editor/markdown-render-mode.ts
@@ -2,6 +2,11 @@ import type { MarkdownViewMode } from '@/store/slices/editor'
 
 export type MarkdownRenderMode = 'source' | 'rich-editor' | 'preview'
 
+export type MarkdownRenderState = {
+  renderMode: MarkdownRenderMode
+  richModeUnsupportedMessage: string | null
+}
+
 export function getMarkdownRenderMode({
   exceedsRichModeSizeLimit,
   hasRichModeUnsupportedContent,

From 5e3c4f391cc2588728e99d79fea30c92e51c795d Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sat, 29 Aug 2026 16:01:36 -0700
Subject: [PATCH 07/31] perf(terminal): bound stalled setup-split polling
 (#17228)

---
 .../terminal-startup-grid-settle.test.ts      | 24 +++++++++++++++++++
 .../terminal-startup-grid-settle.ts           | 15 ++++++++++++
 2 files changed, 39 insertions(+)

diff --git a/src/renderer/src/components/terminal-pane/terminal-startup-grid-settle.test.ts b/src/renderer/src/components/terminal-pane/terminal-startup-grid-settle.test.ts
index ebe5064be3c..dd7e56ab328 100644
--- a/src/renderer/src/components/terminal-pane/terminal-startup-grid-settle.test.ts
+++ b/src/renderer/src/components/terminal-pane/terminal-startup-grid-settle.test.ts
@@ -115,6 +115,30 @@ describe('waitForStableStartupGrid', () => {
     expect(onSettled).toHaveBeenCalledWith({ cols: 88, rows: 50 })
   })
 
+  it('stops polling at the default cap when the external split gate never opens', () => {
+    const scheduler = createFrameScheduler()
+    const onSettled = vi.fn()
+    const measure = vi.fn(() => ({ cols: 88, rows: 50 }))
+
+    waitForStableStartupGrid({
+      isAlive: () => true,
+      isReadyToSettle: () => false,
+      measure,
+      onSettled,
+      requestFrame: scheduler.requestFrame,
+      cancelFrame: scheduler.cancelFrame
+    })
+
+    expect(scheduler.run(119)).toBe(119)
+    expect(scheduler.pending()).toBe(1)
+    expect(onSettled).not.toHaveBeenCalled()
+
+    expect(scheduler.run(10)).toBe(1)
+    expect(scheduler.pending()).toBe(0)
+    expect(measure).toHaveBeenCalledTimes(120)
+    expect(onSettled).toHaveBeenCalledWith({ cols: 88, rows: 50 })
+  })
+
   it('uses the latest usable grid at the frame cap when dimensions keep changing', () => {
     const scheduler = createFrameScheduler()
     const onSettled = vi.fn()
diff --git a/src/renderer/src/components/terminal-pane/terminal-startup-grid-settle.ts b/src/renderer/src/components/terminal-pane/terminal-startup-grid-settle.ts
index 5ed9d704670..8df3d42d6c6 100644
--- a/src/renderer/src/components/terminal-pane/terminal-startup-grid-settle.ts
+++ b/src/renderer/src/components/terminal-pane/terminal-startup-grid-settle.ts
@@ -13,6 +13,7 @@ export type TerminalStartupGridSettleOptions = {
   minFrames?: number
   stableFrames?: number
   maxFrames?: number
+  maxReadinessWaitFrames?: number
 }
 
 export type TerminalStartupGridSettleHandle = {
@@ -22,6 +23,8 @@ export type TerminalStartupGridSettleHandle = {
 const DEFAULT_MIN_FRAMES = 6
 const DEFAULT_STABLE_FRAMES = 2
 const DEFAULT_MAX_FRAMES = 12
+// Why: ten settle windows tolerate slow split layout without permitting permanent polling.
+const DEFAULT_MAX_READINESS_WAIT_FRAMES = DEFAULT_MAX_FRAMES * 10
 
 function usableDimensions(
   dimensions: TerminalStartupGridDimensions | null
@@ -42,6 +45,10 @@ export function waitForStableStartupGrid(
   const minFrames = Math.max(1, options.minFrames ?? DEFAULT_MIN_FRAMES)
   const stableFrames = Math.max(1, options.stableFrames ?? DEFAULT_STABLE_FRAMES)
   const maxFrames = Math.max(minFrames, options.maxFrames ?? DEFAULT_MAX_FRAMES)
+  const maxReadinessWaitFrames = Math.max(
+    1,
+    options.maxReadinessWaitFrames ?? DEFAULT_MAX_READINESS_WAIT_FRAMES
+  )
   let frame = 0
   let stableFrameCount = 0
   let previous: TerminalStartupGridDimensions | null = null
@@ -50,6 +57,7 @@ export function waitForStableStartupGrid(
   let pendingFrame: number | null = null
   let cancelled = false
   let readyFrame = 0
+  let latestReadinessWaitUsable: TerminalStartupGridDimensions | null = null
   const usesReadinessGate = options.isReadyToSettle !== undefined
 
   const settle = (dimensions: TerminalStartupGridDimensions | null): void => {
@@ -73,6 +81,13 @@ export function waitForStableStartupGrid(
     const measured = options.measure()
     const readyToSettle = options.isReadyToSettle?.() ?? true
     if (!readyToSettle) {
+      if (usableDimensions(measured)) {
+        latestReadinessWaitUsable = measured
+      }
+      if (frame >= maxReadinessWaitFrames) {
+        settle(latestReadinessWaitUsable)
+        return
+      }
       previous = null
       stableFrameCount = 0
       observedGridChange = false

From be68aa271887865ef5567bd5ea97548c38a5ef16 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sat, 29 Aug 2026 16:01:39 -0700
Subject: [PATCH 08/31] perf(browser): release popup origin bar contents
 (#17234)

---
 .../browser/popup-origin-bar-window.test.ts   | 45 +++++++++++++++++++
 src/main/browser/popup-origin-bar-window.ts   | 19 +++++---
 2 files changed, 59 insertions(+), 5 deletions(-)

diff --git a/src/main/browser/popup-origin-bar-window.test.ts b/src/main/browser/popup-origin-bar-window.test.ts
index 3e816e74b07..fedcd4dfdd0 100644
--- a/src/main/browser/popup-origin-bar-window.test.ts
+++ b/src/main/browser/popup-origin-bar-window.test.ts
@@ -285,6 +285,7 @@ describe('openPopupWithOriginBar', () => {
   it('closes the window when the popup content is destroyed, without re-closing the contents', () => {
     const adopted = createFakeWebContents()
     openPopupWithOriginBar({ webContents: adopted as never }, 'https://example.com/')
+    const { bar } = lastViews()
 
     adopted.emit('destroyed')
 
@@ -292,6 +293,7 @@ describe('openPopupWithOriginBar', () => {
     // The window's closed handler must not call close() on already-destroyed
     // contents — that throws in real Electron.
     expect(adopted.close).not.toHaveBeenCalled()
+    expect(bar.webContents.close).toHaveBeenCalledTimes(1)
   })
 
   it('re-asserts the origin when the popup finishes loading', () => {
@@ -326,11 +328,54 @@ describe('openPopupWithOriginBar', () => {
     const adopted = createFakeWebContents()
     const onClosed = vi.fn()
     const popup = openPopupWithOriginBar({ webContents: adopted as never }, 'https://example.com/')
+    const { bar } = lastViews()
     popup.onClosed(onClosed)
 
     popup.close()
 
     expect(adopted.close).toHaveBeenCalledTimes(1)
+    expect(bar.webContents.close).toHaveBeenCalledTimes(1)
     expect(onClosed).toHaveBeenCalledTimes(1)
   })
+
+  it('releases every origin bar across repeated popup lifecycles', () => {
+    const cycleCount = 25
+    const originBars: FakeWebContents[] = []
+
+    for (let cycle = 0; cycle < cycleCount; cycle += 1) {
+      const popup = openPopupWithOriginBar({}, `https://example.com/${cycle}`)
+      originBars.push(lastViews().bar.webContents)
+      popup.close()
+    }
+
+    expect(originBars.filter((contents) => contents.close.mock.calls.length === 1)).toHaveLength(
+      cycleCount
+    )
+  })
+
+  it('tolerates an origin bar destroyed before its window closes', () => {
+    const adopted = createFakeWebContents()
+    const onClosed = vi.fn()
+    const popup = openPopupWithOriginBar({ webContents: adopted as never }, 'https://example.com/')
+    popup.onClosed(onClosed)
+    const { bar } = lastViews()
+    const barWebContents = bar.webContents
+    barWebContents.emit('destroyed')
+    Object.defineProperty(bar, 'webContents', { get: () => undefined })
+
+    expect(() => popup.close()).not.toThrow()
+    expect(adopted.close).toHaveBeenCalledTimes(1)
+    expect(barWebContents.close).not.toHaveBeenCalled()
+    expect(onClosed).toHaveBeenCalledTimes(1)
+  })
+
+  it('closes both child contents when popup preparation fails', () => {
+    const adopted = createFakeWebContents()
+
+    openPopupWithOriginBar({ webContents: adopted as never }, 'https://example.com/', () => false)
+
+    expect(adopted.close).toHaveBeenCalledTimes(1)
+    expect(lastViews().bar.webContents.close).toHaveBeenCalledTimes(1)
+    expect(lastWindow().close).toHaveBeenCalledTimes(1)
+  })
 })
diff --git a/src/main/browser/popup-origin-bar-window.ts b/src/main/browser/popup-origin-bar-window.ts
index 376c318d1ae..cfbe3ef3d3b 100644
--- a/src/main/browser/popup-origin-bar-window.ts
+++ b/src/main/browser/popup-origin-bar-window.ts
@@ -92,7 +92,8 @@ function clampPopupContentSize(options: PopupChildWindowOptions): {
 // caller's popup bookkeeping cannot leak an entry for a window that no longer exists.
 function closeUnpreparedPopup(
   window: BaseWindow,
-  contentWebContents: Electron.WebContents
+  contentWebContents: Electron.WebContents,
+  originBarWebContents: Electron.WebContents
 ): PopupOriginBarWindow {
   const closedListeners: (() => void)[] = []
   let closed = false
@@ -105,6 +106,9 @@ function closeUnpreparedPopup(
   if (!contentWebContents.isDestroyed()) {
     contentWebContents.close()
   }
+  if (!originBarWebContents.isDestroyed()) {
+    originBarWebContents.close()
+  }
   if (!window.isDestroyed()) {
     window.close()
   }
@@ -159,6 +163,7 @@ export function openPopupWithOriginBar(
   const originBarView = new WebContentsView({
     webPreferences: { contextIsolation: true, nodeIntegration: false, sandbox: true }
   })
+  const originBarWebContents = originBarView.webContents
   const contentView = new WebContentsView({
     // Why: Electron rejects an explicitly undefined webContents; omitting it
     // lets WebContentsView create contents for Cmd/Ctrl-click popups.
@@ -188,7 +193,7 @@ export function openPopupWithOriginBar(
 
   const contentWebContents = contentView.webContents
   if (prepareContent && !prepareContent(contentWebContents)) {
-    return closeUnpreparedPopup(window, contentWebContents)
+    return closeUnpreparedPopup(window, contentWebContents, originBarWebContents)
   }
   let currentUrl = initialUrl
   const renderOrigin = (): void => {
@@ -202,15 +207,15 @@ export function openPopupWithOriginBar(
     }
     // Why: textContent + JSON encoding — the URL is attacker-controlled and
     // must never be interpolated into the bar's markup.
-    void originBarView.webContents
+    void originBarWebContents
       .executeJavaScript(
         `document.body.classList.toggle('insecure', ${insecure ? 'true' : 'false'});` +
           `document.getElementById('origin').textContent = ${JSON.stringify(label)};`
       )
       .catch(() => {})
   }
-  originBarView.webContents.once('did-finish-load', renderOrigin)
-  void originBarView.webContents.loadURL(
+  originBarWebContents.once('did-finish-load', renderOrigin)
+  void originBarWebContents.loadURL(
     `data:text/html;charset=utf-8,${encodeURIComponent(ORIGIN_BAR_HTML)}`
   )
 
@@ -253,6 +258,10 @@ export function openPopupWithOriginBar(
       // pages often notify the opener from unload.
       contentWebContents.close()
     }
+    // Why: BaseWindow does not destroy child WebContentsView contents when it closes.
+    if (!originBarWebContents.isDestroyed()) {
+      originBarWebContents.close()
+    }
     for (const listener of closedListeners) {
       listener()
     }

From 79aea811734962d35a0177f5cf734b817543dea2 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sat, 29 Aug 2026 16:01:42 -0700
Subject: [PATCH 09/31] perf(renderer): index unread completion tabs (#17246)

---
 .../terminal-tab-activity-status.test.ts      | 55 +++++++++++++++++++
 .../tab-bar/terminal-tab-activity-status.ts   | 50 ++++++++++++-----
 2 files changed, 90 insertions(+), 15 deletions(-)

diff --git a/src/renderer/src/components/tab-bar/terminal-tab-activity-status.test.ts b/src/renderer/src/components/tab-bar/terminal-tab-activity-status.test.ts
index d2bed923686..bf367f93667 100644
--- a/src/renderer/src/components/tab-bar/terminal-tab-activity-status.test.ts
+++ b/src/renderer/src/components/tab-bar/terminal-tab-activity-status.test.ts
@@ -3,6 +3,7 @@ import type { AgentStatusEntry } from '../../../../shared/agent-status-types'
 import type { TerminalTab } from '../../../../shared/terminal-tab-types'
 import {
   hasUnreadAgentCompletionForTerminalTab,
+  resetUnreadAgentCompletionTabIdsCacheForTest,
   resetTerminalTabActivityFlagsCacheForTest,
   resolveTerminalTabActivityStatus,
   resolveTerminalTabAttentionBadge,
@@ -41,6 +42,7 @@ const LIVE_PTY = { [TAB_ID]: ['pty-1'] }
 
 beforeEach(() => {
   resetTerminalTabActivityFlagsCacheForTest()
+  resetUnreadAgentCompletionTabIdsCacheForTest()
   vi.useFakeTimers()
   vi.setSystemTime(NOW)
 })
@@ -48,6 +50,7 @@ beforeEach(() => {
 afterEach(() => {
   vi.useRealTimers()
   resetTerminalTabActivityFlagsCacheForTest()
+  resetUnreadAgentCompletionTabIdsCacheForTest()
 })
 
 describe('resolveTerminalTabActivityStatus', () => {
@@ -267,6 +270,7 @@ describe('hasUnreadAgentCompletionForTerminalTab', () => {
     expect(
       hasUnreadAgentCompletionForTerminalTab({ [`tab-2:${SECOND_LEAF_ID}`]: true }, TAB_ID)
     ).toBe(false)
+    expect(hasUnreadAgentCompletionForTerminalTab(undefined, TAB_ID)).toBe(false)
   })
 
   // Why: the param accepts boolean maps, so a cleared-to-`false` marker must not read as unread.
@@ -275,6 +279,57 @@ describe('hasUnreadAgentCompletionForTerminalTab', () => {
       hasUnreadAgentCompletionForTerminalTab({ [`${TAB_ID}:${FIRST_LEAF_ID}`]: false }, TAB_ID)
     ).toBe(false)
   })
+
+  it('preserves first-colon ownership for legacy and malformed pane keys', () => {
+    expect(hasUnreadAgentCompletionForTerminalTab({ [TAB_ID]: true }, TAB_ID)).toBe(true)
+    expect(hasUnreadAgentCompletionForTerminalTab({ [`${TAB_ID}:3`]: true }, TAB_ID)).toBe(true)
+    expect(
+      hasUnreadAgentCompletionForTerminalTab(
+        { [`${TAB_ID}:${FIRST_LEAF_ID}:suffix`]: true },
+        TAB_ID
+      )
+    ).toBe(true)
+    expect(
+      hasUnreadAgentCompletionForTerminalTab({ [`${TAB_ID}0:${SECOND_LEAF_ID}`]: true }, TAB_ID)
+    ).toBe(false)
+  })
+
+  it('changes only the owning tab when immutable marker snapshots add and clear unread', () => {
+    const before = { [`tab-2:${SECOND_LEAF_ID}`]: true }
+    const added = { ...before, [`${TAB_ID}:${FIRST_LEAF_ID}`]: true }
+    const cleared = { ...added, [`${TAB_ID}:${FIRST_LEAF_ID}`]: false }
+
+    expect(hasUnreadAgentCompletionForTerminalTab(before, TAB_ID)).toBe(false)
+    expect(hasUnreadAgentCompletionForTerminalTab(added, TAB_ID)).toBe(true)
+    expect(hasUnreadAgentCompletionForTerminalTab(cleared, TAB_ID)).toBe(false)
+    expect(hasUnreadAgentCompletionForTerminalTab(before, 'tab-2')).toBe(true)
+    expect(hasUnreadAgentCompletionForTerminalTab(added, 'tab-2')).toBe(true)
+    expect(hasUnreadAgentCompletionForTerminalTab(cleared, 'tab-2')).toBe(true)
+  })
+
+  it('indexes one immutable marker snapshot once across all mounted tab lookups', () => {
+    const ownKeys = vi.fn(Reflect.ownKeys)
+    let valueReads = 0
+    const markers: Record<string, true> = Object.fromEntries(
+      Array.from({ length: 1_000 }, (_, index) => [`owner-${index}:leaf`, true] as const)
+    )
+    const unread = new Proxy<Record<string, true>>(markers, {
+      ownKeys,
+      get: (target, property, receiver) => {
+        valueReads += 1
+        return Reflect.get(target, property, receiver)
+      }
+    })
+
+    for (let publication = 0; publication < 5; publication += 1) {
+      for (let tab = 0; tab < 500; tab += 1) {
+        expect(hasUnreadAgentCompletionForTerminalTab(unread, `absent-${tab}`)).toBe(false)
+      }
+    }
+
+    expect(ownKeys).toHaveBeenCalledTimes(1)
+    expect(valueReads).toBe(1_000)
+  })
 })
 
 describe('resolveTerminalTabAttentionBadge', () => {
diff --git a/src/renderer/src/components/tab-bar/terminal-tab-activity-status.ts b/src/renderer/src/components/tab-bar/terminal-tab-activity-status.ts
index 97f511a1d41..a801855a588 100644
--- a/src/renderer/src/components/tab-bar/terminal-tab-activity-status.ts
+++ b/src/renderer/src/components/tab-bar/terminal-tab-activity-status.ts
@@ -256,29 +256,49 @@ export function terminalTabHasUnreadActivity({
   )
 }
 
+// Why: production writes replace this map; WeakMap supports retained snapshots without pinning them.
+let unreadAgentCompletionTabIdsBySnapshot = new WeakMap<
+  Record<string, boolean | undefined>,
+  ReadonlySet<string>
+>()
+
+function getUnreadAgentCompletionTabIds(
+  unreadAgentCompletionPanes: Record<string, boolean | undefined>
+): ReadonlySet<string> {
+  const cached = unreadAgentCompletionTabIdsBySnapshot.get(unreadAgentCompletionPanes)
+  if (cached) {
+    return cached
+  }
+
+  // Why: every mounted tab runs this selector per store write; index each immutable marker snapshot once.
+  const tabIds = new Set<string>()
+  for (const paneKey of Object.keys(unreadAgentCompletionPanes)) {
+    if (!unreadAgentCompletionPanes[paneKey]) {
+      continue
+    }
+    const separatorIndex = paneKey.indexOf(':')
+    tabIds.add(separatorIndex === -1 ? paneKey : paneKey.slice(0, separatorIndex))
+  }
+  unreadAgentCompletionTabIdsBySnapshot.set(unreadAgentCompletionPanes, tabIds)
+  return tabIds
+}
+
 /** Match pane-level unread completion markers to their owning terminal tab. */
 export function hasUnreadAgentCompletionForTerminalTab(
   unreadAgentCompletionPanes: Record<string, boolean | undefined> | undefined,
   tabId: string
 ): boolean {
-  for (const [paneKey, unread] of Object.entries(unreadAgentCompletionPanes ?? {})) {
-    // Why entries, not keys: the widened value type lets a cleared marker linger as `false`.
-    if (!unread) {
-      continue
-    }
-    // paneKey is `${tabId}:${leafId}` and tab ids never contain ":", so the
-    // prefix up to the first ":" is the owning tab id (see
-    // selectFloatingWorkspaceHasUnread). Prefix-match to keep legacy keys.
-    const separatorIndex = paneKey.indexOf(':')
-    const owningTabId = separatorIndex === -1 ? paneKey : paneKey.slice(0, separatorIndex)
-    if (owningTabId === tabId) {
-      return true
-    }
-  }
-  return false
+  return unreadAgentCompletionPanes
+    ? getUnreadAgentCompletionTabIds(unreadAgentCompletionPanes).has(tabId)
+    : false
 }
 
 /** Test-only: clear the memoized per-tab flag cache between cases. */
 export function resetTerminalTabActivityFlagsCacheForTest(): void {
   flagsCache = null
 }
+
+/** Test-only: clear the unread marker snapshot index between cases. */
+export function resetUnreadAgentCompletionTabIdsCacheForTest(): void {
+  unreadAgentCompletionTabIdsBySnapshot = new WeakMap()
+}

From e25878588445931b42db2fb05323e62733e7a646 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sat, 29 Aug 2026 16:02:10 -0700
Subject: [PATCH 10/31] perf(terminal): index accepted input pane ownership
 (#17287)

---
 .../runtime-terminal-inspection.test.ts       | 204 ++++++++++++++++++
 .../runtime/runtime-terminal-inspection.ts    |  78 +++++--
 2 files changed, 266 insertions(+), 16 deletions(-)

diff --git a/src/renderer/src/runtime/runtime-terminal-inspection.test.ts b/src/renderer/src/runtime/runtime-terminal-inspection.test.ts
index 4223f6d2b82..766e80f3f6e 100644
--- a/src/renderer/src/runtime/runtime-terminal-inspection.test.ts
+++ b/src/renderer/src/runtime/runtime-terminal-inspection.test.ts
@@ -209,6 +209,53 @@ describe('runtime terminal owner routing', () => {
     })
   })
 
+  it('attributes a delayed runtime acknowledgement to the current layout owner', async () => {
+    const pendingSend = Promise.withResolvers<{
+      ok: true
+      result: { send: { handle: string; accepted: true; bytesWritten: number } }
+      _meta: { runtimeId: string }
+    }>()
+    runtimeCall.mockReturnValue(pendingSend.promise)
+    useAppStore.setState({
+      terminalLayoutsByTabId: {
+        'tab-1': {
+          root: { type: 'leaf', leafId: LEAF_ID },
+          activeLeafId: LEAF_ID,
+          expandedLeafId: null,
+          ptyIdsByLeafId: { [LEAF_ID]: 'remote:env-1@@terminal-1' }
+        }
+      }
+    })
+    recordRuntimeTerminalInputForPtyId('remote:env-1@@terminal-1', 123)
+    useAppStore.setState({ lastTerminalInputAtByPaneKey: {} })
+
+    expect(
+      sendRuntimePtyInput({ activeRuntimeEnvironmentId: 'env-2' }, 'remote:env-1@@terminal-1', 'x')
+    ).toBe(true)
+    const nextLeafId = '22222222-2222-4222-8222-222222222222'
+    useAppStore.setState({
+      terminalLayoutsByTabId: {
+        'tab-2': {
+          root: { type: 'leaf', leafId: nextLeafId },
+          activeLeafId: nextLeafId,
+          expandedLeafId: null,
+          ptyIdsByLeafId: { [nextLeafId]: 'remote:env-1@@terminal-1' }
+        }
+      }
+    })
+    pendingSend.resolve({
+      ok: true,
+      result: { send: { handle: 'terminal-1', accepted: true, bytesWritten: 1 } },
+      _meta: { runtimeId: 'runtime-1' }
+    })
+
+    await vi.waitFor(() => {
+      expect(useAppStore.getState().lastTerminalInputAtByPaneKey).toEqual({
+        [`tab-2:${nextLeafId}`]: expect.any(Number)
+      })
+    })
+  })
+
   it('does not record declined fire-and-forget runtime input', async () => {
     runtimeCall.mockResolvedValue({
       ok: true,
@@ -479,6 +526,163 @@ describe('runtime terminal owner routing', () => {
     expect(useAppStore.getState().lastTerminalInputAtByPaneKey[PANE_KEY]).toBe(123)
   })
 
+  it('indexes a stable layout identity once across repeated terminal input', () => {
+    const layoutCount = 500
+    let layoutEnumerations = 0
+    let leafEnumerations = 0
+    const layouts = Object.fromEntries(
+      Array.from({ length: layoutCount }, (_, index) => {
+        const leafId = `00000000-0000-4000-8000-${index.toString(16).padStart(12, '0')}`
+        const ptyIdsByLeafId = new Proxy(
+          { [leafId]: `pty-${index}` },
+          {
+            ownKeys: (target) => {
+              leafEnumerations += 1
+              return Reflect.ownKeys(target)
+            }
+          }
+        )
+        return [
+          `tab-${index}`,
+          {
+            root: { type: 'leaf' as const, leafId },
+            activeLeafId: leafId,
+            expandedLeafId: null,
+            ptyIdsByLeafId
+          }
+        ]
+      })
+    )
+    const observedLayouts = new Proxy(layouts, {
+      ownKeys: (target) => {
+        layoutEnumerations += 1
+        return Reflect.ownKeys(target)
+      }
+    })
+    useAppStore.setState({ terminalLayoutsByTabId: observedLayouts })
+
+    recordRuntimeTerminalInputForPtyId('pty-0', 10_000)
+    expect({ layoutEnumerations, leafEnumerations }).toEqual({
+      layoutEnumerations: 1,
+      leafEnumerations: 1
+    })
+    layoutEnumerations = 0
+    leafEnumerations = 0
+
+    for (let timestamp = 1; timestamp <= 100; timestamp += 1) {
+      recordRuntimeTerminalInputForPtyId(`pty-${layoutCount - 1}`, timestamp * 10_000)
+    }
+
+    expect({ layoutEnumerations, leafEnumerations }).toEqual({
+      layoutEnumerations: 1,
+      leafEnumerations: layoutCount
+    })
+    expect(
+      useAppStore.getState().lastTerminalInputAtByPaneKey[
+        `tab-${layoutCount - 1}:00000000-0000-4000-8000-${(layoutCount - 1)
+          .toString(16)
+          .padStart(12, '0')}`
+      ]
+    ).toBe(1_000_000)
+  })
+
+  it('reindexes a PTY when the immutable layout identity changes', () => {
+    const nextLeafId = '22222222-2222-4222-8222-222222222222'
+    useAppStore.setState({
+      terminalLayoutsByTabId: {
+        'tab-1': {
+          root: { type: 'leaf', leafId: LEAF_ID },
+          activeLeafId: LEAF_ID,
+          expandedLeafId: null,
+          ptyIdsByLeafId: { [LEAF_ID]: 'rebound-pty' }
+        }
+      }
+    })
+    recordRuntimeTerminalInputForPtyId('rebound-pty', 123)
+
+    useAppStore.setState({
+      terminalLayoutsByTabId: {
+        'tab-2': {
+          root: { type: 'leaf', leafId: nextLeafId },
+          activeLeafId: nextLeafId,
+          expandedLeafId: null,
+          ptyIdsByLeafId: { [nextLeafId]: 'rebound-pty' }
+        }
+      }
+    })
+    recordRuntimeTerminalInputForPtyId('rebound-pty', 1_000)
+
+    expect(useAppStore.getState().lastTerminalInputAtByPaneKey).toEqual({
+      [PANE_KEY]: 123,
+      [`tab-2:${nextLeafId}`]: 1_000
+    })
+  })
+
+  it('reindexes stale owners without caching misses within the same layout identity', () => {
+    const nextLeafId = '22222222-2222-4222-8222-222222222222'
+    useAppStore.setState({
+      terminalLayoutsByTabId: {
+        'tab-1': {
+          root: { type: 'leaf', leafId: LEAF_ID },
+          activeLeafId: LEAF_ID,
+          expandedLeafId: null,
+          ptyIdsByLeafId: { [LEAF_ID]: 'rebound-pty' }
+        }
+      }
+    })
+    const layouts = useAppStore.getState().terminalLayoutsByTabId
+    recordRuntimeTerminalInputForPtyId('rebound-pty', 123)
+    recordRuntimeTerminalInputForPtyId('late-pty', 456)
+
+    const firstLayout = layouts['tab-1']
+    expect(firstLayout).toBeDefined()
+    if (!firstLayout) {
+      return
+    }
+    firstLayout.ptyIdsByLeafId = Object.create({ [LEAF_ID]: 'rebound-pty' })
+    Object.setPrototypeOf(layouts, { 'tab-1': firstLayout })
+    delete layouts['tab-1']
+    layouts['tab-2'] = {
+      root: { type: 'leaf', leafId: nextLeafId },
+      activeLeafId: nextLeafId,
+      expandedLeafId: null,
+      ptyIdsByLeafId: { [nextLeafId]: 'rebound-pty', [LEAF_ID]: 'late-pty' }
+    }
+    recordRuntimeTerminalInputForPtyId('rebound-pty', 1_000)
+    recordRuntimeTerminalInputForPtyId('late-pty', 2_000)
+
+    expect(useAppStore.getState().terminalLayoutsByTabId).toBe(layouts)
+    expect(useAppStore.getState().lastTerminalInputAtByPaneKey).toEqual({
+      [PANE_KEY]: 123,
+      [`tab-2:${nextLeafId}`]: 1_000,
+      [`tab-2:${LEAF_ID}`]: 2_000
+    })
+  })
+
+  it('preserves a malformed first match instead of routing a duplicate PTY', () => {
+    const nextLeafId = '22222222-2222-4222-8222-222222222222'
+    useAppStore.setState({
+      terminalLayoutsByTabId: {
+        'legacy:tab': {
+          root: { type: 'leaf', leafId: LEAF_ID },
+          activeLeafId: LEAF_ID,
+          expandedLeafId: null,
+          ptyIdsByLeafId: { [LEAF_ID]: 'duplicate-pty' }
+        },
+        'tab-2': {
+          root: { type: 'leaf', leafId: nextLeafId },
+          activeLeafId: nextLeafId,
+          expandedLeafId: null,
+          ptyIdsByLeafId: { [nextLeafId]: 'duplicate-pty' }
+        }
+      }
+    })
+
+    recordRuntimeTerminalInputForPtyId('duplicate-pty', 123)
+
+    expect(useAppStore.getState().lastTerminalInputAtByPaneKey).toEqual({})
+  })
+
   it('reports success after fallback fire-and-forget writes when local acceptance cannot be verified', async () => {
     localWriteAccepted.mockResolvedValue(false)
 
diff --git a/src/renderer/src/runtime/runtime-terminal-inspection.ts b/src/renderer/src/runtime/runtime-terminal-inspection.ts
index 29be1aed435..7578c161116 100644
--- a/src/renderer/src/runtime/runtime-terminal-inspection.ts
+++ b/src/renderer/src/runtime/runtime-terminal-inspection.ts
@@ -1,6 +1,6 @@
 import type { GlobalSettings } from '../../../shared/global-settings-types'
 import type { RuntimeTerminalSend } from '../../../shared/runtime-types'
-import { makePaneKey } from '../../../shared/stable-pane-id'
+import { makePaneKey, type PaneKey } from '../../../shared/stable-pane-id'
 import { isTerminalInputTooLargeWithDeferredMeasurement } from '../../../shared/terminal-input'
 import { useAppStore } from '../store'
 import { RuntimeRpcCallError, callRuntimeRpc, getActiveRuntimeTarget } from './runtime-rpc-client'
@@ -18,6 +18,56 @@ export type RuntimeTerminalProcessInspection = {
 
 const REMOTE_PTY_ID_PREFIX = 'remote:'
 const DESKTOP_RUNTIME_CLIENT = { id: 'orca-desktop', type: 'desktop' } as const
+type TerminalLayoutsByTabId = ReturnType<typeof useAppStore.getState>['terminalLayoutsByTabId']
+type TerminalPaneOwner = {
+  tabId: string
+  leafId: string
+  paneKey: PaneKey
+}
+
+const paneOwnersByPtyIdByLayoutIdentity = new WeakMap<
+  TerminalLayoutsByTabId,
+  Map<string, TerminalPaneOwner>
+>()
+
+function resolvePaneKeyForPtyId(layouts: TerminalLayoutsByTabId, ptyId: string): PaneKey | null {
+  let paneOwnersByPtyId = paneOwnersByPtyIdByLayoutIdentity.get(layouts)
+  if (!paneOwnersByPtyId) {
+    paneOwnersByPtyId = new Map<string, TerminalPaneOwner>()
+    paneOwnersByPtyIdByLayoutIdentity.set(layouts, paneOwnersByPtyId)
+  }
+  const cachedOwner = paneOwnersByPtyId.get(ptyId)
+  if (cachedOwner) {
+    const layout = Object.prototype.propertyIsEnumerable.call(layouts, cachedOwner.tabId)
+      ? layouts[cachedOwner.tabId]
+      : undefined
+    const ptyIdsByLeafId = layout?.ptyIdsByLeafId
+    if (
+      ptyIdsByLeafId &&
+      Object.prototype.propertyIsEnumerable.call(ptyIdsByLeafId, cachedOwner.leafId) &&
+      ptyIdsByLeafId[cachedOwner.leafId] === ptyId
+    ) {
+      return cachedOwner.paneKey
+    }
+    paneOwnersByPtyId.delete(ptyId)
+  }
+  for (const [tabId, layout] of Object.entries(layouts)) {
+    for (const [leafId, leafPtyId] of Object.entries(layout?.ptyIdsByLeafId ?? {})) {
+      if (leafPtyId !== ptyId) {
+        continue
+      }
+      try {
+        const paneKey = makePaneKey(tabId, leafId)
+        paneOwnersByPtyId.set(ptyId, { tabId, leafId, paneKey })
+        return paneKey
+      } catch {
+        // Preserve first-match behavior for malformed legacy layout rows.
+        return null
+      }
+    }
+  }
+  return null
+}
 
 function isRuntimePtyInputTooLarge(data: string): boolean | Promise<boolean> {
   return isTerminalInputTooLargeWithDeferredMeasurement(data)
@@ -49,21 +99,17 @@ function isTerminalGoneError(error: unknown): boolean {
 
 export function recordRuntimeTerminalInputForPtyId(ptyId: string, timestamp = Date.now()): void {
   const state = useAppStore.getState()
-  for (const [tabId, layout] of Object.entries(state.terminalLayoutsByTabId)) {
-    for (const [leafId, leafPtyId] of Object.entries(layout?.ptyIdsByLeafId ?? {})) {
-      if (leafPtyId !== ptyId) {
-        continue
-      }
-      try {
-        // Why: paired/runtime sends can bypass xterm.onData, so hibernation
-        // needs the same user-input marker from the PTY-id route.
-        state.recordTerminalInput(makePaneKey(tabId, leafId), timestamp)
-      } catch {
-        // Ignore malformed legacy layout data; the planner will stay
-        // conservative when a live PTY cannot be matched to an eligible pane.
-      }
-      return
-    }
+  const paneKey = resolvePaneKeyForPtyId(state.terminalLayoutsByTabId, ptyId)
+  if (!paneKey) {
+    return
+  }
+  try {
+    // Why: paired/runtime sends can bypass xterm.onData, so hibernation
+    // needs the same user-input marker from the PTY-id route.
+    state.recordTerminalInput(paneKey, timestamp)
+  } catch {
+    // Ignore malformed legacy layout data; the planner will stay
+    // conservative when a live PTY cannot be matched to an eligible pane.
   }
 }
 

From 1fe558dd284477f03dcacbed2128feca49af2d59 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sat, 29 Aug 2026 16:02:29 -0700
Subject: [PATCH 11/31] perf(automations): narrow status observer updates
 (#17249)

---
 ...tomation-agent-status-entry-change.test.ts | 66 ++++++++++++++
 .../automation-agent-status-entry-change.ts   | 15 ++++
 ...automation-dispatch-observer-test-probe.ts | 30 +++++++
 .../hooks/useAutomationDispatchEvents.test.ts |  4 +-
 .../src/hooks/useAutomationDispatchEvents.ts  | 89 +++++++++++--------
 5 files changed, 164 insertions(+), 40 deletions(-)
 create mode 100644 src/renderer/src/hooks/automation-agent-status-entry-change.test.ts
 create mode 100644 src/renderer/src/hooks/automation-agent-status-entry-change.ts
 create mode 100644 src/renderer/src/hooks/automation-dispatch-observer-test-probe.ts

diff --git a/src/renderer/src/hooks/automation-agent-status-entry-change.test.ts b/src/renderer/src/hooks/automation-agent-status-entry-change.test.ts
new file mode 100644
index 00000000000..7079f81af8d
--- /dev/null
+++ b/src/renderer/src/hooks/automation-agent-status-entry-change.test.ts
@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest'
+import type { AgentStatusEntry } from '../../../shared/agent-status-types'
+import {
+  selectAutomationAgentStatusEntryChange,
+  UNCHANGED_AUTOMATION_AGENT_STATUS_ENTRY
+} from './automation-agent-status-entry-change'
+
+function makeEntry(paneKey: string): AgentStatusEntry {
+  return {
+    paneKey,
+    state: 'working',
+    prompt: 'turn',
+    updatedAt: 1,
+    stateStartedAt: 1,
+    stateHistory: []
+  }
+}
+
+describe('selectAutomationAgentStatusEntryChange', () => {
+  it('reads only the target and skips an unchanged entry', () => {
+    const targetPaneKey = 'target-tab:leaf'
+    const targetEntry = makeEntry(targetPaneKey)
+    const entries = Object.fromEntries(
+      Array.from({ length: 499 }, (_, index) => {
+        const paneKey = `other-tab:${index}`
+        return [paneKey, makeEntry(paneKey)]
+      })
+    )
+    entries[targetPaneKey] = targetEntry
+    let enumerations = 0
+    const measuredEntries = new Proxy(entries, {
+      ownKeys: (target) => {
+        enumerations += 1
+        return Reflect.ownKeys(target)
+      }
+    })
+
+    expect(selectAutomationAgentStatusEntryChange(measuredEntries, targetPaneKey, undefined)).toBe(
+      targetEntry
+    )
+    expect(
+      selectAutomationAgentStatusEntryChange(measuredEntries, targetPaneKey, targetEntry)
+    ).toBe(UNCHANGED_AUTOMATION_AGENT_STATUS_ENTRY)
+    expect(enumerations).toBe(0)
+  })
+
+  it('reports removal and ignores inherited or non-enumerable entries', () => {
+    const targetPaneKey = 'target-tab:leaf'
+    const previousEntry = makeEntry(targetPaneKey)
+    const inheritedEntries = Object.create({ [targetPaneKey]: previousEntry }) as Record<
+      string,
+      AgentStatusEntry
+    >
+    const nonEnumerableEntries = Object.defineProperty({}, targetPaneKey, {
+      value: previousEntry
+    }) as Record<string, AgentStatusEntry>
+
+    expect(selectAutomationAgentStatusEntryChange({}, targetPaneKey, previousEntry)).toBeUndefined()
+    expect(selectAutomationAgentStatusEntryChange(inheritedEntries, targetPaneKey, undefined)).toBe(
+      UNCHANGED_AUTOMATION_AGENT_STATUS_ENTRY
+    )
+    expect(
+      selectAutomationAgentStatusEntryChange(nonEnumerableEntries, targetPaneKey, undefined)
+    ).toBe(UNCHANGED_AUTOMATION_AGENT_STATUS_ENTRY)
+  })
+})
diff --git a/src/renderer/src/hooks/automation-agent-status-entry-change.ts b/src/renderer/src/hooks/automation-agent-status-entry-change.ts
new file mode 100644
index 00000000000..1c919e6b417
--- /dev/null
+++ b/src/renderer/src/hooks/automation-agent-status-entry-change.ts
@@ -0,0 +1,15 @@
+import type { AgentStatusEntry } from '../../../shared/agent-status-types'
+
+export const UNCHANGED_AUTOMATION_AGENT_STATUS_ENTRY = Symbol('unchanged-agent-status-entry')
+
+export function selectAutomationAgentStatusEntryChange(
+  entries: Readonly<Record<string, AgentStatusEntry>>,
+  targetPaneKey: string,
+  previousEntry: AgentStatusEntry | undefined
+): AgentStatusEntry | undefined | typeof UNCHANGED_AUTOMATION_AGENT_STATUS_ENTRY {
+  const entry = Object.prototype.propertyIsEnumerable.call(entries, targetPaneKey)
+    ? entries[targetPaneKey]
+    : undefined
+  // Why: status writes replace entries; unchanged identity proves an unrelated publication.
+  return entry === previousEntry ? UNCHANGED_AUTOMATION_AGENT_STATUS_ENTRY : entry
+}
diff --git a/src/renderer/src/hooks/automation-dispatch-observer-test-probe.ts b/src/renderer/src/hooks/automation-dispatch-observer-test-probe.ts
new file mode 100644
index 00000000000..302c052782c
--- /dev/null
+++ b/src/renderer/src/hooks/automation-dispatch-observer-test-probe.ts
@@ -0,0 +1,30 @@
+import type { AgentStatusEntry } from '../../../shared/agent-status-types'
+
+const TARGET_PANE_KEY = 'agent-tab:7c6fb4e5-3bf1-4ff4-8259-03f7ae81c40d'
+
+export function countUnchangedObserverHistoryReads(
+  state: { agentStatusByPaneKey: Record<string, AgentStatusEntry> },
+  subscriber: (() => void) | null
+): number {
+  if (!subscriber) {
+    throw new Error('agent status observer was not registered')
+  }
+  let historyReads = 0
+  state.agentStatusByPaneKey = {
+    [TARGET_PANE_KEY]: {
+      paneKey: TARGET_PANE_KEY,
+      state: 'working',
+      prompt: 'turn',
+      updatedAt: Date.now() + 1,
+      stateStartedAt: Date.now() + 1,
+      get stateHistory() {
+        historyReads += 1
+        return []
+      }
+    }
+  }
+  subscriber()
+  historyReads = 0
+  subscriber()
+  return historyReads
+}
diff --git a/src/renderer/src/hooks/useAutomationDispatchEvents.test.ts b/src/renderer/src/hooks/useAutomationDispatchEvents.test.ts
index 81fc23a5728..b8c1cb49c17 100644
--- a/src/renderer/src/hooks/useAutomationDispatchEvents.test.ts
+++ b/src/renderer/src/hooks/useAutomationDispatchEvents.test.ts
@@ -1,6 +1,7 @@
 import type * as ReactModule from 'react'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { AUTOMATIONS_CHANGED_EVENT } from '@/lib/automations-changed-window-event'
+import { countUnchangedObserverHistoryReads } from './automation-dispatch-observer-test-probe'
 
 const mockDispatchEvent = vi.fn()
 
@@ -620,10 +621,11 @@ describe('useAutomationDispatchEvents setup launch', () => {
     await vi.waitFor(() => expect(mockFinalizeTerminalOwnership).toHaveBeenCalledOnce())
   })
 
-  it('persists assistant output from a batched working→done→working transition', async () => {
+  it('skips unchanged status and persists batched working→done→working output', async () => {
     const paneKey = 'agent-tab:7c6fb4e5-3bf1-4ff4-8259-03f7ae81c40d'
 
     await registerAndDispatch()
+    expect(countUnchangedObserverHistoryReads(state, latestStoreSubscriber)).toBe(0)
     const transitionStartedAt = Date.now() + 1
     state.agentStatusByPaneKey = {
       [paneKey]: {
diff --git a/src/renderer/src/hooks/useAutomationDispatchEvents.ts b/src/renderer/src/hooks/useAutomationDispatchEvents.ts
index 1e46b315f28..e06eefa6e61 100644
--- a/src/renderer/src/hooks/useAutomationDispatchEvents.ts
+++ b/src/renderer/src/hooks/useAutomationDispatchEvents.ts
@@ -32,8 +32,12 @@ import {
   toSshExecutionHostId
 } from '../../../shared/execution-host'
 import { parseWorkspaceKey } from '../../../shared/workspace-scope'
-import type { AgentStateHistoryEntry } from '../../../shared/agent-status-types'
+import type { AgentStateHistoryEntry, AgentStatusEntry } from '../../../shared/agent-status-types'
 import { resolveFolderWorkspaceHost } from '../../../shared/folder-workspace-execution-host'
+import {
+  selectAutomationAgentStatusEntryChange,
+  UNCHANGED_AUTOMATION_AGENT_STATUS_ENTRY
+} from './automation-agent-status-entry-change'
 
 const activeReuseDispatchTabIds = new Set<string>()
 
@@ -450,57 +454,64 @@ export function useAutomationDispatchEvents(): void {
           ): void => {
             let sawWorkingAfterStart = false
             let observedStateHistory: AgentStateHistoryEntry[] = []
+            let observedEntry: AgentStatusEntry | undefined
             const checkCurrentStatus = (): void => {
-              const { agentStatusByPaneKey } = useAppStore.getState()
-              for (const [paneKey, entry] of Object.entries(agentStatusByPaneKey)) {
-                if (paneKey !== targetPaneKey || entry.updatedAt < startedAfter) {
+              const entryChange = selectAutomationAgentStatusEntryChange(
+                useAppStore.getState().agentStatusByPaneKey,
+                targetPaneKey,
+                observedEntry
+              )
+              if (entryChange === UNCHANGED_AUTOMATION_AGENT_STATUS_ENTRY) {
+                return
+              }
+              const entry = entryChange
+              observedEntry = entry
+              if (!entry || entry.updatedAt < startedAfter) {
+                return
+              }
+              const historyOverlap = getAgentStateHistoryOverlap(
+                observedStateHistory,
+                entry.stateHistory
+              )
+              // Why: sawWorkingAfterStart stays monotonic — a recreated entry
+              // (transport loss, PTY exit, cap eviction) arrives with an empty
+              // stateHistory, so clearing it here would strand reuseSession runs
+              // with nothing left to re-derive the working edge from.
+              for (const historicalState of entry.stateHistory.slice(historyOverlap)) {
+                if (historicalState.startedAt < startedAfter) {
                   continue
                 }
-                const historyOverlap = getAgentStateHistoryOverlap(
-                  observedStateHistory,
-                  entry.stateHistory
-                )
-                // Why: sawWorkingAfterStart stays monotonic — a recreated entry
-                // (transport loss, PTY exit, cap eviction) arrives with an empty
-                // stateHistory, so clearing it here would strand reuseSession runs
-                // with nothing left to re-derive the working edge from.
-                for (const historicalState of entry.stateHistory.slice(historyOverlap)) {
-                  if (historicalState.startedAt < startedAfter) {
-                    continue
-                  }
-                  if (historicalState.state === 'working') {
-                    sawWorkingAfterStart = true
-                  }
-                  if (
-                    historicalState.state === 'done' &&
-                    (!options?.requireWorkingAfterStart || sawWorkingAfterStart)
-                  ) {
-                    // Why: this `done` already rolled out of the live entry, so its output
-                    // survives only in the entry-level completed slot.
-                    latestAssistantMessage =
-                      entry.lastCompletedAssistantMessage?.trim() || latestAssistantMessage
-                    handleAgentDone()
-                    return
-                  }
-                }
-                observedStateHistory = [...entry.stateHistory]
-                if (entry.state === 'working') {
+                if (historicalState.state === 'working') {
                   sawWorkingAfterStart = true
                 }
                 if (
-                  entry.state === 'done' &&
-                  // Why: a session-boundary done is the agent CONNECTING (Claude SessionStart
-                  // fires at launch, before the argv prompt submits) — completing here would
-                  // close the tab and record an empty run result.
-                  entry.sessionBoundary !== true &&
+                  historicalState.state === 'done' &&
                   (!options?.requireWorkingAfterStart || sawWorkingAfterStart)
                 ) {
+                  // Why: this `done` already rolled out of the live entry, so its output
+                  // survives only in the entry-level completed slot.
                   latestAssistantMessage =
-                    entry.lastAssistantMessage?.trim() || latestAssistantMessage
+                    entry.lastCompletedAssistantMessage?.trim() || latestAssistantMessage
                   handleAgentDone()
                   return
                 }
               }
+              observedStateHistory = [...entry.stateHistory]
+              if (entry.state === 'working') {
+                sawWorkingAfterStart = true
+              }
+              if (
+                entry.state === 'done' &&
+                // Why: a session-boundary done is the agent CONNECTING (Claude SessionStart
+                // fires at launch, before the argv prompt submits) — completing here would
+                // close the tab and record an empty run result.
+                entry.sessionBoundary !== true &&
+                (!options?.requireWorkingAfterStart || sawWorkingAfterStart)
+              ) {
+                latestAssistantMessage =
+                  entry.lastAssistantMessage?.trim() || latestAssistantMessage
+                handleAgentDone()
+              }
             }
             // Why: Codex/Claude completion normally arrives through the global
             // hook IPC listener, not the hidden PTY OSC fallback.

From 9c777ca89e175169fad79ef34bccfdbb36613822 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sat, 29 Aug 2026 16:03:35 -0700
Subject: [PATCH 12/31] perf(renderer): gate pending agent-status retries
 (#17254)

---
 .../ipc-events/agent-status-ipc-bridge.ts     |  11 +-
 .../agent-status-pending-retry-gate.test.ts   | 191 ++++++++++++++++++
 .../agent-status-pending-retry-gate.ts        |  29 +++
 ...Events-agent-status-queue-ordering.test.ts |  27 ++-
 ...vents-agent-status-snapshot-replay.test.ts |   6 +-
 5 files changed, 249 insertions(+), 15 deletions(-)
 create mode 100644 src/renderer/src/hooks/ipc-events/agent-status-pending-retry-gate.test.ts
 create mode 100644 src/renderer/src/hooks/ipc-events/agent-status-pending-retry-gate.ts

diff --git a/src/renderer/src/hooks/ipc-events/agent-status-ipc-bridge.ts b/src/renderer/src/hooks/ipc-events/agent-status-ipc-bridge.ts
index 3a99527b1d3..26058a3e9e0 100644
--- a/src/renderer/src/hooks/ipc-events/agent-status-ipc-bridge.ts
+++ b/src/renderer/src/hooks/ipc-events/agent-status-ipc-bridge.ts
@@ -13,6 +13,7 @@ import type {
   AgentStatusBatchEvent,
   PendingAgentStatusEvent
 } from './agent-status-bridge-types'
+import { shouldRetryPendingAgentStatusesAfterStoreUpdate } from './agent-status-pending-retry-gate'
 
 const PENDING_AGENT_STATUS_RETRY_MS = 100
 const PENDING_AGENT_STATUS_TTL_MS = 15_000
@@ -94,8 +95,8 @@ export function registerAgentStatusIpcBridge(unsubs: (() => void)[]): AgentStatu
       }
     } finally {
       isFlushingAgentStatuses = false
+      schedulePendingAgentStatusFlush()
     }
-    schedulePendingAgentStatusFlush()
   }
 
   const applyAgentStatus = createAgentStatusEventApplicator({
@@ -261,7 +262,13 @@ export function registerAgentStatusIpcBridge(unsubs: (() => void)[]): AgentStatu
   requestAgentStatusSnapshotIfReady()
   const unsubscribeAgentStatusStore = useAppStore.subscribe((state, previousState) => {
     requestAgentStatusSnapshotIfReady()
-    flushPendingAgentStatuses()
+    // Why: the timer covers module-owned rekeys; unrelated store writes cannot change attribution and must not rebuild its routing index.
+    if (
+      pendingAgentStatusEvents.length > 0 &&
+      shouldRetryPendingAgentStatusesAfterStoreUpdate(state, previousState)
+    ) {
+      flushPendingAgentStatuses()
+    }
     syncAgentHookCompletionNotificationsForStoreUpdate(state, previousState)
   })
 
diff --git a/src/renderer/src/hooks/ipc-events/agent-status-pending-retry-gate.test.ts b/src/renderer/src/hooks/ipc-events/agent-status-pending-retry-gate.test.ts
new file mode 100644
index 00000000000..51e8161a8fc
--- /dev/null
+++ b/src/renderer/src/hooks/ipc-events/agent-status-pending-retry-gate.test.ts
@@ -0,0 +1,191 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { AgentStatusBatchUpdate } from '../../store/slices/agent-status'
+import {
+  buildStoreState,
+  FUTURE_LEAF_ID,
+  FUTURE_PANE_KEY,
+  type AgentStatusSetData,
+  type StoreLike,
+  type StoreSubscribeListener
+} from '../ipc-events-agent-status-store-test-fixtures'
+import { shouldRetryPendingAgentStatusesAfterStoreUpdate } from './agent-status-pending-retry-gate'
+
+type RetryState = Parameters<typeof shouldRetryPendingAgentStatusesAfterStoreUpdate>[0]
+
+function createRetryState(): RetryState {
+  return {
+    workspaceSessionReady: true,
+    tabsByWorktree: {},
+    unifiedTabsByWorktree: {},
+    terminalLayoutsByTabId: {},
+    worktreesByRepo: {},
+    repos: [],
+    recentlyClosedAgentStatusTabIds: {},
+    recentlyRetiredAgentStatusPaneKeys: {}
+  }
+}
+
+type PendingRetryHarness = {
+  bridge: { disposeAsyncState: () => void; unsubscribeStore: () => void }
+  emitPendingStatus: () => void
+  publish: (mutate: (state: StoreLike) => void) => void
+  setAgentStatuses: ReturnType<typeof vi.fn>
+  transactAgentStatuses: ReturnType<typeof vi.fn>
+}
+
+async function createPendingRetryHarness(): Promise<PendingRetryHarness> {
+  const subscribeListenerRef: { current: StoreSubscribeListener | null } = { current: null }
+  const onSetListenerRef: { current: ((data: AgentStatusSetData) => void) | null } = {
+    current: null
+  }
+  const setAgentStatuses = vi.fn((updates: readonly AgentStatusBatchUpdate[]) =>
+    updates.map(() => true)
+  )
+  const storeState = buildStoreState({
+    setAgentStatuses,
+    workspaceSessionReady: true,
+    tabsByWorktree: {},
+    terminalLayoutsByTabId: {},
+    settings: { terminalFontSize: 13, notifications: { enabled: false } }
+  })
+  const transactImplementation = storeState.transactAgentStatuses as (...args: unknown[]) => unknown
+  const transactAgentStatuses = vi.fn(transactImplementation)
+  storeState.transactAgentStatuses = transactAgentStatuses
+
+  vi.doMock('../../store', () => ({
+    useAppStore: {
+      subscribe: vi.fn((listener: StoreSubscribeListener) => {
+        subscribeListenerRef.current = listener
+        return () => {
+          subscribeListenerRef.current = null
+        }
+      }),
+      getState: () => storeState
+    }
+  }))
+  vi.doMock('../agent-hook-completion-notifications', () => ({
+    observeAgentHookCompletionForNotification: vi.fn(),
+    syncAgentHookCompletionNotificationsForStoreUpdate: vi.fn()
+  }))
+  vi.stubGlobal('window', {
+    api: {
+      agentStatus: {
+        onSet: (listener: (data: AgentStatusSetData) => void) => {
+          onSetListenerRef.current = listener
+          return () => {
+            onSetListenerRef.current = null
+          }
+        }
+      }
+    }
+  })
+
+  const { registerAgentStatusIpcBridge } = await import('./agent-status-ipc-bridge')
+  const bridge = registerAgentStatusIpcBridge([])
+  if (!subscribeListenerRef.current || !onSetListenerRef.current) {
+    throw new Error('Expected agent-status bridge listeners')
+  }
+
+  return {
+    bridge,
+    emitPendingStatus: () => {
+      onSetListenerRef.current?.({
+        paneKey: FUTURE_PANE_KEY,
+        state: 'working',
+        prompt: 'pending attribution',
+        agentType: 'claude',
+        receivedAt: 1_700_000_000_000,
+        stateStartedAt: 1_700_000_000_000
+      })
+    },
+    publish: (mutate) => {
+      const previousState = { ...storeState }
+      mutate(storeState)
+      subscribeListenerRef.current?.(storeState, previousState)
+    },
+    setAgentStatuses,
+    transactAgentStatuses
+  }
+}
+
+describe('agent status pending retry gate', () => {
+  beforeEach(() => {
+    vi.resetModules()
+    vi.useFakeTimers()
+    vi.setSystemTime(1_700_000_100_000)
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+    vi.unstubAllGlobals()
+  })
+
+  it('tracks every store-owned input that can resolve or retire pending attribution', () => {
+    const previous = createRetryState()
+    const changes: RetryState[] = [
+      { ...previous, workspaceSessionReady: false },
+      { ...previous, tabsByWorktree: {} },
+      { ...previous, unifiedTabsByWorktree: {} },
+      { ...previous, terminalLayoutsByTabId: {} },
+      { ...previous, worktreesByRepo: {} },
+      { ...previous, repos: [] },
+      { ...previous, recentlyClosedAgentStatusTabIds: {} },
+      { ...previous, recentlyRetiredAgentStatusPaneKeys: {} }
+    ]
+
+    expect(shouldRetryPendingAgentStatusesAfterStoreUpdate({ ...previous }, previous)).toBe(false)
+    for (const current of changes) {
+      expect(shouldRetryPendingAgentStatusesAfterStoreUpdate(current, previous)).toBe(true)
+    }
+  })
+
+  it('skips retry transactions for unrelated publications and retries on hydration', async () => {
+    const harness = await createPendingRetryHarness()
+    harness.emitPendingStatus()
+
+    for (let updateIndex = 0; updateIndex < 2_400; updateIndex += 1) {
+      harness.publish((state) => {
+        state.cosmeticUpdateIndex = updateIndex
+      })
+    }
+
+    expect(harness.transactAgentStatuses).not.toHaveBeenCalled()
+
+    harness.publish((state) => {
+      state.tabsByWorktree = {
+        'wt-1': [{ id: 'tab-future', ptyId: 'pty-1', worktreeId: 'wt-1', title: 'Future' }]
+      }
+      state.terminalLayoutsByTabId = {
+        'tab-future': {
+          root: { type: 'leaf', leafId: FUTURE_LEAF_ID },
+          activeLeafId: FUTURE_LEAF_ID,
+          expandedLeafId: null
+        }
+      }
+    })
+
+    expect(harness.transactAgentStatuses).toHaveBeenCalledTimes(1)
+    expect(harness.setAgentStatuses).toHaveBeenCalledWith([
+      expect.objectContaining({ paneKey: FUTURE_PANE_KEY })
+    ])
+    vi.advanceTimersByTime(100)
+    expect(harness.transactAgentStatuses).toHaveBeenCalledTimes(1)
+    harness.bridge.unsubscribeStore()
+    harness.bridge.disposeAsyncState()
+  })
+
+  it('keeps the timer fallback when routing references stay unchanged', async () => {
+    const harness = await createPendingRetryHarness()
+    harness.emitPendingStatus()
+    harness.publish((state) => {
+      state.cosmeticUpdateIndex = 1
+    })
+
+    expect(harness.transactAgentStatuses).not.toHaveBeenCalled()
+    vi.advanceTimersByTime(100)
+    expect(harness.transactAgentStatuses).toHaveBeenCalledTimes(1)
+    expect(harness.setAgentStatuses).toHaveBeenCalledWith([])
+    harness.bridge.unsubscribeStore()
+    harness.bridge.disposeAsyncState()
+  })
+})
diff --git a/src/renderer/src/hooks/ipc-events/agent-status-pending-retry-gate.ts b/src/renderer/src/hooks/ipc-events/agent-status-pending-retry-gate.ts
new file mode 100644
index 00000000000..4b8dcc36a9e
--- /dev/null
+++ b/src/renderer/src/hooks/ipc-events/agent-status-pending-retry-gate.ts
@@ -0,0 +1,29 @@
+import type { AppState } from '../../store/types'
+
+type AgentStatusPendingRetryState = Pick<
+  AppState,
+  | 'workspaceSessionReady'
+  | 'tabsByWorktree'
+  | 'unifiedTabsByWorktree'
+  | 'terminalLayoutsByTabId'
+  | 'worktreesByRepo'
+  | 'repos'
+  | 'recentlyClosedAgentStatusTabIds'
+  | 'recentlyRetiredAgentStatusPaneKeys'
+>
+
+export function shouldRetryPendingAgentStatusesAfterStoreUpdate(
+  current: AgentStatusPendingRetryState,
+  previous: AgentStatusPendingRetryState
+): boolean {
+  return (
+    current.workspaceSessionReady !== previous.workspaceSessionReady ||
+    current.tabsByWorktree !== previous.tabsByWorktree ||
+    current.unifiedTabsByWorktree !== previous.unifiedTabsByWorktree ||
+    current.terminalLayoutsByTabId !== previous.terminalLayoutsByTabId ||
+    current.worktreesByRepo !== previous.worktreesByRepo ||
+    current.repos !== previous.repos ||
+    current.recentlyClosedAgentStatusTabIds !== previous.recentlyClosedAgentStatusTabIds ||
+    current.recentlyRetiredAgentStatusPaneKeys !== previous.recentlyRetiredAgentStatusPaneKeys
+  )
+}
diff --git a/src/renderer/src/hooks/useIpcEvents-agent-status-queue-ordering.test.ts b/src/renderer/src/hooks/useIpcEvents-agent-status-queue-ordering.test.ts
index 322e253e541..eb613f21e70 100644
--- a/src/renderer/src/hooks/useIpcEvents-agent-status-queue-ordering.test.ts
+++ b/src/renderer/src/hooks/useIpcEvents-agent-status-queue-ordering.test.ts
@@ -1,4 +1,4 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import type { AgentStatusUpdate } from '../store/slices/agent-status'
 import { YOLO_TUI_AGENT_ARGS } from '../../../shared/tui-agent-permissions'
 import {
@@ -22,6 +22,10 @@ describe('useIpcEvents agent status snapshot integration', () => {
     vi.unstubAllGlobals()
   })
 
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
   it('preserves queued set-clear order for working removal and done retention', async () => {
     vi.useFakeTimers()
     let storeState: StoreLike
@@ -163,7 +167,7 @@ describe('useIpcEvents agent status snapshot integration', () => {
 
   it('does not recurse when flushing a pending status re-enters via the store subscriber', async () => {
     // Repro for crash 9fc89529 (RangeError: Maximum call stack size exceeded):
-    // the store subscriber calls flushPendingAgentStatuses() on every update.
+    // the store subscriber retries pending statuses synchronously on hydration.
     // flush -> applyAgentStatus -> store.setAgentStatus notifies subscribers
     // synchronously (like Zustand) -> subscriber -> flush again while the same
     // event is still queued -> infinite recursion. Model setAgentStatus with a
@@ -173,10 +177,10 @@ describe('useIpcEvents agent status snapshot integration', () => {
       current: null
     }
     let setAgentStatusCalls = 0
-    const notify = (): void => {
+    const notify = (previousState: StoreLike = storeState): void => {
       const listener = subscribeListenerRef.current
       if (listener) {
-        listener(storeState, storeState)
+        listener(storeState, previousState)
       }
     }
     const storeState: StoreLike = buildStoreState({
@@ -243,6 +247,7 @@ describe('useIpcEvents agent status snapshot integration', () => {
 
     // Tab hydrates; the next store update flushes the pending event. Without the
     // re-entrancy guard this overflows the stack instead of applying once.
+    const beforeHydration = { ...storeState }
     storeState.tabsByWorktree = {
       'wt-1': [{ id: 'tab-future', ptyId: 'pty-1', worktreeId: 'wt-1', title: 'Future Tab' }]
     }
@@ -254,7 +259,7 @@ describe('useIpcEvents agent status snapshot integration', () => {
       }
     }
 
-    expect(() => notify()).not.toThrow()
+    expect(() => notify(beforeHydration)).not.toThrow()
     // Applied exactly once — the re-entrant flush is a no-op, not a loop.
     expect(setAgentStatusCalls).toBe(1)
   })
@@ -263,6 +268,7 @@ describe('useIpcEvents agent status snapshot integration', () => {
   // buffered event permanently. Before batching the queue was only replaced after the loop,
   // so a throw left it intact — keep that.
   it('keeps pending statuses queued when the retry fold throws', async () => {
+    vi.useFakeTimers()
     const subscribeListenerRef: { current: StoreSubscribeListener | null } = { current: null }
     const onSetListenerRef: { current: ((data: AgentStatusSetData) => void) | null } = {
       current: null
@@ -284,8 +290,6 @@ describe('useIpcEvents agent status snapshot integration', () => {
       tabsByWorktree: {},
       terminalLayoutsByTabId: {}
     })
-    const notify = (): void => subscribeListenerRef.current?.(storeState, storeState)
-
     stubReactSyncEffect()
     vi.doMock('../store', () => ({
       useAppStore: {
@@ -325,7 +329,10 @@ describe('useIpcEvents agent status snapshot integration', () => {
       stateStartedAt: 1_700_000_000_100
     })
 
-    // Tab hydrates, so the next store update flushes the pending event — and throws.
+    // The timer-owned retry throws after clearing its handle.
+    expect(() => vi.advanceTimersByTime(100)).toThrow('fold blew up')
+
+    // Hydrate without publishing so only the re-armed timer can recover the event.
     storeState.tabsByWorktree = {
       'wt-1': [{ id: 'tab-future', ptyId: 'pty-1', worktreeId: 'wt-1', title: 'Future Tab' }]
     }
@@ -336,10 +343,8 @@ describe('useIpcEvents agent status snapshot integration', () => {
         expandedLeafId: null
       }
     }
-    expect(() => notify()).toThrow('fold blew up')
 
-    // The event must still be queued, so the next flush replays it.
-    notify()
+    vi.advanceTimersByTime(100)
     const replayedAfterThrow = setAgentStatuses.mock.calls
       .slice(1)
       .flatMap((call) => call[0].map((update) => update.payload.prompt))
diff --git a/src/renderer/src/hooks/useIpcEvents-agent-status-snapshot-replay.test.ts b/src/renderer/src/hooks/useIpcEvents-agent-status-snapshot-replay.test.ts
index cbb4992e7f2..e26448f0b63 100644
--- a/src/renderer/src/hooks/useIpcEvents-agent-status-snapshot-replay.test.ts
+++ b/src/renderer/src/hooks/useIpcEvents-agent-status-snapshot-replay.test.ts
@@ -87,6 +87,7 @@ describe('useIpcEvents agent status snapshot integration', () => {
 
     expect(setAgentStatus).not.toHaveBeenCalled()
 
+    const beforeHydration = { ...storeState }
     Object.assign(storeState, {
       tabsByWorktree: {
         'wt-1': [{ id: 'tab-future', ptyId: 'pty-1', worktreeId: 'wt-1', title: 'SSH Tab' }]
@@ -99,7 +100,7 @@ describe('useIpcEvents agent status snapshot integration', () => {
         }
       }
     })
-    subscribeListenerRef.current?.(storeState, storeState)
+    subscribeListenerRef.current?.(storeState, beforeHydration)
 
     expect(setAgentStatus).toHaveBeenCalledTimes(1)
     expect(setAgentStatus).toHaveBeenCalledWith(
@@ -192,6 +193,7 @@ describe('useIpcEvents agent status snapshot integration', () => {
 
     expect(setAgentStatus).not.toHaveBeenCalled()
 
+    const beforeHydration = { ...storeState }
     Object.assign(storeState, {
       tabsByWorktree: {
         'wt-1': [{ id: 'tab-future', ptyId: 'pty-1', worktreeId: 'wt-1', title: 'SSH Tab' }]
@@ -204,7 +206,7 @@ describe('useIpcEvents agent status snapshot integration', () => {
         }
       }
     })
-    subscribeListenerRef.current?.(storeState, storeState)
+    subscribeListenerRef.current?.(storeState, beforeHydration)
 
     expect(setAgentStatus).toHaveBeenCalledWith(
       FUTURE_PANE_KEY,

From 7ae916cebd7b14f9d1e55f3866c042102e51583b Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sat, 29 Aug 2026 16:06:15 -0700
Subject: [PATCH 13/31] perf(worktrees): batch-prune stale local metadata
 (#17278)

---
 .../ipc/registered-worktree-roots-cache.ts    |  16 +
 ...thoritative-local-metadata-pruning.test.ts | 611 ++++++++++++++++++
 src/main/ipc/worktrees-test-harness.ts        |   9 +-
 src/main/ipc/worktrees-test-ipc-surface.ts    |   4 +
 .../worktrees-test-metadata-pruning-store.ts  |  35 +
 src/main/ipc/worktrees-windows.test.ts        |  16 +
 ...itative-local-worktree-metadata-pruning.ts | 141 ++++
 .../listing/detected-provider-listing.ts      |  23 +-
 .../listing/detected-worktree-scan-cache.ts   | 118 +++-
 .../register-worktree-catalog-handlers.ts     |  29 +-
 src/main/local-worktree-path-presence.test.ts | 219 +++++++
 src/main/local-worktree-path-presence.ts      |  72 +++
 src/main/local-worktree-scan-generation.ts    |  25 +
 src/main/persistence-initial-load.test.ts     |  11 +-
 src/main/persistence-repo-lifecycle.test.ts   |  39 ++
 src/main/persistence-settings-update.test.ts  |  19 +
 src/main/persistence-update-repo.test.ts      |  23 +
 .../applying-settings/settings-update.ts      |  11 +
 .../metadata-lineage-batch-pruning.test.ts    |  64 ++
 .../metadata-lineage-operations.ts            |  31 +
 .../loading-store/profile-preferences.ts      |   2 +
 .../project-collection-operations.ts          |   2 +
 .../repo-lifecycle-operations.ts              |  15 +
 .../worktree-identity-metadata.ts             |  13 +-
 .../session-worktree-ownership.test.ts        | 166 +++++
 .../session-worktree-ownership.ts             | 246 +++++++
 ...ktree-metadata-batch-pruning.bench.test.ts | 106 +++
 ...worktree-metadata-scan-expectation.test.ts | 242 +++++++
 ...ocal-worktree-metadata-scan-expectation.ts | 243 +++++++
 ...ng-local-worktree-metadata-pruning.test.ts | 477 ++++++++++++++
 ...missing-local-worktree-metadata-pruning.ts | 153 +++++
 .../tracking-repos/project-host-operations.ts |   4 +
 .../tracking-repos/repo-update-operations.ts  |   6 +
 src/main/worktree-lineage-pruning.test.ts     | 137 +++-
 src/main/worktree-lineage-pruning.ts          |  35 +-
 .../worktree-retention-path-comparison.ts     |  24 +
 src/shared/priority-semaphore.test.ts         |  15 +
 src/shared/priority-semaphore.ts              |  26 +-
 38 files changed, 3382 insertions(+), 46 deletions(-)
 create mode 100644 src/main/ipc/worktrees-authoritative-local-metadata-pruning.test.ts
 create mode 100644 src/main/ipc/worktrees-test-metadata-pruning-store.ts
 create mode 100644 src/main/ipc/worktrees/listing/authoritative-local-worktree-metadata-pruning.ts
 create mode 100644 src/main/local-worktree-path-presence.test.ts
 create mode 100644 src/main/local-worktree-path-presence.ts
 create mode 100644 src/main/local-worktree-scan-generation.ts
 create mode 100644 src/main/persistence/loading-store/metadata-lineage-batch-pruning.test.ts
 create mode 100644 src/main/persistence/restoring-sessions/session-worktree-ownership.test.ts
 create mode 100644 src/main/persistence/restoring-sessions/session-worktree-ownership.ts
 create mode 100644 src/main/persistence/tracking-repos/local-worktree-metadata-batch-pruning.bench.test.ts
 create mode 100644 src/main/persistence/tracking-repos/local-worktree-metadata-scan-expectation.test.ts
 create mode 100644 src/main/persistence/tracking-repos/local-worktree-metadata-scan-expectation.ts
 create mode 100644 src/main/persistence/tracking-repos/missing-local-worktree-metadata-pruning.test.ts
 create mode 100644 src/main/persistence/tracking-repos/missing-local-worktree-metadata-pruning.ts
 create mode 100644 src/main/worktree-retention-path-comparison.ts

diff --git a/src/main/ipc/registered-worktree-roots-cache.ts b/src/main/ipc/registered-worktree-roots-cache.ts
index 8ca19984298..92ae4fc334f 100644
--- a/src/main/ipc/registered-worktree-roots-cache.ts
+++ b/src/main/ipc/registered-worktree-roots-cache.ts
@@ -7,6 +7,9 @@ import { isDescendantOrEqual, normalizeExistingPath } from './filesystem-path-co
 const registeredWorktreeRoots = new Set<string>()
 const registeredWorktreeRootsByRepo = new Map<string, Set<string>>()
 const registeredWorktreeRootRepoIds = new Set<string>()
+const registeredWorktreeRootsRevisionByRepo = new Map<string, number>()
+let registeredWorktreeRootsRevisionSequence = 0
+let registeredWorktreeRootsBaseRevision = 0
 let registeredWorktreeRootsDirty = true
 let registeredWorktreeRootsRefresh: Promise<void> | null = null
 const AUTHORIZED_ROOTS_REBUILD_CONCURRENCY = 8
@@ -17,6 +20,8 @@ export function invalidateAuthorizedRootsCache(): void {
   registeredWorktreeRoots.clear()
   registeredWorktreeRootsByRepo.clear()
   registeredWorktreeRootRepoIds.clear()
+  registeredWorktreeRootsBaseRevision = ++registeredWorktreeRootsRevisionSequence
+  registeredWorktreeRootsRevisionByRepo.clear()
 }
 
 export async function rebuildAuthorizedRootsCache(store: Store): Promise<void> {
@@ -55,6 +60,8 @@ export async function rebuildAuthorizedRootsCache(store: Store): Promise<void> {
     registeredWorktreeRootRepoIds.add(repoId)
   }
   registeredWorktreeRootsDirty = false
+  registeredWorktreeRootsBaseRevision = ++registeredWorktreeRootsRevisionSequence
+  registeredWorktreeRootsRevisionByRepo.clear()
 }
 
 async function mapWithConcurrency<T, R>(
@@ -87,6 +94,10 @@ export function registerWorktreeRootsForRepo(
     if (!localRepoIds.has(registeredRepoId)) {
       registeredWorktreeRootsByRepo.delete(registeredRepoId)
       registeredWorktreeRootRepoIds.delete(registeredRepoId)
+      registeredWorktreeRootsRevisionByRepo.set(
+        registeredRepoId,
+        ++registeredWorktreeRootsRevisionSequence
+      )
     }
   }
 
@@ -98,10 +109,15 @@ export function registerWorktreeRootsForRepo(
 
   registeredWorktreeRootsByRepo.set(repoId, new Set(worktreeRoots.map((root) => resolve(root))))
   registeredWorktreeRootRepoIds.add(repoId)
+  registeredWorktreeRootsRevisionByRepo.set(repoId, ++registeredWorktreeRootsRevisionSequence)
   refreshRegisteredWorktreeRoots()
   registeredWorktreeRootsDirty = !allLocalRepoRootsRegistered(localRepoIds)
 }
 
+export function getRegisteredWorktreeRootsRevision(repoId: string): number {
+  return registeredWorktreeRootsRevisionByRepo.get(repoId) ?? registeredWorktreeRootsBaseRevision
+}
+
 export async function ensureAuthorizedRootsCache(store: Store): Promise<void> {
   if (!registeredWorktreeRootsDirty) {
     return
diff --git a/src/main/ipc/worktrees-authoritative-local-metadata-pruning.test.ts b/src/main/ipc/worktrees-authoritative-local-metadata-pruning.test.ts
new file mode 100644
index 00000000000..aa3fff56f77
--- /dev/null
+++ b/src/main/ipc/worktrees-authoritative-local-metadata-pruning.test.ts
@@ -0,0 +1,611 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { GitWorktreeInfo } from '../../shared/worktree/types'
+import type { NativeLocalWorktreeMetadataScanExpectation } from '../persistence/tracking-repos/missing-local-worktree-metadata-pruning'
+import { notifyWorktreesChanged } from './worktree-remote'
+import {
+  listWorktreesMock,
+  pruneCleanupScanSnapshotsMock,
+  pruneSpaceAnalysisSnapshotsMock
+} from './worktrees-test-module-mocks'
+import { handlers, mainWindow, setupWorktreeHandlers, store } from './worktrees-test-harness'
+import { mockSelectedWslProjectRuntime } from './worktrees-test-fixtures'
+import { pruneMetadataMissingFromAuthoritativeLocalScan } from './worktrees/listing/authoritative-local-worktree-metadata-pruning'
+import { listDetectedWorktreesForCapturedRepo } from './worktrees/listing/detected-provider-listing'
+import { getLocalWorktreeScanGeneration } from '../local-worktree-scan-generation'
+import {
+  isRegisteredWorktreePath,
+  registerWorktreeRootsForRepo
+} from './registered-worktree-roots-cache'
+
+const localWorktreePathPresenceMock = vi.hoisted(() => vi.fn())
+
+vi.mock('electron', async () =>
+  (await import('./worktrees-test-module-mocks')).electronModuleMock()
+)
+vi.mock('../git/worktree', async () =>
+  (await import('./worktrees-test-module-mocks')).gitWorktreeModuleMock()
+)
+vi.mock('../git/runner', async () =>
+  (await import('./worktrees-test-module-mocks')).gitRunnerModuleMock()
+)
+vi.mock('../git/repo', async () =>
+  (await import('./worktrees-test-module-mocks')).gitRepoModuleMock()
+)
+vi.mock('../git/git-username', async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  resolveLocalGitUsername: (await import('./worktrees-test-module-mocks'))
+    .resolveLocalGitUsernameMock
+}))
+vi.mock('../github/client', async () =>
+  (await import('./worktrees-test-module-mocks')).githubClientModuleMock()
+)
+vi.mock('../source-control/hosted-review', async () =>
+  (await import('./worktrees-test-module-mocks')).hostedReviewModuleMock()
+)
+vi.mock('../providers/ssh-git-dispatch', async () =>
+  (await import('./worktrees-test-module-mocks')).sshGitDispatchModuleMock()
+)
+vi.mock('../providers/ssh-filesystem-dispatch', async () =>
+  (await import('./worktrees-test-module-mocks')).sshFilesystemDispatchModuleMock()
+)
+vi.mock('./worktree-symlinks', async () =>
+  (await import('./worktrees-test-module-mocks')).worktreeSymlinksModuleMock()
+)
+vi.mock('./ssh', async () => (await import('./worktrees-test-module-mocks')).sshModuleMock())
+vi.mock('../ssh/ssh-target-registry', async () =>
+  (await import('./worktrees-test-module-mocks')).sshTargetRegistryModuleMock()
+)
+vi.mock('../hooks', async () => (await import('./worktrees-test-module-mocks')).hooksModuleMock())
+vi.mock('../setup-runner-script-text', async (importOriginal) =>
+  (await import('./worktrees-test-module-mocks')).setupRunnerScriptTextModuleMock(
+    (await importOriginal()) as Record<string, unknown>
+  )
+)
+vi.mock('../worktree-runner-script', async (importOriginal) =>
+  (await import('./worktrees-test-module-mocks')).worktreeRunnerScriptModuleMock(
+    (await importOriginal()) as Record<string, unknown>
+  )
+)
+vi.mock('../effective-hook-config', async (importOriginal) =>
+  (await import('./worktrees-test-module-mocks')).effectiveHookConfigModuleMock(
+    (await importOriginal()) as Record<string, unknown>
+  )
+)
+vi.mock('../setup-hook-env-vars', async (importOriginal) =>
+  (await import('./worktrees-test-module-mocks')).setupHookEnvVarsModuleMock(
+    (await importOriginal()) as Record<string, unknown>
+  )
+)
+vi.mock('./worktree-logic', async (importOriginal) =>
+  (await import('./worktrees-test-module-mocks')).worktreeLogicModuleMock(
+    (await importOriginal()) as Record<string, unknown>
+  )
+)
+vi.mock('../terminal-history-deletion', async () =>
+  (await import('./worktrees-test-module-mocks')).terminalHistoryDeletionModuleMock()
+)
+vi.mock('../ports/advertised-url-watcher', async () =>
+  (await import('./worktrees-test-module-mocks')).advertisedUrlWatcherModuleMock()
+)
+vi.mock('../workspace-cleanup-scan-snapshot', async () =>
+  (await import('./worktrees-test-module-mocks')).workspaceCleanupScanSnapshotModuleMock()
+)
+vi.mock('../workspace-space-analysis-snapshot', async () =>
+  (await import('./worktrees-test-module-mocks')).workspaceSpaceAnalysisSnapshotModuleMock()
+)
+vi.mock('../workspace-cleanup-removal-snapshot-prune', async () =>
+  (await import('./worktrees-test-module-mocks')).workspaceCleanupRemovalSnapshotPruneModuleMock()
+)
+vi.mock('../local-worktree-path-presence', async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  localWorktreePathsExistOrAreUnverifiable: localWorktreePathPresenceMock
+}))
+vi.mock('../runtime/worktree-teardown', async () =>
+  (await import('./worktrees-test-module-mocks')).worktreeTeardownModuleMock()
+)
+vi.mock('./pty', async () => (await import('./worktrees-test-module-mocks')).ptyModuleMock())
+
+const REPO_ID = 'repo-1'
+const REPO_PATH = '/workspace/repo'
+const LOCAL_HOST_ID = 'local'
+
+function worktree(path: string, overrides: Partial<GitWorktreeInfo> = {}): GitWorktreeInfo {
+  return {
+    path,
+    head: path,
+    branch: `refs/heads/${path.split('/').at(-1) ?? 'main'}`,
+    isBare: false,
+    isMainWorktree: path === REPO_PATH,
+    ...overrides
+  }
+}
+
+function scanExpectation(
+  worktreeIds: readonly string[]
+): NativeLocalWorktreeMetadataScanExpectation {
+  const expectedRepo = {
+    id: REPO_ID,
+    path: REPO_PATH,
+    displayName: 'repo',
+    badgeColor: '#000',
+    addedAt: 0
+  }
+  return {
+    repo: {
+      id: REPO_ID,
+      path: REPO_PATH,
+      kind: 'git',
+      expectedRepo
+    },
+    routing: {
+      expectedProject: undefined,
+      expectedProjectUpdatedAt: undefined,
+      expectedSettings:
+        {} as NativeLocalWorktreeMetadataScanExpectation['routing']['expectedSettings']
+    },
+    metadata: worktreeIds.map((worktreeId) => ({
+      worktreeId,
+      expectedLegacy: {
+        expectedPresent: true,
+        expectedMeta: undefined,
+        expectedSerialized: undefined,
+        expectedInstanceId: undefined,
+        expectedHostId: LOCAL_HOST_ID
+      },
+      expectedAliases: []
+    }))
+  }
+}
+
+function listDetected(): Promise<unknown> {
+  return handlers['worktrees:listDetected'](null, { repoId: REPO_ID }) as Promise<unknown>
+}
+
+const localListingCalls = [
+  ['worktrees:listDetected', listDetected],
+  [
+    'worktrees:list',
+    () => handlers['worktrees:list'](null, { repoId: REPO_ID }) as Promise<unknown>
+  ],
+  ['worktrees:listAll', () => handlers['worktrees:listAll'](null, undefined) as Promise<unknown>]
+] as const
+
+describe('authoritative local worktree metadata pruning integration', () => {
+  beforeEach(() => {
+    setupWorktreeHandlers()
+    localWorktreePathPresenceMock.mockReset()
+    localWorktreePathPresenceMock.mockImplementation(
+      async (pathValues: readonly string[]) =>
+        new Map(pathValues.map((pathValue) => [pathValue, false]))
+    )
+  })
+
+  it('captures metadata expectations before starting the Git scan', async () => {
+    const order: string[] = []
+    store.captureNativeLocalWorktreeMetadataScanExpectation.mockImplementation(() => {
+      order.push('capture')
+      return scanExpectation([])
+    })
+    listWorktreesMock.mockImplementation(() => {
+      order.push('scan')
+      return Promise.resolve([worktree(REPO_PATH)])
+    })
+
+    await listDetected()
+
+    expect(order).toEqual(['capture', 'scan'])
+  })
+
+  it('prunes once for the fresh producer, while coalesced and cached callers do nothing', async () => {
+    const staleId = `${REPO_ID}::/workspace/stale`
+    const rows = [worktree(REPO_PATH), worktree('/workspace/live')]
+    store.captureNativeLocalWorktreeMetadataScanExpectation.mockReturnValue(
+      scanExpectation([staleId])
+    )
+    store.pruneSessionlessMissingLocalWorktreeMetadataForRepo.mockReturnValue([staleId])
+    listWorktreesMock.mockImplementation(async () => {
+      await Promise.resolve()
+      return rows
+    })
+
+    await Promise.all([listDetected(), listDetected(), listDetected()])
+    await listDetected()
+
+    expect(store.captureNativeLocalWorktreeMetadataScanExpectation).toHaveBeenCalledTimes(1)
+    expect(store.pruneSessionlessMissingLocalWorktreeMetadataForRepo).toHaveBeenCalledTimes(1)
+    const firstPruneCall = store.pruneSessionlessMissingLocalWorktreeMetadataForRepo.mock
+      .calls[0] as [unknown, readonly { worktreeId: string }[]] | undefined
+    expect(firstPruneCall?.[1].map(({ worktreeId }) => worktreeId)).toEqual([staleId])
+    expect(pruneCleanupScanSnapshotsMock).toHaveBeenCalledTimes(1)
+    expect(pruneCleanupScanSnapshotsMock).toHaveBeenCalledWith('/profile-a', [
+      { worktreeId: staleId, executionHostId: LOCAL_HOST_ID }
+    ])
+    expect(pruneSpaceAnalysisSnapshotsMock).toHaveBeenCalledTimes(1)
+    expect(pruneSpaceAnalysisSnapshotsMock).toHaveBeenCalledWith('/profile-a', [
+      { worktreeId: staleId, executionHostId: LOCAL_HOST_ID }
+    ])
+  })
+
+  it('does not prune when the authoritative scan is invalidated while in flight', async () => {
+    const staleId = `${REPO_ID}::/workspace/stale`
+    let resolveScan: (rows: GitWorktreeInfo[]) => void = () => {}
+    store.captureNativeLocalWorktreeMetadataScanExpectation.mockReturnValue(
+      scanExpectation([staleId])
+    )
+    store.pruneSessionlessMissingLocalWorktreeMetadataForRepo.mockReturnValue([staleId])
+    listWorktreesMock.mockImplementation(
+      () =>
+        new Promise((resolve) => {
+          resolveScan = resolve as (rows: GitWorktreeInfo[]) => void
+        })
+    )
+
+    const pending = listDetected()
+    await Promise.resolve()
+    notifyWorktreesChanged(mainWindow as never, REPO_ID)
+    resolveScan([worktree(REPO_PATH), worktree('/workspace/live')])
+    await pending
+
+    expect(store.captureNativeLocalWorktreeMetadataScanExpectation).toHaveBeenCalledTimes(1)
+    expect(store.pruneSessionlessMissingLocalWorktreeMetadataForRepo).not.toHaveBeenCalled()
+    expect(pruneCleanupScanSnapshotsMock).not.toHaveBeenCalled()
+    expect(pruneSpaceAnalysisSnapshotsMock).not.toHaveBeenCalled()
+  })
+
+  it('does not prune when the completed scan is invalidated before its caller resumes', async () => {
+    const staleId = `${REPO_ID}::/workspace/stale`
+    let resolveScan: (rows: GitWorktreeInfo[]) => void = () => {}
+    store.captureNativeLocalWorktreeMetadataScanExpectation.mockReturnValue(
+      scanExpectation([staleId])
+    )
+    store.pruneSessionlessMissingLocalWorktreeMetadataForRepo.mockReturnValue([staleId])
+    listWorktreesMock.mockImplementation(
+      () =>
+        new Promise((resolve) => {
+          resolveScan = resolve as (rows: GitWorktreeInfo[]) => void
+        })
+    )
+
+    const pending = listDetected()
+    await Promise.resolve()
+    resolveScan([worktree(REPO_PATH)])
+    queueMicrotask(() => notifyWorktreesChanged(mainWindow as never, REPO_ID))
+    await pending
+
+    expect(store.pruneSessionlessMissingLocalWorktreeMetadataForRepo).not.toHaveBeenCalled()
+  })
+
+  it.each(localListingCalls)(
+    'skips stale WSL root and lineage side effects after %s caller resumption',
+    async (_channel, listWorktrees) => {
+      const orphanId = `${REPO_ID}::/workspace/orphan`
+      let resolveScan: (rows: GitWorktreeInfo[]) => void = () => {}
+      mockSelectedWslProjectRuntime()
+      store.getAllWorktreeLineage.mockReturnValue({
+        [orphanId]: {
+          worktreeId: orphanId,
+          worktreeInstanceId: 'orphan-instance',
+          parentWorktreeId: `${REPO_ID}::${REPO_PATH}`,
+          parentWorktreeInstanceId: 'main-instance',
+          origin: 'manual',
+          capture: { source: 'manual-action', confidence: 'explicit' },
+          createdAt: 0
+        }
+      })
+      listWorktreesMock.mockImplementation(
+        () =>
+          new Promise((resolve) => {
+            resolveScan = resolve as (rows: GitWorktreeInfo[]) => void
+          })
+      )
+
+      const pending = listWorktrees()
+      await Promise.resolve()
+      resolveScan([worktree(REPO_PATH)])
+      queueMicrotask(() => notifyWorktreesChanged(mainWindow as never, REPO_ID))
+      await pending
+
+      expect(store.removeWorktreeLineage).not.toHaveBeenCalled()
+      expect(isRegisteredWorktreePath(REPO_PATH)).toBe(false)
+    }
+  )
+
+  it('preserves WSL roots and lineage created while an older Git scan is pending', async () => {
+    const newPath = '/workspace/new-wsl-worktree'
+    const newId = `${REPO_ID}::${newPath}`
+    let resolveScan: (rows: GitWorktreeInfo[]) => void = () => {}
+    mockSelectedWslProjectRuntime()
+    listWorktreesMock.mockImplementation(
+      () =>
+        new Promise((resolve) => {
+          resolveScan = resolve as (rows: GitWorktreeInfo[]) => void
+        })
+    )
+
+    const pending = listDetected()
+    await Promise.resolve()
+
+    resolveScan([worktree(REPO_PATH)])
+    queueMicrotask(() => {
+      registerWorktreeRootsForRepo(store as never, REPO_ID, [REPO_PATH, newPath])
+      store.setWorktreeMeta(newId, { hostId: LOCAL_HOST_ID, instanceId: 'new-instance' })
+      store.getAllWorktreeLineage.mockReturnValue({
+        [newId]: {
+          worktreeId: newId,
+          worktreeInstanceId: 'new-instance',
+          parentWorktreeId: `${REPO_ID}::${REPO_PATH}`,
+          parentWorktreeInstanceId: 'main-instance',
+          origin: 'manual',
+          capture: { source: 'manual-action', confidence: 'explicit' },
+          createdAt: 0
+        }
+      })
+    })
+    await pending
+
+    expect(store.removeWorktreeLineage).not.toHaveBeenCalled()
+    expect(isRegisteredWorktreePath(newPath)).toBe(true)
+  })
+
+  it.each(['scan generation', 'caller request'] as const)(
+    'skips metadata, root, and lineage mutations when the %s is invalidated during path probes',
+    async (invalidation) => {
+      const staleId = `${REPO_ID}::/workspace/stale`
+      const orphanId = `${REPO_ID}::/workspace/orphan`
+      let callerCurrent = true
+      let resolvePresence: (presence: ReadonlyMap<string, boolean>) => void = () => {}
+      store.captureNativeLocalWorktreeMetadataScanExpectation.mockReturnValue(
+        scanExpectation([staleId])
+      )
+      store.pruneSessionlessMissingLocalWorktreeMetadataForRepo.mockReturnValue([staleId])
+      store.getAllWorktreeLineage.mockReturnValue({
+        [orphanId]: {
+          worktreeId: orphanId,
+          worktreeInstanceId: 'orphan-instance',
+          parentWorktreeId: `${REPO_ID}::${REPO_PATH}`,
+          parentWorktreeInstanceId: 'main-instance',
+          origin: 'manual',
+          capture: { source: 'manual-action', confidence: 'explicit' },
+          createdAt: 0
+        }
+      })
+      localWorktreePathPresenceMock.mockImplementationOnce(
+        () =>
+          new Promise((resolve) => {
+            resolvePresence = resolve
+          })
+      )
+      listWorktreesMock.mockResolvedValue([worktree(REPO_PATH)])
+
+      const pending = listDetectedWorktreesForCapturedRepo(
+        store as never,
+        store.getRepo(REPO_ID) as never,
+        () => callerCurrent
+      )
+      await vi.waitFor(() => expect(localWorktreePathPresenceMock).toHaveBeenCalledTimes(1))
+      if (invalidation === 'scan generation') {
+        notifyWorktreesChanged(mainWindow as never, REPO_ID)
+      } else {
+        callerCurrent = false
+      }
+      resolvePresence(new Map([['/workspace/stale', false]]))
+      await pending
+
+      expect(store.pruneSessionlessMissingLocalWorktreeMetadataForRepo).not.toHaveBeenCalled()
+      expect(store.removeWorktreeLineage).not.toHaveBeenCalled()
+      expect(isRegisteredWorktreePath(REPO_PATH)).toBe(false)
+      expect(pruneCleanupScanSnapshotsMock).not.toHaveBeenCalled()
+      expect(pruneSpaceAnalysisSnapshotsMock).not.toHaveBeenCalled()
+    }
+  )
+
+  it('preserves roots and lineage created while an older path probe is pending', async () => {
+    const staleId = `${REPO_ID}::/workspace/stale`
+    const newPath = '/workspace/new-worktree'
+    const newId = `${REPO_ID}::${newPath}`
+    let resolvePresence: (presence: ReadonlyMap<string, boolean>) => void = () => {}
+    const metadata = new Map<string, { hostId: string; instanceId: string }>()
+    store.getWorktreeMeta.mockImplementation((worktreeId) => metadata.get(worktreeId))
+    store.captureNativeLocalWorktreeMetadataScanExpectation.mockReturnValue(
+      scanExpectation([staleId])
+    )
+    store.pruneSessionlessMissingLocalWorktreeMetadataForRepo.mockReturnValue([staleId])
+    localWorktreePathPresenceMock.mockImplementationOnce(
+      () =>
+        new Promise((resolve) => {
+          resolvePresence = resolve
+        })
+    )
+    listWorktreesMock.mockResolvedValue([worktree(REPO_PATH)])
+
+    const pending = listDetected()
+    await vi.waitFor(() => expect(localWorktreePathPresenceMock).toHaveBeenCalledTimes(1))
+
+    registerWorktreeRootsForRepo(store as never, REPO_ID, [REPO_PATH, newPath])
+    const newMetadata = { hostId: LOCAL_HOST_ID, instanceId: 'new-instance' }
+    metadata.set(newId, newMetadata)
+    store.setWorktreeMeta(newId, newMetadata)
+    store.getAllWorktreeLineage.mockReturnValue({
+      [newId]: {
+        worktreeId: newId,
+        worktreeInstanceId: newMetadata.instanceId,
+        parentWorktreeId: `${REPO_ID}::${REPO_PATH}`,
+        parentWorktreeInstanceId: 'main-instance',
+        origin: 'manual',
+        capture: { source: 'manual-action', confidence: 'explicit' },
+        createdAt: 0
+      }
+    })
+    resolvePresence(new Map([['/workspace/stale', false]]))
+    await pending
+
+    expect(store.pruneSessionlessMissingLocalWorktreeMetadataForRepo).toHaveBeenCalledTimes(1)
+    expect(store.removeWorktreeLineage).not.toHaveBeenCalled()
+    expect(isRegisteredWorktreePath(newPath)).toBe(true)
+  })
+
+  it('does not capture or prune on an initial WSL scan', async () => {
+    mockSelectedWslProjectRuntime()
+    listWorktreesMock.mockResolvedValue([worktree(REPO_PATH)])
+
+    await listDetected()
+
+    expect(listWorktreesMock).toHaveBeenCalledWith(REPO_PATH, { wslDistro: 'Ubuntu' })
+    expect(store.captureNativeLocalWorktreeMetadataScanExpectation).not.toHaveBeenCalled()
+    expect(store.pruneSessionlessMissingLocalWorktreeMetadataForRepo).not.toHaveBeenCalled()
+  })
+
+  it('does not let a native scan that changes to WSL routing become destructive', async () => {
+    const staleId = `${REPO_ID}::/workspace/stale`
+    const resolvers: ((rows: GitWorktreeInfo[]) => void)[] = []
+    store.captureNativeLocalWorktreeMetadataScanExpectation.mockReturnValue(
+      scanExpectation([staleId])
+    )
+    store.pruneSessionlessMissingLocalWorktreeMetadataForRepo.mockReturnValue([staleId])
+    listWorktreesMock.mockImplementation(
+      () =>
+        new Promise((resolve) => {
+          resolvers.push(resolve as (rows: GitWorktreeInfo[]) => void)
+        })
+    )
+
+    const nativePending = listDetected()
+    await Promise.resolve()
+    mockSelectedWslProjectRuntime()
+    const wslPending = listDetected()
+    await Promise.resolve()
+
+    resolvers[1]?.([worktree(REPO_PATH)])
+    await wslPending
+    resolvers[0]?.([worktree(REPO_PATH), worktree('/workspace/live')])
+    await nativePending
+
+    expect(store.captureNativeLocalWorktreeMetadataScanExpectation).toHaveBeenCalledTimes(1)
+    expect(store.pruneSessionlessMissingLocalWorktreeMetadataForRepo).not.toHaveBeenCalled()
+    expect(pruneCleanupScanSnapshotsMock).not.toHaveBeenCalled()
+    expect(pruneSpaceAnalysisSnapshotsMock).not.toHaveBeenCalled()
+  })
+
+  it.each([
+    ['empty', [] as GitWorktreeInfo[]],
+    ['failed', new Error('git worktree list failed')]
+  ] as const)('does nothing for an %s authoritative scan', async (_label, result) => {
+    const staleId = `${REPO_ID}::/workspace/stale`
+    store.captureNativeLocalWorktreeMetadataScanExpectation.mockReturnValue(
+      scanExpectation([staleId])
+    )
+    store.pruneSessionlessMissingLocalWorktreeMetadataForRepo.mockReturnValue([staleId])
+    if (result instanceof Error) {
+      listWorktreesMock.mockRejectedValue(result)
+    } else {
+      listWorktreesMock.mockResolvedValue(result)
+    }
+
+    await listDetected()
+
+    expect(store.pruneSessionlessMissingLocalWorktreeMetadataForRepo).not.toHaveBeenCalled()
+    expect(pruneCleanupScanSnapshotsMock).not.toHaveBeenCalled()
+    expect(pruneSpaceAnalysisSnapshotsMock).not.toHaveBeenCalled()
+  })
+
+  it('keeps prunable Git registrations live and does not probe their paths', async () => {
+    const staleId = `${REPO_ID}::/workspace/stale`
+    const liveId = `${REPO_ID}::/workspace/live`
+    const prunableId = `${REPO_ID}::/workspace/prunable`
+    store.captureNativeLocalWorktreeMetadataScanExpectation.mockReturnValue(
+      scanExpectation([staleId, liveId, prunableId])
+    )
+    store.pruneSessionlessMissingLocalWorktreeMetadataForRepo.mockReturnValue([staleId])
+    listWorktreesMock.mockResolvedValue([
+      worktree(REPO_PATH),
+      worktree('/workspace/live'),
+      worktree('/workspace/prunable', { prunable: true })
+    ])
+
+    await listDetected()
+
+    expect(store.pruneSessionlessMissingLocalWorktreeMetadataForRepo).toHaveBeenCalledTimes(1)
+    const missing = store.pruneSessionlessMissingLocalWorktreeMetadataForRepo.mock.calls[0]?.[1] as
+      | readonly { worktreeId: string }[]
+      | undefined
+    expect(missing?.map(({ worktreeId }) => worktreeId)).toEqual([staleId])
+    expect(missing?.map(({ worktreeId }) => worktreeId)).not.toContain(liveId)
+    expect(missing?.map(({ worktreeId }) => worktreeId)).not.toContain(prunableId)
+    expect(localWorktreePathPresenceMock).toHaveBeenCalledWith(['/workspace/stale'], {
+      signal: undefined
+    })
+  })
+
+  it('keeps the configured repo path live when Git reports a canonical spelling', async () => {
+    const configuredMainId = `${REPO_ID}::${REPO_PATH}`
+    const staleId = `${REPO_ID}::/workspace/stale`
+    store.captureNativeLocalWorktreeMetadataScanExpectation.mockReturnValue(
+      scanExpectation([configuredMainId, staleId])
+    )
+    store.pruneSessionlessMissingLocalWorktreeMetadataForRepo.mockReturnValue([staleId])
+    listWorktreesMock.mockResolvedValue([worktree('/canonical/workspace/repo')])
+
+    await listDetected()
+
+    const missing = store.pruneSessionlessMissingLocalWorktreeMetadataForRepo.mock.calls[0]?.[1] as
+      | readonly { worktreeId: string }[]
+      | undefined
+    expect(missing?.map(({ worktreeId }) => worktreeId)).toEqual([staleId])
+    expect(missing?.map(({ worktreeId }) => worktreeId)).not.toContain(configuredMainId)
+  })
+
+  it('keeps a linked worktree whose persisted symlink spelling still exists', async () => {
+    const aliasId = `${REPO_ID}::/workspace/alias/linked`
+    const staleId = `${REPO_ID}::/workspace/stale`
+    const scan = scanExpectation([aliasId, staleId])
+    const repo = scan.repo.expectedRepo!
+    const prune = vi.fn(
+      (
+        _scan: NativeLocalWorktreeMetadataScanExpectation,
+        _missing: readonly { worktreeId: string }[]
+      ) => [] as string[]
+    )
+
+    await pruneMetadataMissingFromAuthoritativeLocalScan({
+      store: {
+        getRepos: () => [repo],
+        pruneSessionlessMissingLocalWorktreeMetadataForRepo: prune
+      } as never,
+      repo,
+      gitWorktrees: [worktree('/workspace/real/linked')],
+      scan,
+      scanGeneration: getLocalWorktreeScanGeneration(REPO_ID),
+      pathsExistOrAreUnverifiable: async (pathValues) =>
+        new Map(pathValues.map((pathValue) => [pathValue, pathValue === '/workspace/alias/linked']))
+    })
+
+    expect(prune.mock.calls[0]?.[1].map(({ worktreeId }) => worktreeId)).toEqual([staleId])
+  })
+
+  it('does not rematerialize a removed lineage parent metadata row', async () => {
+    const staleId = `${REPO_ID}::/workspace/stale`
+    store.captureNativeLocalWorktreeMetadataScanExpectation.mockReturnValue(
+      scanExpectation([staleId])
+    )
+    store.pruneSessionlessMissingLocalWorktreeMetadataForRepo.mockReturnValue([staleId])
+    store.getAllWorktreeLineage.mockReturnValue({
+      [`${REPO_ID}::/workspace/live-child`]: {
+        worktreeId: `${REPO_ID}::/workspace/live-child`,
+        worktreeInstanceId: 'child-instance',
+        parentWorktreeId: staleId,
+        parentWorktreeInstanceId: 'stale-instance',
+        origin: 'manual',
+        capture: { source: 'manual-action', confidence: 'explicit' },
+        createdAt: 0
+      }
+    })
+    listWorktreesMock.mockResolvedValue([worktree(REPO_PATH), worktree('/workspace/live')])
+
+    await listDetected()
+
+    expect(store.pruneSessionlessMissingLocalWorktreeMetadataForRepo).toHaveBeenCalledTimes(1)
+    expect(store.setWorktreeMeta.mock.calls.some(([worktreeId]) => worktreeId === staleId)).toBe(
+      false
+    )
+  })
+})
diff --git a/src/main/ipc/worktrees-test-harness.ts b/src/main/ipc/worktrees-test-harness.ts
index 0eacf52e472..1888156a692 100644
--- a/src/main/ipc/worktrees-test-harness.ts
+++ b/src/main/ipc/worktrees-test-harness.ts
@@ -7,6 +7,7 @@ import { resetRetirementCollisionKeyCacheForTests } from '../worktree-name-retir
 import { resetSshProviderAuthorities } from '../ssh/ssh-provider-authority'
 import { createWorktreeRuntimeStub, type WorktreeRuntimeStub } from './worktrees-test-runtime-stub'
 import { handlers, mainWindow, store } from './worktrees-test-ipc-surface'
+import { configureMetadataPruningStoreMocks } from './worktrees-test-metadata-pruning-store'
 import {
   ORIGINAL_PLATFORM,
   setPlatform,
@@ -129,10 +130,12 @@ export function setupWorktreeHandlers(): WorktreeRuntimeStub {
     store.getWorktreeMeta,
     store.getWorktreeMetaForHost,
     store.getAllWorktreeMeta,
+    store.captureNativeLocalWorktreeMetadataScanExpectation,
     store.setWorktreeMeta,
     store.setWorktreeMetaForHost,
     store.getProjectHostSetups,
     store.removeWorktreeMeta,
+    store.pruneSessionlessMissingLocalWorktreeMetadataForRepo,
     store.removeWorkspaceSessionStateForWorktree,
     store.getAllWorktreeLineage,
     store.removeWorktreeLineage,
@@ -187,12 +190,13 @@ export function setupWorktreeHandlers(): WorktreeRuntimeStub {
   store.getRepo.mockReturnValue({ ...repo, worktreeBaseRef: null })
   store.getProjects.mockReturnValue([])
   store.getSparsePresets.mockReturnValue([])
-  store.getSettings.mockReturnValue({
+  const settings = {
     branchPrefix: 'none',
     nestWorkspaces: false,
     refreshLocalBaseRefOnWorktreeCreate: false,
     workspaceDir: '/workspace'
-  })
+  }
+  store.getSettings.mockReturnValue(settings)
   store.getWorktreeMeta.mockReturnValue(undefined)
   // Host-qualified accessors delegate by default so payload assertions stay on one spy;
   // host routing itself is covered by worktree-identity-persistence.test.ts.
@@ -200,6 +204,7 @@ export function setupWorktreeHandlers(): WorktreeRuntimeStub {
     store.getWorktreeMeta(args[0] as string)
   )
   store.getAllWorktreeMeta.mockReturnValue({})
+  configureMetadataPruningStoreMocks(store, settings)
   store.getRetiredWorktreeNameRegistry.mockReturnValue({ exhaustedTiers: 0, names: [] })
   resetRetirementCollisionKeyCacheForTests()
   store.setWorktreeMeta.mockReturnValue({})
diff --git a/src/main/ipc/worktrees-test-ipc-surface.ts b/src/main/ipc/worktrees-test-ipc-surface.ts
index cc4b497b1bc..a858aacf6b8 100644
--- a/src/main/ipc/worktrees-test-ipc-surface.ts
+++ b/src/main/ipc/worktrees-test-ipc-surface.ts
@@ -24,10 +24,12 @@ export type TestStore = {
   getWorktreeMeta: KeyedStoreMock
   getWorktreeMetaForHost: StoreMock
   getAllWorktreeMeta: StoreMock
+  captureNativeLocalWorktreeMetadataScanExpectation: StoreMock
   setWorktreeMeta: KeyedStoreWriteMock
   setWorktreeMetaForHost: StoreMock
   getProjectHostSetups: StoreMock
   removeWorktreeMeta: KeyedStoreMock
+  pruneSessionlessMissingLocalWorktreeMetadataForRepo: StoreMock
   removeWorkspaceSessionStateForWorktree: KeyedStoreMock
   getAllWorktreeLineage: StoreMock
   removeWorktreeLineage: KeyedStoreMock
@@ -58,10 +60,12 @@ export const store: TestStore = {
   getWorktreeMeta: vi.fn(),
   getWorktreeMetaForHost: vi.fn(),
   getAllWorktreeMeta: vi.fn(),
+  captureNativeLocalWorktreeMetadataScanExpectation: vi.fn(),
   setWorktreeMeta: vi.fn(),
   setWorktreeMetaForHost: vi.fn(),
   getProjectHostSetups: vi.fn(),
   removeWorktreeMeta: vi.fn(),
+  pruneSessionlessMissingLocalWorktreeMetadataForRepo: vi.fn(),
   removeWorkspaceSessionStateForWorktree: vi.fn(),
   getAllWorktreeLineage: vi.fn(),
   removeWorktreeLineage: vi.fn(),
diff --git a/src/main/ipc/worktrees-test-metadata-pruning-store.ts b/src/main/ipc/worktrees-test-metadata-pruning-store.ts
new file mode 100644
index 00000000000..dd60acaa027
--- /dev/null
+++ b/src/main/ipc/worktrees-test-metadata-pruning-store.ts
@@ -0,0 +1,35 @@
+import type { TestStore } from './worktrees-test-ipc-surface'
+
+export function configureMetadataPruningStoreMocks(
+  store: TestStore,
+  expectedSettings: unknown
+): void {
+  store.captureNativeLocalWorktreeMetadataScanExpectation.mockImplementation(
+    (...args: unknown[]) => {
+      const repo = args[0] as {
+        id: string
+        path: string
+        connectionId?: string | null
+        executionHostId?: string | null
+        kind?: string
+      }
+      return {
+        repo: {
+          id: repo.id,
+          path: repo.path,
+          connectionId: repo.connectionId,
+          executionHostId: repo.executionHostId,
+          kind: repo.kind === 'folder' ? 'folder' : 'git',
+          expectedRepo: repo
+        },
+        routing: {
+          expectedProject: undefined,
+          expectedProjectUpdatedAt: undefined,
+          expectedSettings
+        },
+        metadata: []
+      }
+    }
+  )
+  store.pruneSessionlessMissingLocalWorktreeMetadataForRepo.mockReturnValue([])
+}
diff --git a/src/main/ipc/worktrees-windows.test.ts b/src/main/ipc/worktrees-windows.test.ts
index b22d7decd84..3826f5493a8 100644
--- a/src/main/ipc/worktrees-windows.test.ts
+++ b/src/main/ipc/worktrees-windows.test.ts
@@ -166,6 +166,7 @@ describe('registerWorktreeHandlers – Windows path handling', () => {
     getSettings: vi.fn(),
     getWorktreeMeta: vi.fn(),
     getAllWorktreeMeta: vi.fn(),
+    captureNativeLocalWorktreeMetadataScanExpectation: vi.fn(),
     setWorktreeMeta: vi.fn(),
     removeWorktreeMeta: vi.fn(),
     addRetiredWorktreeName: vi.fn(),
@@ -211,6 +212,7 @@ describe('registerWorktreeHandlers – Windows path handling', () => {
     store.getSettings.mockReset()
     store.getWorktreeMeta.mockReset()
     store.getAllWorktreeMeta.mockReset()
+    store.captureNativeLocalWorktreeMetadataScanExpectation.mockReset()
     store.setWorktreeMeta.mockReset()
     store.removeWorktreeMeta.mockReset()
     store.addRetiredWorktreeName.mockReset()
@@ -254,6 +256,20 @@ describe('registerWorktreeHandlers – Windows path handling', () => {
     resolveSetupRunnerShellMock.mockReturnValue(undefined)
     store.getWorktreeMeta.mockReturnValue(undefined)
     store.getAllWorktreeMeta.mockReturnValue({})
+    store.captureNativeLocalWorktreeMetadataScanExpectation.mockImplementation((repo) => ({
+      repo: {
+        id: repo.id,
+        path: repo.path,
+        kind: 'git',
+        expectedRepo: repo
+      },
+      routing: {
+        expectedProject: undefined,
+        expectedProjectUpdatedAt: undefined,
+        expectedSettings: store.getSettings()
+      },
+      metadata: []
+    }))
     store.getRetiredWorktreeNameRegistry.mockReturnValue({ exhaustedTiers: 0, names: [] })
     store.setWorktreeMeta.mockReturnValue({})
     resolveLocalGitUsernameMock.mockResolvedValue('')
diff --git a/src/main/ipc/worktrees/listing/authoritative-local-worktree-metadata-pruning.ts b/src/main/ipc/worktrees/listing/authoritative-local-worktree-metadata-pruning.ts
new file mode 100644
index 00000000000..c5ceb1acafb
--- /dev/null
+++ b/src/main/ipc/worktrees/listing/authoritative-local-worktree-metadata-pruning.ts
@@ -0,0 +1,141 @@
+import { getRepoExecutionHostId, LOCAL_EXECUTION_HOST_ID } from '../../../../shared/execution-host'
+import { isWindowsAbsolutePathLike } from '../../../../shared/cross-platform-path'
+import { isFolderRepo } from '../../../../shared/repo-kind'
+import type { Repo } from '../../../../shared/repo-types'
+import {
+  FOLDER_WORKSPACE_INSTANCE_SEPARATOR,
+  splitWorktreeId
+} from '../../../../shared/worktree/id'
+import type { GitWorktreeInfo } from '../../../../shared/worktree/types'
+import { isWslUncPath } from '../../../../shared/wsl-paths'
+import type { Store } from '../../../persistence/loading-store/store'
+import type { NativeLocalWorktreeMetadataScanExpectation } from '../../../persistence/tracking-repos/missing-local-worktree-metadata-pruning'
+import { pruneWorkspaceCleanupScanSnapshots } from '../../../workspace-cleanup-scan-snapshot'
+import { pruneWorkspaceSpaceAnalysisSnapshots } from '../../../workspace-space-analysis-snapshot'
+import { isLocalWorktreeScanGenerationCurrent } from '../../../local-worktree-scan-generation'
+import { localWorktreePathsExistOrAreUnverifiable } from '../../../local-worktree-path-presence'
+import { worktreeRetentionPathComparisonKey } from '../../../worktree-retention-path-comparison'
+
+type AuthoritativeLocalMetadataPruneArgs = {
+  store: Store
+  repo: Repo
+  gitWorktrees: readonly GitWorktreeInfo[]
+  scan: NativeLocalWorktreeMetadataScanExpectation
+  scanGeneration: number
+  platform?: NodeJS.Platform
+  pathsExistOrAreUnverifiable?: (
+    pathValues: readonly string[],
+    options?: { signal?: AbortSignal }
+  ) => Promise<ReadonlyMap<string, boolean>>
+  isCallerCurrent?: () => boolean
+  signal?: AbortSignal
+}
+
+export type AuthoritativeLocalMetadataPruneResult = Readonly<{
+  removedWorktreeIds: readonly string[]
+  preservedMetadataCandidateIds: ReadonlySet<string>
+  scanGenerationCurrent: boolean
+}>
+
+export async function pruneMetadataMissingFromAuthoritativeLocalScan({
+  store,
+  repo,
+  gitWorktrees,
+  scan,
+  scanGeneration,
+  platform = process.platform,
+  pathsExistOrAreUnverifiable = localWorktreePathsExistOrAreUnverifiable,
+  isCallerCurrent = () => true,
+  signal
+}: AuthoritativeLocalMetadataPruneArgs): Promise<AuthoritativeLocalMetadataPruneResult> {
+  const capturedCandidateIds = scan.metadata.map(({ worktreeId }) => worktreeId)
+  const result = (
+    removedWorktreeIds: readonly string[],
+    scanGenerationCurrent: boolean
+  ): AuthoritativeLocalMetadataPruneResult => {
+    const removedIds = new Set(removedWorktreeIds)
+    return {
+      removedWorktreeIds,
+      preservedMetadataCandidateIds: new Set(
+        capturedCandidateIds.filter((worktreeId) => !removedIds.has(worktreeId))
+      ),
+      scanGenerationCurrent
+    }
+  }
+  const generationCurrent = () => isLocalWorktreeScanGenerationCurrent(repo.id, scanGeneration)
+  const repoOwners = store.getRepos().filter((candidate) => candidate.id === repo.id)
+  if (
+    !generationCurrent() ||
+    !isCallerCurrent() ||
+    gitWorktrees.length === 0 ||
+    repoOwners.length !== 1 ||
+    repo.id !== scan.repo.id ||
+    repo.path !== scan.repo.path ||
+    repo.connectionId ||
+    isFolderRepo(repo) ||
+    getRepoExecutionHostId(repo) !== LOCAL_EXECUTION_HOST_ID ||
+    (platform === 'win32' &&
+      (isWslUncPath(repo.path) || gitWorktrees.some(({ path }) => isWslUncPath(path))))
+  ) {
+    return result([], generationCurrent())
+  }
+
+  const livePathKeys = new Set([
+    // Why: Git can canonicalize a symlinked main checkout differently from the configured path.
+    worktreeRetentionPathComparisonKey(repo.path, platform),
+    ...gitWorktrees.map((worktree) => worktreeRetentionPathComparisonKey(worktree.path, platform))
+  ])
+  const probeCandidates = scan.metadata.flatMap((metadata) => {
+    const { worktreeId } = metadata
+    const parsed = splitWorktreeId(worktreeId)
+    const nativeAbsolute = parsed
+      ? platform === 'win32'
+        ? isWindowsAbsolutePathLike(parsed.worktreePath)
+        : parsed.worktreePath.startsWith('/')
+      : false
+    if (
+      parsed?.repoId !== repo.id ||
+      !nativeAbsolute ||
+      isWslUncPath(parsed.worktreePath) ||
+      worktreeId.includes(FOLDER_WORKSPACE_INSTANCE_SEPARATOR) ||
+      livePathKeys.has(worktreeRetentionPathComparisonKey(parsed.worktreePath, platform))
+    ) {
+      return []
+    }
+    return [{ metadata, pathValue: parsed.worktreePath }]
+  })
+  const presenceByPath = await pathsExistOrAreUnverifiable(
+    probeCandidates.map(({ pathValue }) => pathValue),
+    { signal }
+  )
+  if (!generationCurrent() || !isCallerCurrent()) {
+    return result([], generationCurrent())
+  }
+  const missingMetadata = probeCandidates.flatMap(({ metadata, pathValue }) =>
+    presenceByPath.get(pathValue) === false ? [metadata] : []
+  )
+  if (missingMetadata.length === 0) {
+    return result([], generationCurrent())
+  }
+
+  if (!generationCurrent() || !isCallerCurrent()) {
+    return result([], generationCurrent())
+  }
+  const removedIds = store.pruneSessionlessMissingLocalWorktreeMetadataForRepo(
+    scan,
+    missingMetadata
+  )
+  if (removedIds.length > 0) {
+    const snapshotDirectory = store.getProfileStorageDirectory()
+    const targets: {
+      worktreeId: string
+      executionHostId: typeof LOCAL_EXECUTION_HOST_ID
+    }[] = removedIds.map((worktreeId) => ({
+      worktreeId,
+      executionHostId: LOCAL_EXECUTION_HOST_ID
+    }))
+    void pruneWorkspaceCleanupScanSnapshots(snapshotDirectory, targets)
+    void pruneWorkspaceSpaceAnalysisSnapshots(snapshotDirectory, targets)
+  }
+  return result(removedIds, generationCurrent())
+}
diff --git a/src/main/ipc/worktrees/listing/detected-provider-listing.ts b/src/main/ipc/worktrees/listing/detected-provider-listing.ts
index d855e582161..45ccd4183bb 100644
--- a/src/main/ipc/worktrees/listing/detected-provider-listing.ts
+++ b/src/main/ipc/worktrees/listing/detected-provider-listing.ts
@@ -4,7 +4,6 @@ import { getSshGitProvider } from '../../../providers/ssh-git-dispatch'
 import type { DetectedWorktreeListResult, GitWorktreeInfo } from '../../../../shared/worktree/types'
 import { isFolderRepo } from '../../../../shared/repo-kind'
 import { projectResolvedWorktreeLineage } from '../../../../shared/resolved-worktree-lineage'
-import { pruneLineageForMissingRepoWorktrees } from '../../../worktree-lineage-pruning'
 import type { DirectSshDetectedWorktreeRequest } from '../../../../shared/detected-worktree-provider-contract'
 import { isAdmissibleDirectSshAuthority } from '../../../../shared/ssh-retained-payload-admission'
 import type { ListDesktopLineageForHostArgs } from '../../../../shared/host-lineage-contract'
@@ -20,8 +19,10 @@ import {
 import { isFolderWorkspaceIdForRepo } from '../folder-workspace-model'
 import { hasConflictingStoredWorktreeOwner } from './worktree-host-ownership'
 import {
+  applyFreshDetectedWorktreeScanSideEffects,
   listDetectedGitWorktrees,
-  rememberLocalWorktreeRoots
+  type DetectedWorktreeMetadataPrune,
+  type DetectedWorktreeSideEffectToken
 } from './detected-worktree-scan-cache'
 import { loggedWorktreeListFailures, warnOnce } from './worktree-listing-diagnostics'
 import { readAllWorktreeMetaForHost } from '../../../persistence/host-qualified-worktree-meta'
@@ -48,6 +49,8 @@ export async function listDetectedWorktreesForCapturedRepo(
   try {
     let gitWorktrees: GitWorktreeInfo[]
     let freshScan = true
+    let sideEffectToken: DetectedWorktreeSideEffectToken | undefined
+    let metadataPrune: DetectedWorktreeMetadataPrune | undefined
     if (isFolderRepo(repo)) {
       if (!isCurrent()) {
         return null
@@ -97,6 +100,8 @@ export async function listDetectedWorktreesForCapturedRepo(
       const scan = await listDetectedGitWorktrees(store, repo)
       gitWorktrees = scan.gitWorktrees
       freshScan = scan.fresh
+      sideEffectToken = scan.sideEffectToken
+      metadataPrune = scan.metadataPrune
     }
     const aborted = abortedResult()
     if (aborted) {
@@ -115,8 +120,18 @@ export async function listDetectedWorktreesForCapturedRepo(
       }
     }
     if (freshScan) {
-      rememberLocalWorktreeRoots(store, repo, gitWorktrees)
-      pruneLineageForMissingRepoWorktrees(store, repo, gitWorktrees)
+      await applyFreshDetectedWorktreeScanSideEffects(store, repo, gitWorktrees, metadataPrune, {
+        isCurrent: () => isCurrent() && !providerAbort?.signal.aborted,
+        sideEffectToken,
+        signal: providerAbort?.signal
+      })
+      const aborted = abortedResult()
+      if (aborted) {
+        return aborted
+      }
+      if (!isCurrent()) {
+        return null
+      }
     }
     loggedWorktreeListFailures.delete(`${repo.id}:${repo.path}`)
     return {
diff --git a/src/main/ipc/worktrees/listing/detected-worktree-scan-cache.ts b/src/main/ipc/worktrees/listing/detected-worktree-scan-cache.ts
index 55b3d75e3ed..fea200f1a8b 100644
--- a/src/main/ipc/worktrees/listing/detected-worktree-scan-cache.ts
+++ b/src/main/ipc/worktrees/listing/detected-worktree-scan-cache.ts
@@ -4,7 +4,19 @@ import type { Repo } from '../../../../shared/repo-types'
 import { getLocalProjectWorktreeGitOptions } from '../../../project-runtime-git-options'
 import { isFolderRepo } from '../../../../shared/repo-kind'
 import { listRepoWorktrees } from '../../../repo-worktrees'
-import { registerWorktreeRootsForRepo } from '../../registered-worktree-roots-cache'
+import {
+  getRegisteredWorktreeRootsRevision,
+  registerWorktreeRootsForRepo
+} from '../../registered-worktree-roots-cache'
+import type { NativeLocalWorktreeMetadataScanExpectation } from '../../../persistence/tracking-repos/missing-local-worktree-metadata-pruning'
+import {
+  bumpLocalWorktreeScanGeneration,
+  getLocalWorktreeScanGeneration,
+  isLocalWorktreeScanGenerationCurrent,
+  resetLocalWorktreeScanGenerationsForTests
+} from '../../../local-worktree-scan-generation'
+import { pruneLineageForMissingRepoWorktrees } from '../../../worktree-lineage-pruning'
+import { pruneMetadataMissingFromAuthoritativeLocalScan } from './authoritative-local-worktree-metadata-pruning'
 
 // Why: absorb renderer polling bursts while bounding external worktree-change lag to one short refresh window.
 export const DETECTED_WORKTREE_SCAN_CACHE_TTL_MS = 5_000
@@ -17,17 +29,31 @@ export type DetectedWorktreeScanCacheEntry = {
 export type DetectedWorktreeScan = {
   invalidated: boolean
   promise: Promise<GitWorktreeInfo[]>
+  sideEffectToken: DetectedWorktreeSideEffectToken
+  metadataPrune?: DetectedWorktreeMetadataPrune
 }
 
+export type DetectedWorktreeSideEffectToken = Readonly<{
+  generation: number
+  authorizedRootsRevision: number
+}>
+
+export type DetectedWorktreeMetadataPrune = Readonly<{
+  expectation: NativeLocalWorktreeMetadataScanExpectation
+}>
+
 export type DetectedWorktreeScanResult = {
   gitWorktrees: GitWorktreeInfo[]
   fresh: boolean
+  sideEffectToken?: DetectedWorktreeSideEffectToken
+  metadataPrune?: DetectedWorktreeMetadataPrune
 }
 
 export const detectedWorktreeScanCache = new Map<string, DetectedWorktreeScanCacheEntry>()
 export const detectedWorktreeScanInFlight = new Map<string, DetectedWorktreeScan>()
 
 export function invalidateDetectedWorktreeScanCache(repoId: string): void {
+  bumpLocalWorktreeScanGeneration(repoId)
   const keyPrefix = `${repoId}\0`
   for (const key of new Set([
     ...detectedWorktreeScanCache.keys(),
@@ -53,6 +79,7 @@ export function __resetDetectedWorktreeScanCacheForTests(): void {
   }
   detectedWorktreeScanCache.clear()
   detectedWorktreeScanInFlight.clear()
+  resetLocalWorktreeScanGenerationsForTests()
 }
 
 export function __getDetectedWorktreeScanCacheStatsForTests(): {
@@ -88,21 +115,47 @@ export async function listDetectedGitWorktrees(
     return { gitWorktrees: await inFlight.promise, fresh: false }
   }
 
+  // Why: capture before invoking Git because listing can mutate synchronously before its first await.
+  // WSL listings can use UNC paths while legacy metadata keeps Linux paths; v1 cannot prove
+  // those aliases equivalent, so only native-host scans carry destructive expectations.
+  const generation = getLocalWorktreeScanGeneration(repo.id)
+  const authorizedRootsRevision = getRegisteredWorktreeRootsRevision(repo.id)
+  const metadataPruneExpectation = localWorktreeGitOptions.wslDistro
+    ? undefined
+    : store.captureNativeLocalWorktreeMetadataScanExpectation(repo)
   const scan: DetectedWorktreeScan = {
     invalidated: false,
-    promise: listRepoWorktrees(repo, localWorktreeGitOptions)
+    promise: listRepoWorktrees(repo, localWorktreeGitOptions),
+    sideEffectToken: { generation, authorizedRootsRevision },
+    ...(metadataPruneExpectation
+      ? {
+          metadataPrune: {
+            expectation: metadataPruneExpectation
+          }
+        }
+      : {})
   }
   detectedWorktreeScanInFlight.set(cacheKey, scan)
   try {
     const gitWorktrees = await scan.promise
+    const routingUnchanged =
+      getDetectedWorktreeScanCacheKey(repo.id, getLocalProjectWorktreeGitOptions(store, repo)) ===
+      cacheKey
     // Why: a create/remove notification can invalidate mid-scan; don't let that stale scan repopulate the cache afterward.
-    if (!scan.invalidated) {
+    const generationCurrent = isLocalWorktreeScanGenerationCurrent(repo.id, generation)
+    if (!scan.invalidated && routingUnchanged && generationCurrent) {
       detectedWorktreeScanCache.set(cacheKey, {
         worktrees: gitWorktrees,
         expiresAt: Date.now() + DETECTED_WORKTREE_SCAN_CACHE_TTL_MS
       })
     }
-    return { gitWorktrees, fresh: !scan.invalidated }
+    const fresh = !scan.invalidated && routingUnchanged && generationCurrent
+    return {
+      gitWorktrees,
+      fresh,
+      ...(fresh ? { sideEffectToken: scan.sideEffectToken } : {}),
+      ...(fresh && scan.metadataPrune ? { metadataPrune: scan.metadataPrune } : {})
+    }
   } finally {
     if (detectedWorktreeScanInFlight.get(cacheKey) === scan) {
       detectedWorktreeScanInFlight.delete(cacheKey)
@@ -110,6 +163,63 @@ export async function listDetectedGitWorktrees(
   }
 }
 
+export async function applyFreshDetectedWorktreeScanSideEffects(
+  store: Store,
+  repo: Repo,
+  gitWorktrees: GitWorktreeInfo[],
+  metadataPrune?: DetectedWorktreeMetadataPrune,
+  options: {
+    isCurrent?: () => boolean
+    sideEffectToken?: DetectedWorktreeSideEffectToken
+    signal?: AbortSignal
+  } = {}
+): Promise<boolean> {
+  const { isCurrent = () => true, sideEffectToken, signal } = options
+  const generationCurrent = () =>
+    sideEffectToken === undefined ||
+    isLocalWorktreeScanGenerationCurrent(repo.id, sideEffectToken.generation)
+  if (!generationCurrent() || !isCurrent()) {
+    return false
+  }
+  let preservedMetadataCandidateIds: ReadonlySet<string> | undefined
+  if (metadataPrune) {
+    if (!sideEffectToken) {
+      return false
+    }
+    const pruneResult = await pruneMetadataMissingFromAuthoritativeLocalScan({
+      store,
+      repo,
+      gitWorktrees,
+      scan: metadataPrune.expectation,
+      scanGeneration: sideEffectToken.generation,
+      isCallerCurrent: isCurrent,
+      signal
+    })
+    if (!pruneResult.scanGenerationCurrent || !generationCurrent() || !isCurrent()) {
+      return false
+    }
+    preservedMetadataCandidateIds = pruneResult.preservedMetadataCandidateIds
+  }
+  if (!generationCurrent() || !isCurrent()) {
+    return false
+  }
+
+  if (
+    sideEffectToken &&
+    getRegisteredWorktreeRootsRevision(repo.id) !== sideEffectToken.authorizedRootsRevision
+  ) {
+    return false
+  }
+  rememberLocalWorktreeRoots(store, repo, gitWorktrees)
+  pruneLineageForMissingRepoWorktrees(
+    store,
+    repo,
+    gitWorktrees,
+    preservedMetadataCandidateIds ? { preservedMetadataCandidateIds } : undefined
+  )
+  return true
+}
+
 export function getDetectedWorktreeScanCacheKey(
   repoId: string,
   localWorktreeGitOptions: { wslDistro?: string } = {}
diff --git a/src/main/ipc/worktrees/listing/register-worktree-catalog-handlers.ts b/src/main/ipc/worktrees/listing/register-worktree-catalog-handlers.ts
index ac98130b5eb..4a882ff24b7 100644
--- a/src/main/ipc/worktrees/listing/register-worktree-catalog-handlers.ts
+++ b/src/main/ipc/worktrees/listing/register-worktree-catalog-handlers.ts
@@ -2,7 +2,6 @@ import { ipcMain } from 'electron'
 import { isFolderRepo } from '../../../../shared/repo-kind'
 import { getRepoExecutionHostId, type ExecutionHostId } from '../../../../shared/execution-host'
 import { getSshGitProvider } from '../../../providers/ssh-git-dispatch'
-import { pruneLineageForMissingRepoWorktrees } from '../../../worktree-lineage-pruning'
 import { EMPTY_RETIRED_NAME_REGISTRY } from '../../../../shared/worktree/retired-name-registry'
 import { getRetiredNameRegistryForRepo } from '../../../worktree-name-retirement'
 import {
@@ -13,8 +12,10 @@ import {
 } from './ssh-worktree-fallback'
 import { listVisibleFolderWorkspaces } from './folder-workspace-catalog'
 import {
+  applyFreshDetectedWorktreeScanSideEffects,
   listDetectedGitWorktrees,
-  rememberLocalWorktreeRoots
+  type DetectedWorktreeMetadataPrune,
+  type DetectedWorktreeSideEffectToken
 } from './detected-worktree-scan-cache'
 import {
   loggedUnavailableSshGitProviders,
@@ -88,6 +89,8 @@ export function registerWorktreeCatalogHandlers(context: WorktreeIpcContext): vo
       try {
         let gitWorktrees
         let freshScan = true
+        let sideEffectToken: DetectedWorktreeSideEffectToken | undefined
+        let metadataPrune: DetectedWorktreeMetadataPrune | undefined
         if (isFolderRepo(repo)) {
           return listVisibleFolderWorkspaces(store, repo)
         } else if (repo.connectionId) {
@@ -116,10 +119,19 @@ export function registerWorktreeCatalogHandlers(context: WorktreeIpcContext): vo
           const scan = await listDetectedGitWorktrees(store, repo)
           gitWorktrees = scan.gitWorktrees
           freshScan = scan.fresh
+          sideEffectToken = scan.sideEffectToken
+          metadataPrune = scan.metadataPrune
         }
         if (freshScan) {
-          rememberLocalWorktreeRoots(store, repo, gitWorktrees)
-          pruneLineageForMissingRepoWorktrees(store, repo, gitWorktrees)
+          await applyFreshDetectedWorktreeScanSideEffects(
+            store,
+            repo,
+            gitWorktrees,
+            metadataPrune,
+            {
+              sideEffectToken
+            }
+          )
         }
         loggedWorktreeListFailures.delete(`${repo.id}:${repo.path}`)
         const metadata = metadataForRepo(repo)
@@ -169,6 +181,8 @@ export function registerWorktreeCatalogHandlers(context: WorktreeIpcContext): vo
     try {
       let gitWorktrees
       let freshScan = true
+      let sideEffectToken: DetectedWorktreeSideEffectToken | undefined
+      let metadataPrune: DetectedWorktreeMetadataPrune | undefined
       if (isFolderRepo(repo)) {
         return listVisibleFolderWorkspaces(store, repo)
       } else if (repo.connectionId) {
@@ -197,10 +211,13 @@ export function registerWorktreeCatalogHandlers(context: WorktreeIpcContext): vo
         const scan = await listDetectedGitWorktrees(store, repo)
         gitWorktrees = scan.gitWorktrees
         freshScan = scan.fresh
+        sideEffectToken = scan.sideEffectToken
+        metadataPrune = scan.metadataPrune
       }
       if (freshScan) {
-        rememberLocalWorktreeRoots(store, repo, gitWorktrees)
-        pruneLineageForMissingRepoWorktrees(store, repo, gitWorktrees)
+        await applyFreshDetectedWorktreeScanSideEffects(store, repo, gitWorktrees, metadataPrune, {
+          sideEffectToken
+        })
       }
       loggedWorktreeListFailures.delete(`${repo.id}:${repo.path}`)
       const metadata = allMeta ?? readAllWorktreeMetaForHost(store, getRepoExecutionHostId(repo))
diff --git a/src/main/local-worktree-path-presence.test.ts b/src/main/local-worktree-path-presence.test.ts
new file mode 100644
index 00000000000..d54284f7c6b
--- /dev/null
+++ b/src/main/local-worktree-path-presence.test.ts
@@ -0,0 +1,219 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { statMock } = vi.hoisted(() => ({
+  statMock: vi.fn()
+}))
+
+vi.mock('node:fs/promises', () => ({ stat: statMock }))
+
+import {
+  LOCAL_WORKTREE_PATH_PROBE_TIMEOUT_MS,
+  localWorktreePathExistsOrIsUnverifiable,
+  localWorktreePathsExistOrAreUnverifiable
+} from './local-worktree-path-presence'
+
+function fsError(code: string): NodeJS.ErrnoException {
+  return Object.assign(new Error(code), { code })
+}
+
+function installFakeAbortSignalTimeout(): AbortController[] {
+  const controllers: AbortController[] = []
+  vi.spyOn(AbortSignal, 'timeout').mockImplementation((timeoutMs) => {
+    const controller = new AbortController()
+    controllers.push(controller)
+    setTimeout(
+      () => controller.abort(new DOMException('The operation timed out.', 'TimeoutError')),
+      timeoutMs
+    )
+    return controller.signal
+  })
+  return controllers
+}
+
+describe('local worktree path presence', () => {
+  beforeEach(() => {
+    statMock.mockReset()
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+    vi.restoreAllMocks()
+  })
+
+  it('returns one result per distinct path and only treats ENOENT/ENOTDIR as missing', async () => {
+    statMock.mockImplementation(async (pathValue: string) => {
+      if (pathValue === '/missing') {
+        throw fsError('ENOENT')
+      }
+      if (pathValue === '/not-a-directory') {
+        throw fsError('ENOTDIR')
+      }
+      if (pathValue === '/permission-denied') {
+        throw fsError('EACCES')
+      }
+      return {}
+    })
+
+    const result = await localWorktreePathsExistOrAreUnverifiable([
+      '/present',
+      '/missing',
+      '/not-a-directory',
+      '/permission-denied',
+      '/present'
+    ])
+
+    expect([...result.entries()]).toEqual([
+      ['/present', true],
+      ['/missing', false],
+      ['/not-a-directory', false],
+      ['/permission-denied', true]
+    ])
+    expect(statMock).toHaveBeenCalledTimes(4)
+  })
+
+  it('does not allocate a deadline when there are no paths to probe', async () => {
+    const timeout = vi.spyOn(AbortSignal, 'timeout')
+
+    await expect(localWorktreePathsExistOrAreUnverifiable([])).resolves.toEqual(new Map())
+
+    expect(timeout).not.toHaveBeenCalled()
+    expect(statMock).not.toHaveBeenCalled()
+  })
+
+  it('globally bounds stat calls across simultaneous bulk probes', async () => {
+    let active = 0
+    let maximumActive = 0
+    const pending: (() => void)[] = []
+    statMock.mockImplementation(
+      () =>
+        new Promise((resolve) => {
+          active += 1
+          maximumActive = Math.max(maximumActive, active)
+          pending.push(() => {
+            active -= 1
+            resolve({})
+          })
+        })
+    )
+
+    const first = localWorktreePathsExistOrAreUnverifiable([
+      '/first-1',
+      '/first-2',
+      '/first-3',
+      '/first-4'
+    ])
+    const second = localWorktreePathsExistOrAreUnverifiable([
+      '/second-1',
+      '/second-2',
+      '/second-3',
+      '/second-4'
+    ])
+
+    let resolved = 0
+    while (resolved < 8) {
+      while (pending.length === 0) {
+        await Promise.resolve()
+      }
+      pending.shift()?.()
+      resolved += 1
+      await Promise.resolve()
+    }
+
+    await Promise.all([first, second])
+
+    expect(maximumActive).toBe(2)
+    expect(statMock).toHaveBeenCalledTimes(8)
+  })
+
+  it('uses the same fail-closed classification for a single probe', async () => {
+    statMock.mockRejectedValueOnce(fsError('ENOENT'))
+    statMock.mockRejectedValueOnce(fsError('ENOTDIR'))
+    statMock.mockRejectedValueOnce(fsError('EIO'))
+
+    await expect(localWorktreePathExistsOrIsUnverifiable('/missing')).resolves.toBe(false)
+    await expect(localWorktreePathExistsOrIsUnverifiable('/parent-missing')).resolves.toBe(false)
+    await expect(localWorktreePathExistsOrIsUnverifiable('/unverifiable')).resolves.toBe(true)
+  })
+
+  it('settles timed-out batches without exceeding or leaking the global stat bound', async () => {
+    vi.useFakeTimers()
+    const timeoutControllers = installFakeAbortSignalTimeout()
+    const releaseStats: (() => void)[] = []
+    let returnMissing = false
+    statMock.mockImplementation(() =>
+      returnMissing
+        ? Promise.reject(fsError('ENOENT'))
+        : new Promise((resolve) => releaseStats.push(() => resolve({})))
+    )
+
+    try {
+      const firstPaths = ['/first-1', '/first-2', '/first-3', '/first-4']
+      const first = localWorktreePathsExistOrAreUnverifiable(firstPaths)
+      let firstSettled = false
+      void first.then(() => {
+        firstSettled = true
+      })
+      await vi.advanceTimersByTimeAsync(0)
+
+      expect(statMock).toHaveBeenCalledTimes(2)
+      await vi.advanceTimersByTimeAsync(LOCAL_WORKTREE_PATH_PROBE_TIMEOUT_MS - 1)
+      expect(firstSettled).toBe(false)
+      await vi.advanceTimersByTimeAsync(1)
+      await expect(first).resolves.toEqual(
+        new Map(firstPaths.map((pathValue) => [pathValue, true]))
+      )
+      expect(statMock).toHaveBeenCalledTimes(2)
+
+      const secondPaths = ['/second-1', '/second-2', '/second-3']
+      const second = localWorktreePathsExistOrAreUnverifiable(secondPaths)
+      await vi.advanceTimersByTimeAsync(LOCAL_WORKTREE_PATH_PROBE_TIMEOUT_MS)
+      await expect(second).resolves.toEqual(
+        new Map(secondPaths.map((pathValue) => [pathValue, true]))
+      )
+      expect(statMock).toHaveBeenCalledTimes(2)
+
+      returnMissing = true
+      releaseStats.splice(0).forEach((release) => release())
+      await vi.advanceTimersByTimeAsync(0)
+
+      await expect(localWorktreePathsExistOrAreUnverifiable(['/after-release'])).resolves.toEqual(
+        new Map([['/after-release', false]])
+      )
+      expect(statMock).toHaveBeenCalledTimes(3)
+    } finally {
+      timeoutControllers.forEach((controller) => controller.abort())
+      releaseStats.splice(0).forEach((release) => release())
+      await Promise.resolve()
+      await Promise.resolve()
+    }
+  })
+
+  it('settles promptly and fail closed when the caller aborts hung probes', async () => {
+    vi.useFakeTimers()
+    const timeoutControllers = installFakeAbortSignalTimeout()
+    const releaseStats: (() => void)[] = []
+    statMock.mockImplementation(
+      () => new Promise((resolve) => releaseStats.push(() => resolve({})))
+    )
+    const controller = new AbortController()
+    const paths = ['/abort-1', '/abort-2', '/abort-3']
+
+    try {
+      const result = localWorktreePathsExistOrAreUnverifiable(paths, {
+        signal: controller.signal
+      })
+      await vi.advanceTimersByTimeAsync(0)
+      expect(statMock).toHaveBeenCalledTimes(2)
+
+      controller.abort()
+
+      await expect(result).resolves.toEqual(new Map(paths.map((pathValue) => [pathValue, true])))
+      expect(vi.getTimerCount()).toBeGreaterThan(0)
+    } finally {
+      timeoutControllers.forEach((timeoutController) => timeoutController.abort())
+      releaseStats.splice(0).forEach((release) => release())
+      await Promise.resolve()
+      await Promise.resolve()
+    }
+  })
+})
diff --git a/src/main/local-worktree-path-presence.ts b/src/main/local-worktree-path-presence.ts
new file mode 100644
index 00000000000..673305d9513
--- /dev/null
+++ b/src/main/local-worktree-path-presence.ts
@@ -0,0 +1,72 @@
+import { stat } from 'node:fs/promises'
+import { mapWithConcurrency } from '../shared/map-with-concurrency'
+import { PrioritySemaphore } from '../shared/priority-semaphore'
+
+// Why: share one bound across polling callers so slow mounts cannot multiply libuv work.
+const LOCAL_WORKTREE_PATH_PROBE_CONCURRENCY = 2
+export const LOCAL_WORKTREE_PATH_PROBE_TIMEOUT_MS = 2_000
+const localWorktreePathProbeSemaphore = new PrioritySemaphore(LOCAL_WORKTREE_PATH_PROBE_CONCURRENCY)
+
+function probeDeadline(signal?: AbortSignal): AbortSignal {
+  const timeout = AbortSignal.timeout(LOCAL_WORKTREE_PATH_PROBE_TIMEOUT_MS)
+  return signal ? AbortSignal.any([signal, timeout]) : timeout
+}
+
+async function probeLocalWorktreePath(pathValue: string, signal: AbortSignal): Promise<boolean> {
+  let release: () => void
+  try {
+    release = await localWorktreePathProbeSemaphore.acquire(0, signal)
+  } catch {
+    return true
+  }
+  if (signal.aborted) {
+    release()
+    return true
+  }
+  const presence = stat(pathValue)
+    .then(
+      () => true,
+      (error) => {
+        const code = (error as NodeJS.ErrnoException | undefined)?.code
+        return code !== 'ENOENT' && code !== 'ENOTDIR'
+      }
+    )
+    .finally(release)
+  if (signal.aborted) {
+    return true
+  }
+  return new Promise((resolve) => {
+    const finish = (value: boolean): void => {
+      signal.removeEventListener('abort', onAbort)
+      resolve(value)
+    }
+    const onAbort = (): void => finish(true)
+    signal.addEventListener('abort', onAbort, { once: true })
+    void presence.then(finish)
+  })
+}
+
+/** A non-absence filesystem error cannot prove a native-local worktree disappeared. */
+export function localWorktreePathExistsOrIsUnverifiable(
+  pathValue: string,
+  options: { signal?: AbortSignal } = {}
+): Promise<boolean> {
+  return probeLocalWorktreePath(pathValue, probeDeadline(options.signal))
+}
+
+export async function localWorktreePathsExistOrAreUnverifiable(
+  pathValues: readonly string[],
+  options: { signal?: AbortSignal } = {}
+): Promise<ReadonlyMap<string, boolean>> {
+  const uniquePaths = [...new Set(pathValues)]
+  if (uniquePaths.length === 0) {
+    return new Map()
+  }
+  const signal = probeDeadline(options.signal)
+  const results = await mapWithConcurrency(
+    uniquePaths,
+    LOCAL_WORKTREE_PATH_PROBE_CONCURRENCY,
+    async (pathValue) => [pathValue, await probeLocalWorktreePath(pathValue, signal)] as const
+  )
+  return new Map(results)
+}
diff --git a/src/main/local-worktree-scan-generation.ts b/src/main/local-worktree-scan-generation.ts
new file mode 100644
index 00000000000..c8cc3bd0ff9
--- /dev/null
+++ b/src/main/local-worktree-scan-generation.ts
@@ -0,0 +1,25 @@
+const generationByRepoId = new Map<string, number>()
+let generationSequence = 0
+
+export function getLocalWorktreeScanGeneration(repoId: string): number {
+  const existing = generationByRepoId.get(repoId)
+  if (existing !== undefined) {
+    return existing
+  }
+  const generation = ++generationSequence
+  generationByRepoId.set(repoId, generation)
+  return generation
+}
+
+export function bumpLocalWorktreeScanGeneration(repoId: string): void {
+  generationByRepoId.set(repoId, ++generationSequence)
+}
+
+export function isLocalWorktreeScanGenerationCurrent(repoId: string, generation: number): boolean {
+  return getLocalWorktreeScanGeneration(repoId) === generation
+}
+
+export function resetLocalWorktreeScanGenerationsForTests(): void {
+  generationSequence += 1
+  generationByRepoId.clear()
+}
diff --git a/src/main/persistence-initial-load.test.ts b/src/main/persistence-initial-load.test.ts
index e1926a67877..6d0c0f11d5e 100644
--- a/src/main/persistence-initial-load.test.ts
+++ b/src/main/persistence-initial-load.test.ts
@@ -16,6 +16,10 @@ import {
   makeProjectHostSetup
 } from './persistence-test-harness'
 import { TEST_LEAF_1 } from './persistence-session-fixtures'
+import {
+  getLocalWorktreeScanGeneration,
+  isLocalWorktreeScanGenerationCurrent
+} from './local-worktree-scan-generation'
 
 // Stub the ~/.ssh/config parser so the SSH-import test drives the real Store with deterministic hosts, not the operator's actual ~/.ssh/config.
 const { loadUserSshConfigMock, sshConfigHostsToTargetsMock } = vi.hoisted(() => ({
@@ -304,12 +308,13 @@ describe('Store', () => {
 
   it('updates and persists a project Windows runtime preference', async () => {
     const project = makeProject({
-      id: 'project-1',
+      id: 'repo:r1',
       sourceRepoIds: ['r1'],
       localWindowsRuntimePreference: { kind: 'inherit-global' }
     })
     writeDataFile({
       ...getDefaultPersistedState(testState.dir),
+      repos: [makeRepo({ id: 'r1' })],
       projects: [project],
       projectHostSetups: [
         makeProjectHostSetup({
@@ -320,12 +325,14 @@ describe('Store', () => {
       ]
     })
     const store = await createStore()
+    const scanGeneration = getLocalWorktreeScanGeneration('r1')
 
-    const updated = store.updateProject('project-1', {
+    const updated = store.updateProject(project.id, {
       localWindowsRuntimePreference: { kind: 'wsl', distro: 'Ubuntu' }
     })
 
     expect(updated?.localWindowsRuntimePreference).toEqual({ kind: 'wsl', distro: 'Ubuntu' })
+    expect(isLocalWorktreeScanGenerationCurrent('r1', scanGeneration)).toBe(false)
     store.flush()
     const reloaded = await createStore()
     expect(reloaded.getProjects()[0]?.localWindowsRuntimePreference).toEqual({
diff --git a/src/main/persistence-repo-lifecycle.test.ts b/src/main/persistence-repo-lifecycle.test.ts
index 53b759a7d01..1653f78297e 100644
--- a/src/main/persistence-repo-lifecycle.test.ts
+++ b/src/main/persistence-repo-lifecycle.test.ts
@@ -14,6 +14,10 @@ import {
   makeTerminalTab,
   makeWorktreeLineage
 } from './persistence-test-harness'
+import {
+  getLocalWorktreeScanGeneration,
+  isLocalWorktreeScanGenerationCurrent
+} from './local-worktree-scan-generation'
 
 // Stub the ~/.ssh/config parser so the SSH-import test drives the real Store with deterministic hosts, not the operator's actual ~/.ssh/config.
 const { loadUserSshConfigMock, sshConfigHostsToTargetsMock } = vi.hoisted(() => ({
@@ -79,6 +83,23 @@ describe('Store', () => {
     expect(fetched!.gitUsername).toBe('')
   })
 
+  it('invalidates local scans across add, remove, and same-id re-add', async () => {
+    const store = await createStore()
+    const repoId = 'scan-lifecycle'
+    const beforeAdd = getLocalWorktreeScanGeneration(repoId)
+
+    store.addRepo(makeRepo({ id: repoId }))
+    expect(isLocalWorktreeScanGenerationCurrent(repoId, beforeAdd)).toBe(false)
+
+    const beforeRemove = getLocalWorktreeScanGeneration(repoId)
+    store.removeProject(repoId)
+    expect(isLocalWorktreeScanGenerationCurrent(repoId, beforeRemove)).toBe(false)
+
+    const beforeReAdd = getLocalWorktreeScanGeneration(repoId)
+    store.addRepo(makeRepo({ id: repoId, path: '/replacement' }))
+    expect(isLocalWorktreeScanGenerationCurrent(repoId, beforeReAdd)).toBe(false)
+  })
+
   it('setResolvedRepoGitUsername persists the enriched username for hydration', async () => {
     const store = await createStore()
     store.addRepo(makeRepo())
@@ -369,6 +390,24 @@ describe('Store', () => {
 
   // ── 6b. removeProjectForHost is host-scoped ───────────────────────────
 
+  it('invalidates local scans when one host registration is removed', async () => {
+    const store = await createStore()
+    store.addRepo(makeRepo({ id: 'shared', path: '/local/repo' }))
+    store.addRepo(
+      makeRepo({
+        id: 'shared',
+        path: '/remote/repo',
+        connectionId: 'ssh-old',
+        executionHostId: 'ssh:ssh-old'
+      })
+    )
+    const beforeRemove = getLocalWorktreeScanGeneration('shared')
+
+    store.removeProjectForHost('shared', 'ssh:ssh-old')
+
+    expect(isLocalWorktreeScanGenerationCurrent('shared', beforeRemove)).toBe(false)
+  })
+
   it('removeProjectForHost removes only the target host row for a shared repo id', async () => {
     const store = await createStore()
     // Same repo id on both local and an SSH host.
diff --git a/src/main/persistence-settings-update.test.ts b/src/main/persistence-settings-update.test.ts
index 330386a48a2..dc3a3c7ebb5 100644
--- a/src/main/persistence-settings-update.test.ts
+++ b/src/main/persistence-settings-update.test.ts
@@ -14,6 +14,10 @@ import {
   makeRepo,
   makeTerminalTab
 } from './persistence-test-harness'
+import {
+  getLocalWorktreeScanGeneration,
+  isLocalWorktreeScanGenerationCurrent
+} from './local-worktree-scan-generation'
 
 // Stub the ~/.ssh/config parser so the SSH-import test drives the real Store with deterministic hosts, not the operator's actual ~/.ssh/config.
 const { loadUserSshConfigMock, sshConfigHostsToTargetsMock } = vi.hoisted(() => ({
@@ -227,6 +231,21 @@ describe('Store', () => {
     expect(listener).not.toHaveBeenCalled()
   })
 
+  it('invalidates local worktree scans when the global Windows runtime changes', async () => {
+    writeDataFile({ repos: [makeRepo()] })
+    const store = await createStore()
+    const generation = getLocalWorktreeScanGeneration('r1')
+
+    store.updateSettings({ theme: 'dark' })
+    expect(isLocalWorktreeScanGenerationCurrent('r1', generation)).toBe(true)
+
+    store.updateSettings({
+      localWindowsRuntimeDefault: { kind: 'wsl', distro: 'Ubuntu' }
+    })
+
+    expect(isLocalWorktreeScanGenerationCurrent('r1', generation)).toBe(false)
+  })
+
   it('migrates missing terminal scrollback rows to the row default and writes back rows only', async () => {
     writeDataFile({ settings: {} })
 
diff --git a/src/main/persistence-update-repo.test.ts b/src/main/persistence-update-repo.test.ts
index d2266103615..a89378d6c71 100644
--- a/src/main/persistence-update-repo.test.ts
+++ b/src/main/persistence-update-repo.test.ts
@@ -11,6 +11,10 @@ import {
   makeProject,
   makeProjectHostSetup
 } from './persistence-test-harness'
+import {
+  getLocalWorktreeScanGeneration,
+  isLocalWorktreeScanGenerationCurrent
+} from './local-worktree-scan-generation'
 
 // Stub the ~/.ssh/config parser so the SSH-import test drives the real Store with deterministic hosts, not the operator's actual ~/.ssh/config.
 const { loadUserSshConfigMock, sshConfigHostsToTargetsMock } = vi.hoisted(() => ({
@@ -75,6 +79,25 @@ describe('Store', () => {
     expect(store.getRepo('r1')!.displayName).toBe('renamed')
   })
 
+  it('invalidates local worktree scans across a git-folder-git update round trip', async () => {
+    const store = await createStore()
+    store.addRepo(makeRepo({ id: 'scan-round-trip', kind: 'git' }))
+
+    const initialGeneration = getLocalWorktreeScanGeneration('scan-round-trip')
+    expect(isLocalWorktreeScanGenerationCurrent('scan-round-trip', initialGeneration)).toBe(true)
+
+    const folder = store.updateRepo('scan-round-trip', { kind: 'folder' })
+    expect(folder?.kind).toBe('folder')
+    expect(isLocalWorktreeScanGenerationCurrent('scan-round-trip', initialGeneration)).toBe(false)
+
+    const folderGeneration = getLocalWorktreeScanGeneration('scan-round-trip')
+    expect(isLocalWorktreeScanGenerationCurrent('scan-round-trip', folderGeneration)).toBe(true)
+
+    const git = store.updateRepo('scan-round-trip', { kind: 'git' })
+    expect(git?.kind).toBe('git')
+    expect(isLocalWorktreeScanGenerationCurrent('scan-round-trip', folderGeneration)).toBe(false)
+  })
+
   it('updateRepo targets one host when repo ids collide', async () => {
     const store = await createStore()
     store.addRepo(makeRepo({ id: 'shared', path: '/local/repo' }))
diff --git a/src/main/persistence/applying-settings/settings-update.ts b/src/main/persistence/applying-settings/settings-update.ts
index c4ded8da753..20614061bdd 100644
--- a/src/main/persistence/applying-settings/settings-update.ts
+++ b/src/main/persistence/applying-settings/settings-update.ts
@@ -41,6 +41,7 @@ import {
 
 export type SettingsMutationOperations = {
   state: PersistedState
+  bumpLocalWorktreeScanGeneration: (repoId: string) => void
   removeRetainedBlob: (
     slot: Parameters<ProtectedSecretPersistence['removeRetainedBlob']>[0]
   ) => void
@@ -242,6 +243,16 @@ export function updateSettings(
     }),
     ...(mergedTelemetry !== undefined ? { telemetry: mergedTelemetry } : {})
   }
+  if (
+    !Object.is(
+      previousSettings.localWindowsRuntimeDefault,
+      operations.state.settings.localWindowsRuntimeDefault
+    )
+  ) {
+    for (const repoId of new Set(operations.state.repos.map(({ id }) => id))) {
+      operations.bumpLocalWorktreeScanGeneration(repoId)
+    }
+  }
   operations.scheduleSave()
   const changedUpdates = {} as Partial<GlobalSettings> & Record<string, unknown>
   for (const key of Object.keys(sanitizedUpdates) as (keyof GlobalSettings)[]) {
diff --git a/src/main/persistence/loading-store/metadata-lineage-batch-pruning.test.ts b/src/main/persistence/loading-store/metadata-lineage-batch-pruning.test.ts
new file mode 100644
index 00000000000..9e7b71734b6
--- /dev/null
+++ b/src/main/persistence/loading-store/metadata-lineage-batch-pruning.test.ts
@@ -0,0 +1,64 @@
+import { describe, expect, it, vi } from 'vitest'
+import { getDefaultPersistedState } from '../../../shared/constants'
+import type { Repo } from '../../../shared/repo-types'
+import type { WorktreeMeta } from '../../../shared/worktree/meta-types'
+import type * as WriteSchedulingModule from './write-scheduling'
+import { MetadataLineageOperations } from './metadata-lineage-operations'
+
+const { scheduleSaveMock } = vi.hoisted(() => ({ scheduleSaveMock: vi.fn() }))
+
+vi.mock('./write-scheduling', async (importOriginal) => ({
+  ...(await importOriginal<typeof WriteSchedulingModule>()),
+  scheduleSave: scheduleSaveMock
+}))
+
+const REPO: Repo = {
+  id: 'repo-1',
+  path: '/workspace/repo',
+  displayName: 'repo',
+  badgeColor: '#000',
+  addedAt: 0
+}
+
+function makeMeta(worktreeId: string): WorktreeMeta {
+  return {
+    instanceId: `instance-${worktreeId}`,
+    hostId: 'local',
+    displayName: worktreeId,
+    comment: '',
+    linkedIssue: null,
+    linkedPR: null,
+    linkedLinearIssue: null,
+    isArchived: false,
+    isUnread: false,
+    isPinned: false,
+    sortOrder: 0,
+    lastActivityAt: 0
+  }
+}
+
+describe('MetadataLineageOperations batch metadata pruning', () => {
+  it('schedules one save for thousands of removals and none for a no-op retry', () => {
+    const state = getDefaultPersistedState('/home/test')
+    state.repos = [REPO]
+    const staleIds = Array.from(
+      { length: 2_709 },
+      (_, index) => `${REPO.id}::/workspace/stale-${index}`
+    )
+    for (const worktreeId of staleIds) {
+      state.worktreeMeta[worktreeId] = makeMeta(worktreeId)
+    }
+    const operations = new MetadataLineageOperations({ state } as never, {} as never, {} as never)
+    const scan = operations.captureNativeLocalWorktreeMetadataScanExpectation(REPO)
+
+    expect(
+      operations.pruneSessionlessMissingLocalWorktreeMetadataForRepo(scan, scan.metadata)
+    ).toHaveLength(staleIds.length)
+    expect(scheduleSaveMock).toHaveBeenCalledTimes(1)
+
+    expect(
+      operations.pruneSessionlessMissingLocalWorktreeMetadataForRepo(scan, scan.metadata)
+    ).toEqual([])
+    expect(scheduleSaveMock).toHaveBeenCalledTimes(1)
+  })
+})
diff --git a/src/main/persistence/loading-store/metadata-lineage-operations.ts b/src/main/persistence/loading-store/metadata-lineage-operations.ts
index f12af5d1583..7d4867ce476 100644
--- a/src/main/persistence/loading-store/metadata-lineage-operations.ts
+++ b/src/main/persistence/loading-store/metadata-lineage-operations.ts
@@ -1,6 +1,7 @@
 import type { WorkspaceKey } from '../../../shared/folder-workspace-types'
 import type { WorkspaceLineage, WorktreeLineage } from '../../../shared/worktree/lineage-types'
 import type { WorktreeMeta } from '../../../shared/worktree/meta-types'
+import type { Repo } from '../../../shared/repo-types'
 import { LOCAL_EXECUTION_HOST_ID, type ExecutionHostId } from '../../../shared/execution-host'
 import { getRepoIdFromWorktreeId } from '../../../shared/worktree/id'
 import { hasWorktreeRemovalRepoOwnerOnOtherHost } from '../../worktree-removal-repo-owner'
@@ -28,6 +29,12 @@ import {
   setWorktreeMetaForHost as setWorktreeMetaForHostOperation
 } from './worktree-identity-metadata'
 import { mergeWorktreeMetaForWrite } from './worktree-meta-write-normalization'
+import {
+  captureNativeLocalWorktreeMetadataScanExpectation as captureNativeLocalWorktreeMetadataScanExpectationOperation,
+  pruneSessionlessMissingLocalWorktreeMetadataForRepo as pruneSessionlessMissingLocalWorktreeMetadataForRepoOperation,
+  type LocalWorktreeMetadataPruneExpectation,
+  type NativeLocalWorktreeMetadataScanExpectation
+} from '../tracking-repos/missing-local-worktree-metadata-pruning'
 
 type MetadataLineageOperationsRuntime = Pick<StoreRuntimeState, 'state'>
 
@@ -89,6 +96,15 @@ export class MetadataLineageOperations {
     )
   }
 
+  captureNativeLocalWorktreeMetadataScanExpectation(
+    repo: Repo
+  ): NativeLocalWorktreeMetadataScanExpectation {
+    return captureNativeLocalWorktreeMetadataScanExpectationOperation(
+      this[metadataLineageOperationsContext].runtime.state,
+      repo
+    )
+  }
+
   setWorktreeMeta(worktreeId: string, meta: Partial<WorktreeMeta>): WorktreeMeta {
     const state = this[metadataLineageOperationsContext].runtime.state
     const stored = state.worktreeMeta[worktreeId]
@@ -184,6 +200,21 @@ export class MetadataLineageOperations {
     scheduleSave(this[metadataLineageOperationsContext].scheduling)
   }
 
+  pruneSessionlessMissingLocalWorktreeMetadataForRepo(
+    scan: NativeLocalWorktreeMetadataScanExpectation,
+    missingMetadata: readonly LocalWorktreeMetadataPruneExpectation[]
+  ): string[] {
+    const removed = pruneSessionlessMissingLocalWorktreeMetadataForRepoOperation(
+      this[metadataLineageOperationsContext].runtime.state,
+      scan,
+      missingMetadata
+    )
+    if (removed.length > 0) {
+      scheduleSave(this[metadataLineageOperationsContext].scheduling)
+    }
+    return removed
+  }
+
   getWorktreeLineage(worktreeId: string): WorktreeLineage | undefined {
     return this[metadataLineageOperationsContext].runtime.state.worktreeLineageById[worktreeId]
   }
diff --git a/src/main/persistence/loading-store/profile-preferences.ts b/src/main/persistence/loading-store/profile-preferences.ts
index 228229d2584..0ec4e383c34 100644
--- a/src/main/persistence/loading-store/profile-preferences.ts
+++ b/src/main/persistence/loading-store/profile-preferences.ts
@@ -17,6 +17,7 @@ import {
 import type { StoreRuntimeState } from './store-runtime-state'
 import type { WriteSchedulingOperations } from './write-scheduling'
 import { scheduleSave } from './write-scheduling'
+import { bumpLocalWorktreeScanGeneration } from '../../local-worktree-scan-generation'
 
 type ProfilePreferencesRuntime = Pick<
   StoreRuntimeState,
@@ -155,6 +156,7 @@ export function getSettingsMutationOperations(
 ): SettingsMutationOperations {
   return {
     state: owner[profilePreferencesContext].runtime.state,
+    bumpLocalWorktreeScanGeneration,
     removeRetainedBlob: (slot) =>
       owner[profilePreferencesContext].runtime.protectedSecrets.removeRetainedBlob(slot),
     scheduleSave: () => scheduleSave(owner[profilePreferencesContext].scheduling),
diff --git a/src/main/persistence/loading-store/project-collection-operations.ts b/src/main/persistence/loading-store/project-collection-operations.ts
index e7100478037..ecb1130072f 100644
--- a/src/main/persistence/loading-store/project-collection-operations.ts
+++ b/src/main/persistence/loading-store/project-collection-operations.ts
@@ -28,6 +28,7 @@ import {
 } from './repo-lifecycle-operations'
 import { scheduleSave } from './write-scheduling'
 import { removeWorkspaceLineageForFolderParent } from './metadata-lineage-operations'
+import { bumpLocalWorktreeScanGeneration } from '../../local-worktree-scan-generation'
 
 type ProjectCollectionOperationsRuntime = Pick<
   StoreRuntimeState,
@@ -159,6 +160,7 @@ export function getProjectHostOperations(
     new ProjectHostPersistenceOperations({
       state: owner[projectCollectionOperationsContext].runtime.state,
       gitUsernameCache: owner[projectCollectionOperationsContext].runtime.gitUsernameCache,
+      bumpLocalWorktreeScanGeneration,
       hydrateRepo: (repo) => hydrateRepo(owner[projectCollectionOperationsContext].repos, repo),
       updateRepoBackedProjectHostSetup: (setup, repo, updates) =>
         updateRepoBackedProjectHostSetup(
diff --git a/src/main/persistence/loading-store/repo-lifecycle-operations.ts b/src/main/persistence/loading-store/repo-lifecycle-operations.ts
index bdd3718d9a6..095090ee1ca 100644
--- a/src/main/persistence/loading-store/repo-lifecycle-operations.ts
+++ b/src/main/persistence/loading-store/repo-lifecycle-operations.ts
@@ -15,6 +15,7 @@ import { pruneWorktreeStateForRepo as pruneWorktreeStateForRepoOperation } from
 import { hydrateRepo as hydrateRepoOperation } from '../tracking-repos/repo-hydration'
 import { RepoUpdatePersistenceOperations } from '../tracking-repos/repo-update-operations'
 import { ProjectHostSetupPersistenceOperations } from '../tracking-repos/project-host-setup-update'
+import { bumpLocalWorktreeScanGeneration } from '../../local-worktree-scan-generation'
 
 import type { StoreRuntimeState } from './store-runtime-state'
 import type { WriteSchedulingOperations } from './write-scheduling'
@@ -43,6 +44,7 @@ export class RepoLifecycleOperations {
   }
 
   addRepo(repo: Repo): void {
+    bumpLocalWorktreeScanGeneration(repo.id)
     getRepoOrderOperations(this).addRepo(repo)
   }
 
@@ -55,9 +57,15 @@ export class RepoLifecycleOperations {
   }
 
   removeProject(id: string): void {
+    const repoRemoved = this[repoLifecycleOperationsContext].runtime.state.repos.some(
+      (repo) => repo.id === id
+    )
     this[repoLifecycleOperationsContext].runtime.state.repos = this[
       repoLifecycleOperationsContext
     ].runtime.state.repos.filter((r) => r.id !== id)
+    if (repoRemoved) {
+      bumpLocalWorktreeScanGeneration(id)
+    }
     syncProjectHostSetupCompatibilityState(this)
     // Why: presets are repo-scoped and unreachable once the repo is gone, so drop them with it.
     delete this[repoLifecycleOperationsContext].runtime.state.sparsePresetsByRepo[id]
@@ -77,9 +85,15 @@ export class RepoLifecycleOperations {
   }
 
   removeProjectForHost(id: string, hostId: ExecutionHostId): void {
+    const repoRemoved = this[repoLifecycleOperationsContext].runtime.state.repos.some(
+      (repo) => repo.id === id && getRepoExecutionHostId(repo) === hostId
+    )
     this[repoLifecycleOperationsContext].runtime.state.repos = this[
       repoLifecycleOperationsContext
     ].runtime.state.repos.filter((r) => !(r.id === id && getRepoExecutionHostId(r) === hostId))
+    if (repoRemoved) {
+      bumpLocalWorktreeScanGeneration(id)
+    }
     const idStillPresent = this[repoLifecycleOperationsContext].runtime.state.repos.some(
       (r) => r.id === id
     )
@@ -204,6 +218,7 @@ export function getRepoUpdateOperations(
   owner[repoLifecycleOperationsContext].runtime.repoUpdateOperations ??=
     new RepoUpdatePersistenceOperations({
       state: owner[repoLifecycleOperationsContext].runtime.state,
+      bumpLocalWorktreeScanGeneration,
       syncProjectHostSetupCompatibilityState: () => syncProjectHostSetupCompatibilityState(owner),
       scheduleSave: () => scheduleSave(owner[repoLifecycleOperationsContext].scheduling),
       hydrateRepo: (repo) => hydrateRepo(owner, repo)
diff --git a/src/main/persistence/loading-store/worktree-identity-metadata.ts b/src/main/persistence/loading-store/worktree-identity-metadata.ts
index 396c2ffae85..21fea4ac15c 100644
--- a/src/main/persistence/loading-store/worktree-identity-metadata.ts
+++ b/src/main/persistence/loading-store/worktree-identity-metadata.ts
@@ -36,11 +36,18 @@ function resolveAliasIdentityKey(state: PersistedState, alias: string): string |
 }
 
 /** Drop identity metadata no alias points at any more. */
-export function pruneUnreferencedWorktreeIdentityMeta(state: PersistedState): boolean {
+export function pruneUnreferencedWorktreeIdentityMeta(
+  state: PersistedState,
+  candidates?: ReadonlySet<string>
+): boolean {
   const referenced = new Set(Object.values(state.worktreeIdentityAliases ?? {}).flat())
   let changed = false
-  for (const identityKey of Object.keys(state.worktreeMetaByIdentity ?? {})) {
-    if (!referenced.has(identityKey)) {
+  const identityKeys = candidates ?? Object.keys(state.worktreeMetaByIdentity ?? {})
+  for (const identityKey of identityKeys) {
+    if (
+      Object.hasOwn(state.worktreeMetaByIdentity ?? {}, identityKey) &&
+      !referenced.has(identityKey)
+    ) {
       delete state.worktreeMetaByIdentity?.[identityKey]
       changed = true
     }
diff --git a/src/main/persistence/restoring-sessions/session-worktree-ownership.test.ts b/src/main/persistence/restoring-sessions/session-worktree-ownership.test.ts
new file mode 100644
index 00000000000..1e84cf4c506
--- /dev/null
+++ b/src/main/persistence/restoring-sessions/session-worktree-ownership.test.ts
@@ -0,0 +1,166 @@
+import { describe, expect, it } from 'vitest'
+import { getDefaultPersistedState, getDefaultWorkspaceSession } from '../../../shared/constants'
+import type { WorkspaceSessionState } from '../../../shared/workspace-session-state-types'
+import { worktreeWorkspaceKey } from '../../../shared/workspace-scope'
+import {
+  collectPersistedSessionWorktreeOwners,
+  collectWorkspaceSessionWorktreeOwners
+} from './session-worktree-ownership'
+
+const TARGET = 'repo-1::/workspace/target'
+const OTHER = 'repo-1::/workspace/other'
+
+function sessionWith(field: keyof WorkspaceSessionState, value: unknown): WorkspaceSessionState {
+  return { ...getDefaultWorkspaceSession(), [field]: value } as WorkspaceSessionState
+}
+
+function collected(session: WorkspaceSessionState): string[] {
+  return [...collectWorkspaceSessionWorktreeOwners(session, new Set([TARGET]))]
+}
+
+const OWNER_KEYED_FIELD_VALUES = [
+  ['tabsByWorktree', []],
+  ['openFilesByWorktree', []],
+  ['activeFileIdByWorktree', null],
+  ['browserTabsByWorktree', []],
+  ['activeBrowserTabIdByWorktree', null],
+  ['clientHostedBrowserPagesByWorktree', []],
+  ['activeTabTypeByWorktree', 'terminal'],
+  ['activeTabIdByWorktree', null],
+  ['unifiedTabs', []],
+  ['tabGroups', []],
+  ['tabGroupLayouts', { type: 'leaf', groupId: 'group-1' }],
+  ['activeGroupIdByWorktree', 'group-1'],
+  ['lastVisitedAtByWorktreeId', 0],
+  ['defaultTerminalTabsAppliedByWorktreeId', true]
+] as const satisfies readonly [keyof WorkspaceSessionState, unknown][]
+
+describe('workspace session worktree ownership', () => {
+  it.each(OWNER_KEYED_FIELD_VALUES)(
+    'treats a key in %s as ownership even when its bucket is empty or null',
+    (field, value) => {
+      expect(collected(sessionWith(field, { [TARGET]: value }))).toEqual([TARGET])
+    }
+  )
+
+  it.each([
+    ['active worktree', sessionWith('activeWorktreeId', TARGET)],
+    ['active workspace', sessionWith('activeWorkspaceKey', worktreeWorkspaceKey(TARGET))],
+    ['shutdown owner', sessionWith('activeWorktreeIdsOnShutdown', [TARGET])],
+    [
+      'host-qualified recency owner',
+      sessionWith('lastVisitedAtByWorktreeId', { [`ssh:builder|${TARGET}`]: 1 })
+    ]
+  ])('collects the %s', (_label, session) => {
+    expect(collected(session)).toEqual([TARGET])
+  })
+
+  it.each([
+    ['terminal tab', 'tabsByWorktree', { [OTHER]: [{ worktreeId: TARGET }] }],
+    ['open file', 'openFilesByWorktree', { [OTHER]: [{ worktreeId: TARGET }] }],
+    ['unified tab', 'unifiedTabs', { [OTHER]: [{ worktreeId: TARGET }] }],
+    ['tab group', 'tabGroups', { [OTHER]: [{ worktreeId: TARGET }] }],
+    ['browser workspace', 'browserTabsByWorktree', { [OTHER]: [{ worktreeId: TARGET }] }],
+    [
+      'browser workspace document',
+      'browserTabsByWorktree',
+      { [OTHER]: [{ worktreeId: OTHER, docLocation: { worktreeId: TARGET } }] }
+    ],
+    ['browser page', 'browserPagesByWorkspace', { page: [{ worktreeId: TARGET }] }],
+    [
+      'browser page document',
+      'browserPagesByWorkspace',
+      { page: [{ worktreeId: OTHER, docLocation: { worktreeId: TARGET } }] }
+    ],
+    [
+      'browser close intent',
+      'clientHostedBrowserCloseIntentsByEnvironment',
+      { environment: [{ worktreeId: TARGET }] }
+    ],
+    ['sleeping agent', 'sleepingAgentSessionsByPaneKey', { pane: { worktreeId: TARGET } }],
+    ['terminal tombstone', 'terminalSurfaceTombstonesByPaneKey', { pane: { worktreeId: TARGET } }],
+    [
+      'closed-terminal tombstone',
+      'closedTerminalTabTombstonesByTabId',
+      { tab: { worktreeId: TARGET } }
+    ]
+  ] as const)(
+    'collects a %s value even when its enclosing key names something else',
+    (_label, field, value) => {
+      expect(collected(sessionWith(field, value))).toEqual([TARGET])
+    }
+  )
+
+  it('collects ownership from every persisted host partition', () => {
+    const state = getDefaultPersistedState('/home/test')
+    state.workspaceSessionsByHostId = {
+      'ssh:builder': sessionWith('tabsByWorktree', { [TARGET]: [] }),
+      'runtime:environment': sessionWith('activeWorktreeIdsOnShutdown', [OTHER])
+    }
+
+    expect(
+      [...collectPersistedSessionWorktreeOwners(state, new Set([TARGET, OTHER]))].sort()
+    ).toEqual([OTHER, TARGET])
+  })
+
+  it('prefers an exact candidate id over workspace-key prefix parsing', () => {
+    const prefixedId = 'folder::/workspace/target'
+    const session = sessionWith('tabsByWorktree', { [prefixedId]: [] })
+
+    expect([...collectWorkspaceSessionWorktreeOwners(session, new Set([prefixedId]))]).toEqual([
+      prefixedId
+    ])
+  })
+
+  it('matches canonically equivalent Unicode worktree owners', () => {
+    const candidateId = 'repo-1::/workspace/Café'.normalize('NFC')
+    const ownerId = candidateId.normalize('NFD')
+    const session = sessionWith('activeWorktreeId', ownerId)
+
+    expect([...collectWorkspaceSessionWorktreeOwners(session, new Set([candidateId]))]).toEqual([
+      candidateId
+    ])
+  })
+
+  it('matches Windows worktree owners across drive case and slash spelling', () => {
+    const candidateId = 'repo-1::D:/Agentic/game2'
+    const session = sessionWith('activeWorktreeId', 'repo-1::d:\\agentic\\game2')
+
+    expect([...collectWorkspaceSessionWorktreeOwners(session, new Set([candidateId]))]).toEqual([
+      candidateId
+    ])
+  })
+
+  it('matches macOS /private/tmp session owners to /tmp metadata', () => {
+    const candidateId = 'repo-1::/private/tmp/orca/target'
+    const session = sessionWith('activeWorktreeId', 'repo-1::/tmp/orca/target')
+
+    expect([
+      ...collectWorkspaceSessionWorktreeOwners(session, new Set([candidateId]), 'darwin')
+    ]).toEqual([candidateId])
+  })
+
+  it('preserves every candidate that shares an owner comparison key', () => {
+    const nfcId = 'repo-1::/workspace/Café'.normalize('NFC')
+    const nfdId = nfcId.normalize('NFD')
+    const session = sessionWith('activeWorktreeId', nfcId)
+
+    expect(
+      [...collectWorkspaceSessionWorktreeOwners(session, new Set([nfcId, nfdId]))].sort()
+    ).toEqual([nfcId, nfdId].sort())
+  })
+
+  it('ignores fields whose keys cannot identify a worktree owner', () => {
+    const session = {
+      ...getDefaultWorkspaceSession(),
+      activeRepoId: TARGET,
+      activeTabId: TARGET,
+      terminalLayoutsByTabId: { [TARGET]: { root: null } },
+      remoteSessionIdsByTabId: { [TARGET]: TARGET },
+      terminalPtyIncarnationsByPaneKey: { [TARGET]: TARGET },
+      terminalTopologyRevisionByRepoId: { [TARGET]: 1 }
+    } as unknown as WorkspaceSessionState
+
+    expect(collected(session)).toEqual([])
+  })
+})
diff --git a/src/main/persistence/restoring-sessions/session-worktree-ownership.ts b/src/main/persistence/restoring-sessions/session-worktree-ownership.ts
new file mode 100644
index 00000000000..dc572e79278
--- /dev/null
+++ b/src/main/persistence/restoring-sessions/session-worktree-ownership.ts
@@ -0,0 +1,246 @@
+import type { PersistedState } from '../../../shared/persisted-state-types'
+import type { WorkspaceSessionState } from '../../../shared/workspace-session-state-types'
+import { parseWorkspaceKey } from '../../../shared/workspace-scope'
+import {
+  getWorktreeIdFromHostIdentity,
+  isWorktreeHostIdentity
+} from '../../../shared/worktree/host-qualified-identity'
+import { worktreeRetentionIdComparisonKey } from '../../worktree-retention-path-comparison'
+
+type WorkspaceSessionWorktreeReferenceKind =
+  | 'none'
+  | 'direct'
+  | 'owner-keyed'
+  | 'owner-keyed-row-arrays'
+  | 'owner-keyed-browser-row-arrays'
+  | 'worktree-id-array'
+  | 'row-record'
+  | 'row-arrays'
+  | 'browser-row-arrays'
+
+/** Every persisted session field must state how, if at all, it can name a worktree owner. */
+export const WORKSPACE_SESSION_WORKTREE_REFERENCE_KIND = {
+  activeRepoId: 'none',
+  activeWorkspaceKey: 'direct',
+  activeWorkspaceExecutionHostId: 'none',
+  activeWorktreeId: 'direct',
+  activeTabId: 'none',
+  tabsByWorktree: 'owner-keyed-row-arrays',
+  terminalLayoutsByTabId: 'none',
+  activeWorktreeIdsOnShutdown: 'worktree-id-array',
+  openFilesByWorktree: 'owner-keyed-row-arrays',
+  activeFileIdByWorktree: 'owner-keyed',
+  markdownFrontmatterVisible: 'none',
+  browserTabsByWorktree: 'owner-keyed-browser-row-arrays',
+  browserPagesByWorkspace: 'browser-row-arrays',
+  activeBrowserTabIdByWorktree: 'owner-keyed',
+  clientHostedBrowserPagesByWorktree: 'owner-keyed',
+  clientHostedBrowserCloseIntentsByEnvironment: 'row-arrays',
+  activeTabTypeByWorktree: 'owner-keyed',
+  browserUrlHistory: 'none',
+  activeTabIdByWorktree: 'owner-keyed',
+  unifiedTabs: 'owner-keyed-row-arrays',
+  tabGroups: 'owner-keyed-row-arrays',
+  tabGroupLayouts: 'owner-keyed',
+  activeGroupIdByWorktree: 'owner-keyed',
+  activeConnectionIdsAtShutdown: 'none',
+  remoteSessionIdsByTabId: 'none',
+  lastVisitedAtByWorktreeId: 'owner-keyed',
+  defaultTerminalTabsAppliedByWorktreeId: 'owner-keyed',
+  sleepingAgentSessionsByPaneKey: 'row-record',
+  terminalPtyIncarnationsByPaneKey: 'none',
+  terminalTopologyRevisionByRepoId: 'none',
+  terminalSurfaceTombstonesByPaneKey: 'row-record',
+  closedTerminalTabTombstonesByTabId: 'row-record'
+} as const satisfies Record<keyof WorkspaceSessionState, WorkspaceSessionWorktreeReferenceKind>
+
+type WorktreeRow = { worktreeId?: string | null }
+type BrowserWorktreeRow = WorktreeRow & {
+  docLocation?: { worktreeId?: string | null } | null
+}
+
+export type WorktreeOwnerCandidateCollector = Readonly<{
+  owners: Set<string>
+  addOwner: (ownerKey: string | null | undefined) => void
+}>
+
+export function getPersistedWorktreeOwnerId(ownerKey: string | null | undefined): string | null {
+  if (!ownerKey) {
+    return null
+  }
+  if (isWorktreeHostIdentity(ownerKey)) {
+    return getWorktreeIdFromHostIdentity(ownerKey) || null
+  }
+  const scope = parseWorkspaceKey(ownerKey)
+  if (scope?.type === 'folder') {
+    return null
+  }
+  return scope?.type === 'worktree' ? scope.worktreeId : ownerKey
+}
+
+export function createWorktreeOwnerCandidateCollector(
+  candidateIds: ReadonlySet<string>,
+  platform: NodeJS.Platform = process.platform,
+  owners: Set<string> = new Set<string>()
+): WorktreeOwnerCandidateCollector {
+  const candidateIdsByComparisonKey = new Map<string, string[]>()
+  for (const candidateId of candidateIds) {
+    const comparisonKey = worktreeRetentionIdComparisonKey(candidateId, platform)
+    if (!comparisonKey) {
+      continue
+    }
+    const matches = candidateIdsByComparisonKey.get(comparisonKey) ?? []
+    matches.push(candidateId)
+    candidateIdsByComparisonKey.set(comparisonKey, matches)
+  }
+  return {
+    owners,
+    addOwner: (ownerKey) => {
+      const worktreeId =
+        ownerKey && candidateIds.has(ownerKey) ? ownerKey : getPersistedWorktreeOwnerId(ownerKey)
+      if (!worktreeId) {
+        return
+      }
+      const comparisonKey = worktreeRetentionIdComparisonKey(worktreeId, platform)
+      const equivalentCandidates = comparisonKey
+        ? candidateIdsByComparisonKey.get(comparisonKey)
+        : undefined
+      if (equivalentCandidates) {
+        for (const candidateId of equivalentCandidates) {
+          owners.add(candidateId)
+        }
+      } else if (candidateIds.has(worktreeId)) {
+        owners.add(worktreeId)
+      }
+    }
+  }
+}
+
+function collectRecordKeys(
+  value: unknown,
+  add: (ownerKey: string | null | undefined) => void
+): void {
+  for (const ownerKey of Object.keys((value ?? {}) as Record<string, unknown>)) {
+    add(ownerKey)
+  }
+}
+
+function collectWorktreeRows(
+  rows: unknown,
+  add: (ownerKey: string | null | undefined) => void
+): void {
+  if (!Array.isArray(rows)) {
+    return
+  }
+  for (const row of rows as WorktreeRow[]) {
+    add(row?.worktreeId)
+  }
+}
+
+function collectBrowserRows(
+  rows: unknown,
+  add: (ownerKey: string | null | undefined) => void
+): void {
+  if (!Array.isArray(rows)) {
+    return
+  }
+  for (const row of rows as BrowserWorktreeRow[]) {
+    add(row?.worktreeId)
+    add(row?.docLocation?.worktreeId)
+  }
+}
+
+function collectSessionFieldOwners(
+  value: unknown,
+  kind: WorkspaceSessionWorktreeReferenceKind,
+  add: (ownerKey: string | null | undefined) => void
+): void {
+  switch (kind) {
+    case 'none':
+      return
+    case 'direct':
+      add(typeof value === 'string' ? value : null)
+      return
+    case 'owner-keyed':
+      collectRecordKeys(value, add)
+      return
+    case 'owner-keyed-row-arrays':
+    case 'owner-keyed-browser-row-arrays':
+      for (const [ownerKey, rows] of Object.entries((value ?? {}) as Record<string, unknown>)) {
+        add(ownerKey)
+        if (kind === 'owner-keyed-browser-row-arrays') {
+          collectBrowserRows(rows, add)
+        } else {
+          collectWorktreeRows(rows, add)
+        }
+      }
+      return
+    case 'worktree-id-array':
+      for (const ownerKey of (value ?? []) as string[]) {
+        add(ownerKey)
+      }
+      return
+    case 'row-record':
+      for (const row of Object.values((value ?? {}) as Record<string, WorktreeRow>)) {
+        add(row?.worktreeId)
+      }
+      return
+    case 'row-arrays':
+    case 'browser-row-arrays':
+      for (const rows of Object.values((value ?? {}) as Record<string, unknown>)) {
+        if (kind === 'browser-row-arrays') {
+          collectBrowserRows(rows, add)
+        } else {
+          collectWorktreeRows(rows, add)
+        }
+      }
+  }
+}
+
+export function collectWorkspaceSessionWorktreeOwners(
+  session: WorkspaceSessionState,
+  candidateIds: ReadonlySet<string>,
+  platform: NodeJS.Platform = process.platform,
+  owners: Set<string> = new Set<string>()
+): Set<string> {
+  const collector = createWorktreeOwnerCandidateCollector(candidateIds, platform, owners)
+  addWorkspaceSessionWorktreeOwners(session, collector)
+  return owners
+}
+
+function addWorkspaceSessionWorktreeOwners(
+  session: WorkspaceSessionState,
+  collector: WorktreeOwnerCandidateCollector
+): void {
+  for (const field of Object.keys(
+    WORKSPACE_SESSION_WORKTREE_REFERENCE_KIND
+  ) as (keyof WorkspaceSessionState)[]) {
+    collectSessionFieldOwners(
+      session[field],
+      WORKSPACE_SESSION_WORKTREE_REFERENCE_KIND[field],
+      collector.addOwner
+    )
+  }
+}
+
+export function addPersistedSessionWorktreeOwners(
+  state: Pick<PersistedState, 'workspaceSession' | 'workspaceSessionsByHostId'>,
+  collector: WorktreeOwnerCandidateCollector
+): void {
+  addWorkspaceSessionWorktreeOwners(state.workspaceSession, collector)
+  for (const session of Object.values(state.workspaceSessionsByHostId ?? {})) {
+    if (session) {
+      addWorkspaceSessionWorktreeOwners(session, collector)
+    }
+  }
+}
+
+export function collectPersistedSessionWorktreeOwners(
+  state: Pick<PersistedState, 'workspaceSession' | 'workspaceSessionsByHostId'>,
+  candidateIds: ReadonlySet<string>,
+  platform: NodeJS.Platform = process.platform
+): Set<string> {
+  const collector = createWorktreeOwnerCandidateCollector(candidateIds, platform)
+  addPersistedSessionWorktreeOwners(state, collector)
+  return collector.owners
+}
diff --git a/src/main/persistence/tracking-repos/local-worktree-metadata-batch-pruning.bench.test.ts b/src/main/persistence/tracking-repos/local-worktree-metadata-batch-pruning.bench.test.ts
new file mode 100644
index 00000000000..0f5a85a80c6
--- /dev/null
+++ b/src/main/persistence/tracking-repos/local-worktree-metadata-batch-pruning.bench.test.ts
@@ -0,0 +1,106 @@
+// Opt in: ORCA_LOCAL_METADATA_PRUNE_BENCH=1 pnpm test src/main/persistence/tracking-repos/local-worktree-metadata-batch-pruning.bench.test.ts
+import { performance } from 'node:perf_hooks'
+import { describe, expect, it, vi } from 'vitest'
+import { getDefaultPersistedState } from '../../../shared/constants'
+import type { PersistedState } from '../../../shared/persisted-state-types'
+import type { Repo } from '../../../shared/repo-types'
+import type { WorktreeMeta } from '../../../shared/worktree/meta-types'
+import { removeWorkspaceSessionOwner } from '../restoring-sessions/session-owner-removal'
+import {
+  pruneUnreferencedWorktreeIdentityMeta,
+  removeWorktreeMetadataForHost
+} from '../loading-store/worktree-identity-metadata'
+import {
+  captureNativeLocalWorktreeMetadataScanExpectation,
+  pruneSessionlessMissingLocalWorktreeMetadataForRepo
+} from './missing-local-worktree-metadata-pruning'
+
+const describeBench = process.env.ORCA_LOCAL_METADATA_PRUNE_BENCH ? describe : describe.skip
+const ROW_COUNT = 2_709
+const REPO: Repo = {
+  id: 'repo-1',
+  path: '/workspace/repo',
+  displayName: 'repo',
+  badgeColor: '#000',
+  addedAt: 0
+}
+
+function makeMeta(index: number): WorktreeMeta {
+  return {
+    instanceId: `instance-${index}`,
+    hostId: 'local',
+    displayName: `stale-${index}`,
+    comment: '',
+    linkedIssue: null,
+    linkedPR: null,
+    linkedLinearIssue: null,
+    isArchived: false,
+    isUnread: false,
+    isPinned: false,
+    sortOrder: index,
+    lastActivityAt: 0
+  }
+}
+
+function makeState(): { state: PersistedState; staleIds: string[] } {
+  const state = getDefaultPersistedState('/home/test')
+  state.repos = [REPO]
+  state.worktreeMetaByIdentity = {}
+  state.worktreeIdentityAliases = {}
+  const staleIds = Array.from(
+    { length: ROW_COUNT },
+    (_, index) => `${REPO.id}::/workspace/stale-${index}`
+  )
+  for (const [index, worktreeId] of staleIds.entries()) {
+    const meta = makeMeta(index)
+    const identityKey = `identity-${index}`
+    state.worktreeMeta[worktreeId] = meta
+    state.worktreeMetaByIdentity[identityKey] = meta
+    state.worktreeIdentityAliases[`local|${worktreeId}`] = [identityKey]
+  }
+  return { state, staleIds }
+}
+
+describeBench('authoritative local metadata batch pruning', () => {
+  it('measures the reported 2,709-row sequential and batch shapes', () => {
+    const legacy = makeState()
+    const batch = makeState()
+    const cloneSpy = vi.spyOn(globalThis, 'structuredClone')
+    const legacyStartedAt = performance.now()
+    for (const worktreeId of legacy.staleIds) {
+      removeWorktreeMetadataForHost(legacy.state, worktreeId, undefined)
+      delete legacy.state.worktreeMeta[worktreeId]
+      legacy.state.workspaceSession = removeWorkspaceSessionOwner(
+        legacy.state.workspaceSession,
+        worktreeId
+      )!
+    }
+    pruneUnreferencedWorktreeIdentityMeta(legacy.state)
+    const legacyMs = performance.now() - legacyStartedAt
+    const legacySessionClones = cloneSpy.mock.calls.length
+    cloneSpy.mockClear()
+
+    const batchStartedAt = performance.now()
+    const scan = captureNativeLocalWorktreeMetadataScanExpectation(batch.state, REPO)
+    const removed = pruneSessionlessMissingLocalWorktreeMetadataForRepo(
+      batch.state,
+      scan,
+      scan.metadata
+    )
+    const batchMs = performance.now() - batchStartedAt
+    const batchSessionClones = cloneSpy.mock.calls.length
+    cloneSpy.mockRestore()
+
+    expect(removed).toHaveLength(ROW_COUNT)
+    expect(Object.keys(legacy.state.worktreeMeta)).toHaveLength(0)
+    expect(Object.keys(batch.state.worktreeMeta)).toHaveLength(0)
+    expect(legacySessionClones).toBe(ROW_COUNT)
+    expect(batchSessionClones).toBe(0)
+
+    console.log(
+      `[bench] rows=${ROW_COUNT} metadata+session=${legacyMs.toFixed(2)}ms -> ${batchMs.toFixed(2)}ms; ` +
+        `gitScans=${ROW_COUNT} -> 1; sessionClones=${legacySessionClones} -> ${batchSessionClones}; ` +
+        `minimumSaveSchedules=${ROW_COUNT * 2} -> 1`
+    )
+  })
+})
diff --git a/src/main/persistence/tracking-repos/local-worktree-metadata-scan-expectation.test.ts b/src/main/persistence/tracking-repos/local-worktree-metadata-scan-expectation.test.ts
new file mode 100644
index 00000000000..85c883fe666
--- /dev/null
+++ b/src/main/persistence/tracking-repos/local-worktree-metadata-scan-expectation.test.ts
@@ -0,0 +1,242 @@
+import { describe, expect, it } from 'vitest'
+import { getDefaultPersistedState } from '../../../shared/constants'
+import type { PersistedState } from '../../../shared/persisted-state-types'
+import type { Repo } from '../../../shared/repo-types'
+import type { WorktreeMeta } from '../../../shared/worktree/meta-types'
+import {
+  captureNativeLocalWorktreeMetadataScanExpectation,
+  pruneSessionlessMissingLocalWorktreeMetadataForRepo
+} from './missing-local-worktree-metadata-pruning'
+
+const REPO_ID = 'repo-1'
+const WORKTREE_ID = `${REPO_ID}::/workspace/stale`
+const LOCAL_ALIAS = `local|${WORKTREE_ID}`
+const IDENTITY_KEY = 'local-identity'
+
+function makeRepo(id = REPO_ID): Repo {
+  return {
+    id,
+    path: `/workspace/${id}`,
+    displayName: id,
+    badgeColor: '#000',
+    addedAt: 0
+  }
+}
+
+function makeMeta(worktreeId = WORKTREE_ID): WorktreeMeta {
+  return {
+    instanceId: `instance-${worktreeId}`,
+    hostId: 'local',
+    displayName: worktreeId,
+    comment: '',
+    linkedIssue: null,
+    linkedPR: null,
+    linkedLinearIssue: null,
+    isArchived: false,
+    isUnread: false,
+    isPinned: false,
+    sortOrder: 0,
+    lastActivityAt: 0
+  }
+}
+
+function makeState(): PersistedState {
+  const state = getDefaultPersistedState('/home/test')
+  state.repos = [makeRepo()]
+  return state
+}
+
+function makeCanonicalOnlyState(): {
+  state: PersistedState
+  meta: WorktreeMeta
+} {
+  const state = makeState()
+  const meta = makeMeta()
+  state.worktreeMetaByIdentity = { [IDENTITY_KEY]: meta }
+  state.worktreeIdentityAliases = { [LOCAL_ALIAS]: [IDENTITY_KEY] }
+  return { state, meta }
+}
+
+function pruneCaptured(state: PersistedState): string[] {
+  const scan = captureNativeLocalWorktreeMetadataScanExpectation(state, state.repos[0]!)
+  return pruneSessionlessMissingLocalWorktreeMetadataForRepo(state, scan, scan.metadata)
+}
+
+describe('local worktree metadata scan expectations', () => {
+  it('captures canonical-only local metadata and removes its orphaned identity row', () => {
+    const { state } = makeCanonicalOnlyState()
+
+    expect(pruneCaptured(state)).toEqual([WORKTREE_ID])
+    expect(state.worktreeMeta[WORKTREE_ID]).toBeUndefined()
+    expect(state.worktreeIdentityAliases?.[LOCAL_ALIAS]).toBeUndefined()
+    expect(state.worktreeMetaByIdentity?.[IDENTITY_KEY]).toBeUndefined()
+  })
+
+  it('removes equal legacy and canonical projections after a persistence round trip', () => {
+    const state = makeState()
+    const meta = makeMeta()
+    state.worktreeMeta[WORKTREE_ID] = structuredClone(meta)
+    state.worktreeMetaByIdentity = { [IDENTITY_KEY]: structuredClone(meta) }
+    state.worktreeIdentityAliases = { [LOCAL_ALIAS]: [IDENTITY_KEY] }
+
+    expect(pruneCaptured(state)).toEqual([WORKTREE_ID])
+    expect(state.worktreeMeta[WORKTREE_ID]).toBeUndefined()
+    expect(state.worktreeIdentityAliases[LOCAL_ALIAS]).toBeUndefined()
+    expect(state.worktreeMetaByIdentity[IDENTITY_KEY]).toBeUndefined()
+  })
+
+  it('does not sweep an unrelated unaliased canonical row during pruning', () => {
+    const { state, meta } = makeCanonicalOnlyState()
+    const unrelated = makeMeta(`${REPO_ID}::/workspace/unrelated`)
+    state.worktreeMetaByIdentity!.unrelated = unrelated
+
+    expect(pruneCaptured(state)).toEqual([WORKTREE_ID])
+    expect(state.worktreeMetaByIdentity).toEqual({ unrelated })
+    expect(state.worktreeMetaByIdentity?.[IDENTITY_KEY]).not.toBeDefined()
+    expect(meta).not.toBe(unrelated)
+  })
+
+  it('allocates expectations only for the scanned repository', () => {
+    const state = makeState()
+    const otherRepo = makeRepo('repo-2')
+    const otherId = `${otherRepo.id}::/workspace/other`
+    const canonicalId = `${REPO_ID}::/workspace/canonical`
+    const canonicalKey = 'canonical-key'
+    state.repos.push(otherRepo)
+    state.worktreeMeta[WORKTREE_ID] = makeMeta()
+    state.worktreeMeta[otherId] = makeMeta(otherId)
+    state.worktreeMetaByIdentity = {
+      [canonicalKey]: makeMeta(canonicalId),
+      'other-key': makeMeta(otherId)
+    }
+    state.worktreeIdentityAliases = {
+      [`local|${canonicalId}`]: [canonicalKey],
+      [`local|${otherId}`]: ['other-key']
+    }
+
+    const scan = captureNativeLocalWorktreeMetadataScanExpectation(state, state.repos[0]!)
+
+    expect(scan.metadata.map(({ worktreeId }) => worktreeId).sort()).toEqual(
+      [WORKTREE_ID, canonicalId].sort()
+    )
+  })
+
+  it('preserves metadata when an alias array is replaced with identical contents', () => {
+    const { state } = makeCanonicalOnlyState()
+    const scan = captureNativeLocalWorktreeMetadataScanExpectation(state, state.repos[0]!)
+    state.worktreeIdentityAliases![LOCAL_ALIAS] = [IDENTITY_KEY]
+
+    expect(pruneSessionlessMissingLocalWorktreeMetadataForRepo(state, scan, scan.metadata)).toEqual(
+      []
+    )
+    expect(state.worktreeMetaByIdentity?.[IDENTITY_KEY]).toBeDefined()
+  })
+
+  it('preserves metadata when the captured alias array is mutated in place', () => {
+    const { state } = makeCanonicalOnlyState()
+    const scan = captureNativeLocalWorktreeMetadataScanExpectation(state, state.repos[0]!)
+    state.worktreeIdentityAliases![LOCAL_ALIAS]!.push('new-identity')
+    state.worktreeMetaByIdentity!['new-identity'] = makeMeta()
+
+    expect(pruneSessionlessMissingLocalWorktreeMetadataForRepo(state, scan, scan.metadata)).toEqual(
+      []
+    )
+  })
+
+  it.each([
+    [
+      'replaced',
+      (state: PersistedState) => {
+        state.worktreeMetaByIdentity![IDENTITY_KEY] = {
+          ...state.worktreeMetaByIdentity![IDENTITY_KEY]!
+        }
+      }
+    ],
+    [
+      'host-mutated',
+      (state: PersistedState) => {
+        state.worktreeMetaByIdentity![IDENTITY_KEY]!.hostId = 'ssh:builder'
+      }
+    ],
+    [
+      'instance-mutated',
+      (state: PersistedState) => {
+        state.worktreeMetaByIdentity![IDENTITY_KEY]!.instanceId = 'new-instance'
+      }
+    ],
+    [
+      'content-mutated',
+      (state: PersistedState) => {
+        state.worktreeMetaByIdentity![IDENTITY_KEY]!.comment = 'new comment'
+      }
+    ]
+  ] as const)('preserves metadata when a canonical row is %s', (_label, mutate) => {
+    const { state } = makeCanonicalOnlyState()
+    const scan = captureNativeLocalWorktreeMetadataScanExpectation(state, state.repos[0]!)
+    mutate(state)
+
+    expect(pruneSessionlessMissingLocalWorktreeMetadataForRepo(state, scan, scan.metadata)).toEqual(
+      []
+    )
+  })
+
+  it.each([
+    [
+      'added',
+      (state: PersistedState) => {
+        state.worktreeIdentityAliases![`ssh:builder|${WORKTREE_ID}`] = [IDENTITY_KEY]
+      }
+    ],
+    [
+      'removed',
+      (state: PersistedState) => {
+        delete state.worktreeIdentityAliases![LOCAL_ALIAS]
+      }
+    ]
+  ] as const)('preserves metadata when an alias is %s during the scan', (_label, mutate) => {
+    const { state } = makeCanonicalOnlyState()
+    const scan = captureNativeLocalWorktreeMetadataScanExpectation(state, state.repos[0]!)
+    mutate(state)
+
+    expect(pruneSessionlessMissingLocalWorktreeMetadataForRepo(state, scan, scan.metadata)).toEqual(
+      []
+    )
+    expect(state.worktreeMetaByIdentity?.[IDENTITY_KEY]).toBeDefined()
+  })
+
+  it('preserves a legacy row created after a canonical-only scan capture', () => {
+    const { state } = makeCanonicalOnlyState()
+    const scan = captureNativeLocalWorktreeMetadataScanExpectation(state, state.repos[0]!)
+    state.worktreeMeta[WORKTREE_ID] = makeMeta()
+
+    expect(pruneSessionlessMissingLocalWorktreeMetadataForRepo(state, scan, scan.metadata)).toEqual(
+      []
+    )
+    expect(state.worktreeMeta[WORKTREE_ID]).toBeDefined()
+  })
+
+  it.each([WORKTREE_ID, `bogus|${WORKTREE_ID}`, `ssh:builder|${WORKTREE_ID}`])(
+    'preserves metadata with an unqualified or foreign alias: %s',
+    (alias) => {
+      const state = makeState()
+      state.worktreeMeta[WORKTREE_ID] = makeMeta()
+      state.worktreeMetaByIdentity = { [IDENTITY_KEY]: state.worktreeMeta[WORKTREE_ID]! }
+      state.worktreeIdentityAliases = { [alias]: [IDENTITY_KEY] }
+
+      expect(pruneCaptured(state)).toEqual([])
+      expect(state.worktreeMeta[WORKTREE_ID]).toBeDefined()
+    }
+  )
+
+  it('preserves an unqualified alias whose worktree path contains a pipe', () => {
+    const state = makeState()
+    const pipedId = `${REPO_ID}::/workspace/a|b`
+    state.worktreeMeta[pipedId] = makeMeta(pipedId)
+    state.worktreeMetaByIdentity = { [IDENTITY_KEY]: state.worktreeMeta[pipedId]! }
+    state.worktreeIdentityAliases = { [pipedId]: [IDENTITY_KEY] }
+
+    expect(pruneCaptured(state)).toEqual([])
+    expect(state.worktreeMeta[pipedId]).toBeDefined()
+    expect(state.worktreeIdentityAliases[pipedId]).toEqual([IDENTITY_KEY])
+  })
+})
diff --git a/src/main/persistence/tracking-repos/local-worktree-metadata-scan-expectation.ts b/src/main/persistence/tracking-repos/local-worktree-metadata-scan-expectation.ts
new file mode 100644
index 00000000000..fca925d0986
--- /dev/null
+++ b/src/main/persistence/tracking-repos/local-worktree-metadata-scan-expectation.ts
@@ -0,0 +1,243 @@
+import { isDeepStrictEqual } from 'node:util'
+import type { PersistedState } from '../../../shared/persisted-state-types'
+import type { GlobalSettings } from '../../../shared/global-settings-types'
+import type { Project } from '../../../shared/project-types'
+import type { Repo } from '../../../shared/repo-types'
+import { getRepoKind } from '../../../shared/repo-kind'
+import { splitWorktreeId } from '../../../shared/worktree/id'
+import {
+  composeWorktreeHostIdentity,
+  getWorktreeIdFromHostIdentity,
+  isWorktreeHostIdentity
+} from '../../../shared/worktree/host-qualified-identity'
+import type { WorktreeMeta } from '../../../shared/worktree/meta-types'
+import { LOCAL_EXECUTION_HOST_ID } from '../../../shared/execution-host'
+
+type CapturedLocalRepoIdentity = Readonly<
+  Pick<Repo, 'id' | 'path' | 'connectionId' | 'executionHostId'> & {
+    kind: ReturnType<typeof getRepoKind>
+    expectedRepo: Repo | undefined
+  }
+>
+
+type CapturedLocalRoutingIdentity = Readonly<{
+  expectedProject: Project | undefined
+  expectedProjectUpdatedAt: number | undefined
+  expectedSettings: GlobalSettings
+}>
+
+type MetadataRowExpectation = Readonly<{
+  expectedPresent: boolean
+  expectedMeta: WorktreeMeta | undefined
+  expectedSerialized: string | null | undefined
+  expectedInstanceId: string | undefined
+  expectedHostId: WorktreeMeta['hostId']
+}>
+
+type MetadataAliasExpectation = Readonly<{
+  alias: string
+  expectedAlias: string[]
+  expectedIdentityKeys: readonly string[]
+  expectedIdentityRows: readonly (MetadataRowExpectation & { identityKey: string })[]
+}>
+
+export type LocalWorktreeMetadataPruneExpectation = Readonly<{
+  worktreeId: string
+  expectedLegacy: MetadataRowExpectation
+  expectedAliases: readonly MetadataAliasExpectation[]
+}>
+
+export type NativeLocalWorktreeMetadataScanExpectation = Readonly<{
+  repo: CapturedLocalRepoIdentity
+  routing: CapturedLocalRoutingIdentity
+  metadata: readonly LocalWorktreeMetadataPruneExpectation[]
+}>
+
+type MetadataAliasEntry = readonly [alias: string, identityKeys: string[]]
+
+function serializeMetadataRow(meta: WorktreeMeta | undefined): string | null | undefined {
+  if (!meta) {
+    return undefined
+  }
+  try {
+    return JSON.stringify(meta)
+  } catch {
+    return null
+  }
+}
+
+function captureRow(
+  record: Readonly<Record<string, WorktreeMeta>> | undefined,
+  key: string
+): MetadataRowExpectation {
+  const expectedPresent = Object.hasOwn(record ?? {}, key)
+  const expectedMeta = record?.[key]
+  return {
+    expectedPresent,
+    expectedMeta,
+    expectedSerialized: serializeMetadataRow(expectedMeta),
+    expectedInstanceId: expectedMeta?.instanceId,
+    expectedHostId: expectedMeta?.hostId
+  }
+}
+
+export function indexMetadataAliasesForWorktreeIds(
+  state: PersistedState,
+  worktreeIds: ReadonlySet<string>
+): Map<string, MetadataAliasEntry[]> {
+  const indexed = new Map<string, MetadataAliasEntry[]>()
+  for (const [alias, identityKeys] of Object.entries(state.worktreeIdentityAliases ?? {})) {
+    const matches = new Set<string>()
+    if (worktreeIds.has(alias)) {
+      matches.add(alias)
+    }
+    const separator = alias.indexOf('|')
+    const suffix = separator === -1 ? alias : alias.slice(separator + 1)
+    if (worktreeIds.has(suffix)) {
+      matches.add(suffix)
+    }
+    for (const worktreeId of matches) {
+      const entries = indexed.get(worktreeId) ?? []
+      entries.push([alias, identityKeys])
+      indexed.set(worktreeId, entries)
+    }
+  }
+  return indexed
+}
+
+export function captureNativeLocalWorktreeMetadataScanExpectation(
+  state: PersistedState,
+  repo: Repo
+): NativeLocalWorktreeMetadataScanExpectation {
+  const matchingRepos = state.repos.filter((entry) => entry.id === repo.id)
+  const expectedRepo = matchingRepos.length === 1 ? matchingRepos[0] : undefined
+  const expectedProject = state.projects.find((project) => project.sourceRepoIds.includes(repo.id))
+  const candidateIds = new Set<string>()
+  for (const [worktreeId, meta] of Object.entries(state.worktreeMeta)) {
+    if (
+      splitWorktreeId(worktreeId)?.repoId === repo.id &&
+      (!meta.hostId || meta.hostId === LOCAL_EXECUTION_HOST_ID)
+    ) {
+      candidateIds.add(worktreeId)
+    }
+  }
+  for (const alias of Object.keys(state.worktreeIdentityAliases ?? {})) {
+    if (!isWorktreeHostIdentity(alias)) {
+      continue
+    }
+    const worktreeId = getWorktreeIdFromHostIdentity(alias)
+    if (
+      alias === composeWorktreeHostIdentity(LOCAL_EXECUTION_HOST_ID, worktreeId) &&
+      splitWorktreeId(worktreeId)?.repoId === repo.id
+    ) {
+      candidateIds.add(worktreeId)
+    }
+  }
+  const aliasesByWorktreeId = indexMetadataAliasesForWorktreeIds(state, candidateIds)
+  return {
+    repo: {
+      id: repo.id,
+      path: repo.path,
+      connectionId: repo.connectionId,
+      executionHostId: repo.executionHostId,
+      kind: getRepoKind(repo),
+      expectedRepo
+    },
+    routing: {
+      expectedProject,
+      expectedProjectUpdatedAt: expectedProject?.updatedAt,
+      expectedSettings: state.settings
+    },
+    metadata: [...candidateIds].map((worktreeId) => ({
+      worktreeId,
+      expectedLegacy: captureRow(state.worktreeMeta, worktreeId),
+      expectedAliases: (aliasesByWorktreeId.get(worktreeId) ?? []).map(([alias, identityKeys]) => ({
+        alias,
+        expectedAlias: identityKeys,
+        expectedIdentityKeys: [...identityKeys],
+        expectedIdentityRows: identityKeys.map((identityKey) => ({
+          identityKey,
+          ...captureRow(state.worktreeMetaByIdentity, identityKey)
+        }))
+      }))
+    }))
+  }
+}
+
+function rowStillMatches(
+  record: Readonly<Record<string, WorktreeMeta>> | undefined,
+  key: string,
+  expected: MetadataRowExpectation
+): boolean {
+  const current = record?.[key]
+  return (
+    Object.hasOwn(record ?? {}, key) === expected.expectedPresent &&
+    current === expected.expectedMeta &&
+    expected.expectedSerialized !== null &&
+    serializeMetadataRow(current) === expected.expectedSerialized &&
+    current?.instanceId === expected.expectedInstanceId &&
+    current?.hostId === expected.expectedHostId
+  )
+}
+
+function aliasesStillMatch(
+  state: PersistedState,
+  expected: LocalWorktreeMetadataPruneExpectation,
+  currentAliases: readonly MetadataAliasEntry[]
+): boolean {
+  if (currentAliases.length !== expected.expectedAliases.length) {
+    return false
+  }
+  const currentByAlias = new Map(currentAliases)
+  return expected.expectedAliases.every((aliasExpectation) => {
+    const current = currentByAlias.get(aliasExpectation.alias)
+    return Boolean(
+      current &&
+      current === aliasExpectation.expectedAlias &&
+      current.length === aliasExpectation.expectedIdentityKeys.length &&
+      current.every((key, index) => key === aliasExpectation.expectedIdentityKeys[index]) &&
+      aliasExpectation.expectedIdentityRows.every(({ identityKey, ...row }) =>
+        rowStillMatches(state.worktreeMetaByIdentity, identityKey, row)
+      )
+    )
+  })
+}
+
+export function removeRevalidatedLocalWorktreeMetadata(
+  state: PersistedState,
+  expected: LocalWorktreeMetadataPruneExpectation,
+  currentAliases: readonly MetadataAliasEntry[],
+  removedIdentityKeys?: Set<string>
+): boolean {
+  if (
+    !rowStillMatches(state.worktreeMeta, expected.worktreeId, expected.expectedLegacy) ||
+    !aliasesStillMatch(state, expected, currentAliases)
+  ) {
+    return false
+  }
+  const localAlias = composeWorktreeHostIdentity(LOCAL_EXECUTION_HOST_ID, expected.worktreeId)
+  if (currentAliases.some(([alias]) => alias !== localAlias)) {
+    return false
+  }
+  const legacy = state.worktreeMeta[expected.worktreeId]
+  const identityKeys = state.worktreeIdentityAliases?.[localAlias]
+  if (identityKeys && identityKeys.length !== 1) {
+    return false
+  }
+  const canonical = identityKeys?.[0] ? state.worktreeMetaByIdentity?.[identityKeys[0]] : undefined
+  if (
+    (legacy?.hostId && legacy.hostId !== LOCAL_EXECUTION_HOST_ID) ||
+    (canonical?.hostId && canonical.hostId !== LOCAL_EXECUTION_HOST_ID) ||
+    (identityKeys && !canonical) ||
+    (legacy && canonical && !isDeepStrictEqual(legacy, canonical)) ||
+    (!legacy && !canonical)
+  ) {
+    return false
+  }
+  if (identityKeys?.[0]) {
+    removedIdentityKeys?.add(identityKeys[0])
+  }
+  delete state.worktreeMeta[expected.worktreeId]
+  delete state.worktreeIdentityAliases?.[localAlias]
+  return true
+}
diff --git a/src/main/persistence/tracking-repos/missing-local-worktree-metadata-pruning.test.ts b/src/main/persistence/tracking-repos/missing-local-worktree-metadata-pruning.test.ts
new file mode 100644
index 00000000000..cdad14034e2
--- /dev/null
+++ b/src/main/persistence/tracking-repos/missing-local-worktree-metadata-pruning.test.ts
@@ -0,0 +1,477 @@
+import { describe, expect, it, vi } from 'vitest'
+import { getDefaultPersistedState, getDefaultWorkspaceSession } from '../../../shared/constants'
+import type { PersistedState } from '../../../shared/persisted-state-types'
+import type { Project } from '../../../shared/project-types'
+import type { Repo } from '../../../shared/repo-types'
+import { worktreeWorkspaceKey } from '../../../shared/workspace-scope'
+import type { WorktreeMeta } from '../../../shared/worktree/meta-types'
+import {
+  captureNativeLocalWorktreeMetadataScanExpectation,
+  pruneSessionlessMissingLocalWorktreeMetadataForRepo
+} from './missing-local-worktree-metadata-pruning'
+
+const REPO_ID = 'repo-1'
+const LIVE_ID = `${REPO_ID}::/workspace/live`
+
+function makeRepo(overrides: Partial<Repo> = {}): Repo {
+  return {
+    id: REPO_ID,
+    path: '/workspace/repo',
+    displayName: 'repo',
+    badgeColor: '#000',
+    addedAt: 0,
+    ...overrides
+  }
+}
+
+function makeMeta(worktreeId: string): WorktreeMeta {
+  return {
+    instanceId: `instance-${worktreeId}`,
+    hostId: 'local',
+    displayName: worktreeId,
+    comment: '',
+    linkedIssue: null,
+    linkedPR: null,
+    linkedLinearIssue: null,
+    isArchived: false,
+    isUnread: false,
+    isPinned: false,
+    sortOrder: 0,
+    lastActivityAt: 0
+  }
+}
+
+function makeState(repo = makeRepo()): PersistedState {
+  const state = getDefaultPersistedState('/home/test')
+  state.repos = [repo]
+  return state
+}
+
+function capture(state: PersistedState, repo = state.repos[0]!) {
+  return captureNativeLocalWorktreeMetadataScanExpectation(state, repo)
+}
+
+function pruneCaptured(
+  state: PersistedState,
+  scan: ReturnType<typeof capture>,
+  ids: readonly string[],
+  platform?: NodeJS.Platform
+): string[] {
+  const wanted = new Set(ids)
+  return pruneSessionlessMissingLocalWorktreeMetadataForRepo(
+    state,
+    scan,
+    scan.metadata.filter(({ worktreeId }) => wanted.has(worktreeId)),
+    platform
+  )
+}
+
+describe('pruneSessionlessMissingLocalWorktreeMetadataForRepo', () => {
+  it('removes 2,709 sessionless rows in one batch without cloning or changing session state', () => {
+    const state = makeState()
+    const staleIds = Array.from(
+      { length: 2_709 },
+      (_, index) => `${REPO_ID}::/workspace/stale-${index}`
+    )
+    const allIds = [LIVE_ID, ...staleIds]
+    state.worktreeMetaByIdentity = {}
+    state.worktreeIdentityAliases = {}
+    for (const [index, worktreeId] of allIds.entries()) {
+      const meta = makeMeta(worktreeId)
+      const identityKey = `identity-${index}`
+      state.worktreeMeta[worktreeId] = meta
+      state.worktreeMetaByIdentity[identityKey] = meta
+      state.worktreeIdentityAliases[`local|${worktreeId}`] = [identityKey]
+    }
+    state.worktreeLineageById[staleIds[0]!] = { worktreeId: staleIds[0] } as never
+    state.workspaceLineageByChildKey[worktreeWorkspaceKey(staleIds[0]!)] = {
+      childWorkspaceKey: worktreeWorkspaceKey(staleIds[0]!)
+    } as never
+    state.workspaceSession.terminalTopologyRevisionByRepoId = { [REPO_ID]: 7 }
+    const hostSession = {
+      ...getDefaultWorkspaceSession(),
+      terminalTopologyRevisionByRepoId: { [REPO_ID]: 11 }
+    }
+    state.workspaceSessionsByHostId = { 'runtime:mirror': hostSession }
+    const scan = capture(state)
+    const session = state.workspaceSession
+    const sessionSnapshot = structuredClone(session)
+    const hostSessionSnapshot = structuredClone(hostSession)
+    const cloneSpy = vi.spyOn(globalThis, 'structuredClone')
+
+    const removed = pruneCaptured(state, scan, staleIds)
+
+    expect(removed).toHaveLength(staleIds.length)
+    expect(cloneSpy).not.toHaveBeenCalled()
+    cloneSpy.mockRestore()
+    expect(Object.keys(state.worktreeMeta)).toEqual([LIVE_ID])
+    expect(Object.keys(state.worktreeMetaByIdentity ?? {})).toEqual(['identity-0'])
+    expect(Object.keys(state.worktreeIdentityAliases ?? {})).toEqual([`local|${LIVE_ID}`])
+    expect(state.worktreeLineageById[staleIds[0]!]).toBeUndefined()
+    expect(state.workspaceLineageByChildKey[worktreeWorkspaceKey(staleIds[0]!)]).toBeUndefined()
+    expect(state.workspaceSession).toBe(session)
+    expect(state.workspaceSession).toEqual(sessionSnapshot)
+    expect(state.workspaceSessionsByHostId?.['runtime:mirror']).toBe(hostSession)
+    expect(state.workspaceSessionsByHostId?.['runtime:mirror']).toEqual(hostSessionSnapshot)
+  })
+
+  it('fails closed when metadata is mutated or replaced after the scan starts', () => {
+    const inPlaceState = makeState()
+    const inPlaceId = `${REPO_ID}::/workspace/in-place`
+    inPlaceState.worktreeMeta[inPlaceId] = makeMeta(inPlaceId)
+    const inPlaceScan = capture(inPlaceState)
+    inPlaceState.worktreeMeta[inPlaceId]!.instanceId = 'replacement-instance'
+
+    expect(pruneCaptured(inPlaceState, inPlaceScan, [inPlaceId])).toEqual([])
+
+    const replacedState = makeState()
+    const replacedId = `${REPO_ID}::/workspace/replaced`
+    const original = makeMeta(replacedId)
+    replacedState.worktreeMeta[replacedId] = original
+    const replacedScan = capture(replacedState)
+    replacedState.worktreeMeta[replacedId] = { ...original }
+
+    expect(pruneCaptured(replacedState, replacedScan, [replacedId])).toEqual([])
+    expect(replacedState.worktreeMeta[replacedId]).not.toBe(original)
+  })
+
+  it('fails closed when an identical repo row is removed and re-added during the scan', () => {
+    const state = makeState()
+    const worktreeId = `${REPO_ID}::/workspace/re-added-repo`
+    state.worktreeMeta[worktreeId] = makeMeta(worktreeId)
+    const scan = capture(state)
+    const replacement = { ...state.repos[0]! }
+    state.repos.splice(0, 1, replacement)
+
+    expect(pruneCaptured(state, scan, [worktreeId])).toEqual([])
+    expect(state.repos[0]).toBe(replacement)
+    expect(state.worktreeMeta[worktreeId]).toBeDefined()
+  })
+
+  it('uses the effective Git kind when the raw legacy repo omitted kind', () => {
+    const state = makeState()
+    const worktreeId = `${REPO_ID}::/workspace/legacy-git-kind`
+    const rawRepo = state.repos[0]!
+    state.worktreeMeta[worktreeId] = makeMeta(worktreeId)
+    const scan = capture(state, { ...rawRepo, kind: 'git' })
+
+    expect(rawRepo.kind).toBeUndefined()
+    expect(pruneCaptured(state, scan, [worktreeId])).toEqual([worktreeId])
+  })
+
+  it.each([
+    'tabsByWorktree',
+    'browserTabsByWorktree',
+    'openFilesByWorktree',
+    'activeFileIdByWorktree',
+    'activeBrowserTabIdByWorktree',
+    'clientHostedBrowserPagesByWorktree',
+    'activeTabTypeByWorktree',
+    'activeTabIdByWorktree',
+    'unifiedTabs',
+    'tabGroups',
+    'tabGroupLayouts',
+    'activeGroupIdByWorktree',
+    'lastVisitedAtByWorktreeId',
+    'defaultTerminalTabsAppliedByWorktreeId'
+  ] as const)('preserves an owner named by workspaceSession.%s', (field) => {
+    const state = makeState()
+    const worktreeId = `${REPO_ID}::/workspace/${field}`
+    state.worktreeMeta[worktreeId] = makeMeta(worktreeId)
+    const scan = capture(state)
+    const ownerKey = field === 'lastVisitedAtByWorktreeId' ? `local|${worktreeId}` : worktreeId
+    ;(state.workspaceSession as unknown as Record<string, unknown>)[field] = {
+      [ownerKey]: []
+    }
+
+    expect(pruneCaptured(state, scan, [worktreeId])).toEqual([])
+    expect(state.worktreeMeta[worktreeId]).toBeDefined()
+  })
+
+  it('preserves scalar, nested, remote-partition, mobile, and relay recovery owners', () => {
+    const ownerMutations: ((state: PersistedState, worktreeId: string) => void)[] = [
+      (state, worktreeId) => {
+        state.workspaceSession.activeWorktreeId = worktreeId
+      },
+      (state, worktreeId) => {
+        state.workspaceSession.activeWorkspaceKey = worktreeWorkspaceKey(worktreeId)
+      },
+      (state, worktreeId) => {
+        state.workspaceSession.activeWorktreeIdsOnShutdown = [worktreeId]
+      },
+      (state, worktreeId) => {
+        state.ui.lastActiveWorktreeId = worktreeId
+      },
+      (state, worktreeId) => {
+        state.workspaceSession.sleepingAgentSessionsByPaneKey = {
+          pane: { worktreeId } as never
+        }
+      },
+      (state, worktreeId) => {
+        state.workspaceSession.terminalSurfaceTombstonesByPaneKey = {
+          pane: { worktreeId } as never
+        }
+      },
+      (state, worktreeId) => {
+        state.workspaceSession.closedTerminalTabTombstonesByTabId = {
+          tab: { worktreeId, closedAt: 1 }
+        }
+      },
+      (state, worktreeId) => {
+        state.workspaceSession.clientHostedBrowserCloseIntentsByEnvironment = {
+          runtime: [{ worktreeId, browserPageId: 'page', closedAt: 1 }]
+        }
+      },
+      (state, worktreeId) => {
+        state.workspaceSession.browserPagesByWorkspace = {
+          browser: [{ worktreeId } as never]
+        }
+      },
+      (state, worktreeId) => {
+        state.workspaceSessionsByHostId = {
+          'ssh:builder': {
+            ...getDefaultWorkspaceSession(),
+            lastVisitedAtByWorktreeId: { [worktreeId]: 1 }
+          }
+        }
+      },
+      (state, worktreeId) => {
+        state.mobileClientTabSelectionsByDeviceId = {
+          phone: { [worktreeId]: {} as never }
+        }
+      },
+      (state, worktreeId) => {
+        state.sshRemotePtyLeases = [
+          {
+            targetId: 'builder',
+            ptyId: 'pty',
+            worktreeId,
+            state: 'detached',
+            createdAt: 1,
+            updatedAt: 1
+          }
+        ]
+      },
+      (state, worktreeId) => {
+        state.migrationUnsupportedPtyEntries = [
+          {
+            ptyId: 'pty',
+            worktreeId,
+            reason: 'legacy-numeric-pane-key',
+            source: 'local',
+            updatedAt: 1
+          }
+        ]
+      },
+      (state, worktreeId) => {
+        state.automations = [
+          {
+            enabled: true,
+            workspaceMode: 'existing',
+            workspaceId: worktreeId
+          } as never
+        ]
+      },
+      (state, worktreeId) => {
+        state.automationRuns = [{ status: 'dispatching', workspaceId: worktreeId } as never]
+      }
+    ]
+
+    for (const [index, mutate] of ownerMutations.entries()) {
+      const state = makeState()
+      const worktreeId = `${REPO_ID}::/workspace/owner-${index}`
+      state.worktreeMeta[worktreeId] = makeMeta(worktreeId)
+      const scan = capture(state)
+      mutate(state, worktreeId)
+      expect(pruneCaptured(state, scan, [worktreeId])).toEqual([])
+    }
+  })
+
+  it('preserves canonically equivalent session and top-level owners', () => {
+    const candidateId = `${REPO_ID}::/workspace/Café`.normalize('NFC')
+    const ownerId = candidateId.normalize('NFD')
+    const ownerMutations: ((state: PersistedState) => void)[] = [
+      (state) => {
+        state.workspaceSession.activeWorktreeId = ownerId
+      },
+      (state) => {
+        state.ui.lastActiveWorktreeId = ownerId
+      }
+    ]
+
+    for (const mutate of ownerMutations) {
+      const state = makeState()
+      state.worktreeMeta[candidateId] = makeMeta(candidateId)
+      const scan = capture(state)
+      mutate(state)
+
+      expect(pruneCaptured(state, scan, [candidateId])).toEqual([])
+      expect(state.worktreeMeta[candidateId]).toBeDefined()
+    }
+  })
+
+  it('removes a row on a later pass after its persisted owner is cleared', () => {
+    const state = makeState()
+    const worktreeId = `${REPO_ID}::/workspace/two-phase`
+    state.worktreeMeta[worktreeId] = makeMeta(worktreeId)
+    state.workspaceSession.lastVisitedAtByWorktreeId = { [worktreeId]: 1 }
+    const scan = capture(state)
+
+    expect(pruneCaptured(state, scan, [worktreeId])).toEqual([])
+    delete state.workspaceSession.lastVisitedAtByWorktreeId![worktreeId]
+    expect(pruneCaptured(state, scan, [worktreeId])).toEqual([worktreeId])
+  })
+
+  it('treats dotfile visibility and cleanup dismissals as non-owning preferences', () => {
+    const state = makeState()
+    const worktreeId = `${REPO_ID}::/workspace/non-owning-preferences`
+    state.worktreeMeta[worktreeId] = makeMeta(worktreeId)
+    const showDotfilesByWorktree = { [worktreeId]: true }
+    const workspaceCleanup = {
+      dismissals: {
+        [worktreeId]: {
+          worktreeId,
+          dismissedAt: 1,
+          fingerprint: 'fingerprint',
+          classifierVersion: 1
+        }
+      }
+    }
+    state.ui.showDotfilesByWorktree = showDotfilesByWorktree
+    state.ui.workspaceCleanup = workspaceCleanup
+    const scan = capture(state)
+
+    expect(pruneCaptured(state, scan, [worktreeId])).toEqual([worktreeId])
+    expect(state.ui.showDotfilesByWorktree).toBe(showDotfilesByWorktree)
+    expect(state.ui.workspaceCleanup).toBe(workspaceCleanup)
+  })
+
+  it('preserves foreign aliases, ambiguous local aliases, and divergent projections', () => {
+    const foreignState = makeState()
+    const foreignId = `${REPO_ID}::/workspace/foreign-alias`
+    const localMeta = makeMeta(foreignId)
+    const remoteMeta = { ...localMeta, hostId: 'ssh:builder' as const }
+    foreignState.worktreeMeta[foreignId] = localMeta
+    foreignState.worktreeMetaByIdentity = { local: localMeta, remote: remoteMeta }
+    foreignState.worktreeIdentityAliases = {
+      [`local|${foreignId}`]: ['local'],
+      [`ssh:builder|${foreignId}`]: ['remote']
+    }
+    const foreignScan = capture(foreignState)
+
+    expect(pruneCaptured(foreignState, foreignScan, [foreignId])).toEqual([])
+    expect(foreignState.worktreeMetaByIdentity).toEqual({ local: localMeta, remote: remoteMeta })
+
+    const ambiguousState = makeState()
+    const ambiguousId = `${REPO_ID}::/workspace/ambiguous`
+    const first = makeMeta(ambiguousId)
+    ambiguousState.worktreeMeta[ambiguousId] = first
+    ambiguousState.worktreeMetaByIdentity = { first, second: { ...first } }
+    ambiguousState.worktreeIdentityAliases = { [`local|${ambiguousId}`]: ['first', 'second'] }
+    expect(pruneCaptured(ambiguousState, capture(ambiguousState), [ambiguousId])).toEqual([])
+
+    const divergentState = makeState()
+    const divergentId = `${REPO_ID}::/workspace/divergent`
+    const legacy = makeMeta(divergentId)
+    const canonical = { ...legacy, comment: 'newer canonical comment' }
+    divergentState.worktreeMeta[divergentId] = legacy
+    divergentState.worktreeMetaByIdentity = { canonical }
+    divergentState.worktreeIdentityAliases = { [`local|${divergentId}`]: ['canonical'] }
+    const divergentScan = capture(divergentState)
+    expect(pruneCaptured(divergentState, divergentScan, [divergentId])).toEqual([])
+  })
+
+  it('fails closed for repo replacement, host collisions, remote, runtime, and folder repos', () => {
+    const mutations: ((state: PersistedState) => void)[] = [
+      (state) => {
+        state.repos[0] = makeRepo({ path: '/workspace/replacement' })
+      },
+      (state) => {
+        state.repos.push(makeRepo({ connectionId: 'builder', executionHostId: 'ssh:builder' }))
+      },
+      (state) => {
+        state.repos[0] = makeRepo({ connectionId: 'builder', executionHostId: 'ssh:builder' })
+      },
+      (state) => {
+        state.repos[0] = makeRepo({ executionHostId: 'runtime:environment' })
+      },
+      (state) => {
+        state.repos[0] = makeRepo({ kind: 'folder' })
+      }
+    ]
+    for (const mutate of mutations) {
+      const state = makeState()
+      const worktreeId = `${REPO_ID}::/workspace/stale`
+      state.worktreeMeta[worktreeId] = makeMeta(worktreeId)
+      const scan = capture(state)
+      mutate(state)
+      expect(pruneCaptured(state, scan, [worktreeId])).toEqual([])
+    }
+  })
+
+  it('fails closed when project runtime routing changes away and back during the scan', () => {
+    const state = makeState()
+    const worktreeId = `${REPO_ID}::/workspace/project-routing-race`
+    const project: Project = {
+      id: 'project-1',
+      displayName: 'project',
+      badgeColor: '#000',
+      localWindowsRuntimePreference: { kind: 'windows-host' },
+      sourceRepoIds: [REPO_ID],
+      createdAt: 1,
+      updatedAt: 1
+    }
+    state.projects = [project]
+    state.worktreeMeta[worktreeId] = makeMeta(worktreeId)
+    const scan = capture(state)
+    project.localWindowsRuntimePreference = { kind: 'wsl', distro: 'Ubuntu' }
+    project.updatedAt += 1
+    project.localWindowsRuntimePreference = { kind: 'windows-host' }
+    project.updatedAt += 1
+
+    expect(pruneCaptured(state, scan, [worktreeId])).toEqual([])
+    expect(state.worktreeMeta[worktreeId]).toBeDefined()
+  })
+
+  it('fails closed when global runtime routing changes away and back during the scan', () => {
+    const state = makeState()
+    const worktreeId = `${REPO_ID}::/workspace/settings-routing-race`
+    const originalDefault = state.settings.localWindowsRuntimeDefault
+    state.worktreeMeta[worktreeId] = makeMeta(worktreeId)
+    const scan = capture(state)
+    state.settings = {
+      ...state.settings,
+      localWindowsRuntimeDefault: { kind: 'wsl', distro: 'Ubuntu' }
+    }
+    state.settings = {
+      ...state.settings,
+      localWindowsRuntimeDefault: originalDefault
+    }
+
+    expect(state.settings.localWindowsRuntimeDefault).toEqual(originalDefault)
+    expect(pruneCaptured(state, scan, [worktreeId])).toEqual([])
+    expect(state.worktreeMeta[worktreeId]).toBeDefined()
+  })
+
+  it('rejects malformed, folder-instance, WSL, and non-native Windows candidate paths', () => {
+    const state = makeState()
+    const foreignWindowsId = `${REPO_ID}::C:\\workspace\\stale`
+    const ids = [
+      `${REPO_ID}::relative/path`,
+      `${REPO_ID}::`,
+      `wrong::/workspace/stale`,
+      `${REPO_ID}::/workspace/folder::workspace:11111111-1111-4111-8111-111111111111`,
+      `${REPO_ID}::\\\\wsl.localhost\\Ubuntu\\home\\gone`,
+      `${REPO_ID}::/home/user/wsl-legacy`,
+      foreignWindowsId
+    ]
+    for (const worktreeId of ids) {
+      state.worktreeMeta[worktreeId] = makeMeta(worktreeId)
+    }
+    const scan = capture(state)
+
+    expect(pruneCaptured(state, scan, ids.slice(0, -2))).toEqual([])
+    expect(pruneCaptured(state, scan, [ids.at(-2)!], 'win32')).toEqual([])
+    expect(pruneCaptured(state, scan, [foreignWindowsId], 'linux')).toEqual([])
+  })
+})
diff --git a/src/main/persistence/tracking-repos/missing-local-worktree-metadata-pruning.ts b/src/main/persistence/tracking-repos/missing-local-worktree-metadata-pruning.ts
new file mode 100644
index 00000000000..3ab380bdd8e
--- /dev/null
+++ b/src/main/persistence/tracking-repos/missing-local-worktree-metadata-pruning.ts
@@ -0,0 +1,153 @@
+import { isWindowsAbsolutePathLike } from '../../../shared/cross-platform-path'
+import { getRepoExecutionHostId, LOCAL_EXECUTION_HOST_ID } from '../../../shared/execution-host'
+import type { PersistedState } from '../../../shared/persisted-state-types'
+import { getRepoKind } from '../../../shared/repo-kind'
+import { worktreeWorkspaceKey } from '../../../shared/workspace-scope'
+import { FOLDER_WORKSPACE_INSTANCE_SEPARATOR, splitWorktreeId } from '../../../shared/worktree/id'
+import { isWslUncPath } from '../../../shared/wsl-paths'
+import { isFinalAutomationRunStatus } from '../../../shared/automations-types'
+import { pruneUnreferencedWorktreeIdentityMeta } from '../loading-store/worktree-identity-metadata'
+import {
+  addPersistedSessionWorktreeOwners,
+  createWorktreeOwnerCandidateCollector
+} from '../restoring-sessions/session-worktree-ownership'
+import {
+  indexMetadataAliasesForWorktreeIds,
+  removeRevalidatedLocalWorktreeMetadata,
+  type LocalWorktreeMetadataPruneExpectation,
+  type NativeLocalWorktreeMetadataScanExpectation
+} from './local-worktree-metadata-scan-expectation'
+
+export { captureNativeLocalWorktreeMetadataScanExpectation } from './local-worktree-metadata-scan-expectation'
+export type {
+  LocalWorktreeMetadataPruneExpectation,
+  NativeLocalWorktreeMetadataScanExpectation
+} from './local-worktree-metadata-scan-expectation'
+
+function collectPersistedWorkspaceOwners(
+  state: PersistedState,
+  candidateIds: ReadonlySet<string>,
+  platform: NodeJS.Platform
+): Set<string> {
+  const collector = createWorktreeOwnerCandidateCollector(candidateIds, platform)
+  addPersistedSessionWorktreeOwners(state, collector)
+  const add = collector.addOwner
+  add(state.ui.lastActiveWorktreeId)
+  for (const selections of Object.values(state.mobileClientTabSelectionsByDeviceId ?? {})) {
+    for (const worktreeId of Object.keys(selections)) {
+      add(worktreeId)
+    }
+  }
+  for (const lease of state.sshRemotePtyLeases) {
+    add(lease.worktreeId)
+  }
+  for (const entry of state.migrationUnsupportedPtyEntries) {
+    add(entry.worktreeId)
+  }
+  for (const automation of state.automations) {
+    if (automation.enabled && automation.workspaceMode === 'existing') {
+      add(automation.workspaceId)
+    }
+  }
+  for (const run of state.automationRuns) {
+    if (!isFinalAutomationRunStatus(run.status)) {
+      add(run.workspaceId)
+    }
+  }
+  return collector.owners
+}
+
+function repoStillMatches(
+  state: PersistedState,
+  expected: NativeLocalWorktreeMetadataScanExpectation['repo']
+): boolean {
+  const owners = state.repos.filter((repo) => repo.id === expected.id)
+  const current = owners[0]
+  return Boolean(
+    owners.length === 1 &&
+    current &&
+    current === expected.expectedRepo &&
+    current.path === expected.path &&
+    current.connectionId === expected.connectionId &&
+    current.executionHostId === expected.executionHostId &&
+    getRepoKind(current) === expected.kind &&
+    expected.kind === 'git' &&
+    !current.connectionId &&
+    getRepoExecutionHostId(current) === LOCAL_EXECUTION_HOST_ID
+  )
+}
+
+function routingStillMatches(
+  state: PersistedState,
+  expected: NativeLocalWorktreeMetadataScanExpectation
+): boolean {
+  const currentProject = state.projects.find((project) =>
+    project.sourceRepoIds.includes(expected.repo.id)
+  )
+  return (
+    currentProject === expected.routing.expectedProject &&
+    currentProject?.updatedAt === expected.routing.expectedProjectUpdatedAt &&
+    state.settings === expected.routing.expectedSettings
+  )
+}
+
+function isValidCandidateId(
+  repoId: string,
+  worktreeId: string,
+  platform: NodeJS.Platform
+): boolean {
+  const parsed = splitWorktreeId(worktreeId)
+  return Boolean(
+    parsed?.repoId === repoId &&
+    parsed.worktreePath.length > 0 &&
+    !isWslUncPath(parsed.worktreePath) &&
+    (platform === 'win32'
+      ? isWindowsAbsolutePathLike(parsed.worktreePath)
+      : parsed.worktreePath.startsWith('/')) &&
+    !worktreeId.includes(FOLDER_WORKSPACE_INSTANCE_SEPARATOR)
+  )
+}
+
+export function pruneSessionlessMissingLocalWorktreeMetadataForRepo(
+  state: PersistedState,
+  scan: NativeLocalWorktreeMetadataScanExpectation,
+  missingMetadata: readonly LocalWorktreeMetadataPruneExpectation[],
+  platform = process.platform
+): string[] {
+  if (
+    missingMetadata.length === 0 ||
+    !repoStillMatches(state, scan.repo) ||
+    !routingStillMatches(state, scan)
+  ) {
+    return []
+  }
+
+  const candidateIds = new Set(missingMetadata.map(({ worktreeId }) => worktreeId))
+  const sessionOwners = collectPersistedWorkspaceOwners(state, candidateIds, platform)
+  const aliasesByWorktreeId = indexMetadataAliasesForWorktreeIds(state, candidateIds)
+  const removedIdentityKeys = new Set<string>()
+  const removedIds: string[] = []
+  for (const expectation of missingMetadata) {
+    const { worktreeId } = expectation
+    if (
+      !isValidCandidateId(scan.repo.id, worktreeId, platform) ||
+      sessionOwners.has(worktreeId) ||
+      !removeRevalidatedLocalWorktreeMetadata(
+        state,
+        expectation,
+        aliasesByWorktreeId.get(worktreeId) ?? [],
+        removedIdentityKeys
+      )
+    ) {
+      continue
+    }
+    delete state.worktreeLineageById[worktreeId]
+    delete state.workspaceLineageByChildKey[worktreeWorkspaceKey(worktreeId)]
+    removedIds.push(worktreeId)
+  }
+  if (removedIds.length > 0) {
+    // Why: a global sweep could delete unrelated unaliased rows from another repo or host.
+    pruneUnreferencedWorktreeIdentityMeta(state, removedIdentityKeys)
+  }
+  return removedIds
+}
diff --git a/src/main/persistence/tracking-repos/project-host-operations.ts b/src/main/persistence/tracking-repos/project-host-operations.ts
index c6a8441f58a..605c258f4f7 100644
--- a/src/main/persistence/tracking-repos/project-host-operations.ts
+++ b/src/main/persistence/tracking-repos/project-host-operations.ts
@@ -19,6 +19,7 @@ import { repoGitUsernameCacheKey } from './repo-hydration'
 export type ProjectHostMutationOperations = {
   state: PersistedState
   gitUsernameCache: Map<string, string>
+  bumpLocalWorktreeScanGeneration: (repoId: string) => void
   hydrateRepo: (repo: Repo) => Repo
   updateRepoBackedProjectHostSetup: (
     setup: ProjectHostSetup,
@@ -87,6 +88,9 @@ export class ProjectHostPersistenceOperations {
       return null
     }
     if ('localWindowsRuntimePreference' in updates) {
+      for (const repoId of project.sourceRepoIds) {
+        this.operations.bumpLocalWorktreeScanGeneration(repoId)
+      }
       if (updates.localWindowsRuntimePreference === undefined) {
         delete project.localWindowsRuntimePreference
       } else {
diff --git a/src/main/persistence/tracking-repos/repo-update-operations.ts b/src/main/persistence/tracking-repos/repo-update-operations.ts
index f39e0e1e26f..6ad6f23903b 100644
--- a/src/main/persistence/tracking-repos/repo-update-operations.ts
+++ b/src/main/persistence/tracking-repos/repo-update-operations.ts
@@ -9,6 +9,7 @@ import { sanitizeRepoUpdatesForPersistence } from './repo-sanitization'
 
 export type RepoUpdateMutationOperations = {
   state: PersistedState
+  bumpLocalWorktreeScanGeneration: (repoId: string) => void
   syncProjectHostSetupCompatibilityState: () => void
   scheduleSave: () => void
   hydrateRepo: (repo: Repo) => Repo
@@ -21,6 +22,10 @@ export class RepoUpdatePersistenceOperations {
     return this.operations.state
   }
 
+  private bumpLocalWorktreeScanGeneration(repoId: string): void {
+    this.operations.bumpLocalWorktreeScanGeneration(repoId)
+  }
+
   private syncProjectHostSetupCompatibilityState(): void {
     this.operations.syncProjectHostSetupCompatibilityState()
   }
@@ -177,6 +182,7 @@ export class RepoUpdatePersistenceOperations {
       }
     }
     Object.assign(repo, sanitizedUpdates)
+    this.bumpLocalWorktreeScanGeneration(id)
     this.syncProjectHostSetupCompatibilityState()
     this.scheduleSave()
     return this.hydrateRepo(repo)
diff --git a/src/main/worktree-lineage-pruning.test.ts b/src/main/worktree-lineage-pruning.test.ts
index db393e864d5..22b34f70104 100644
--- a/src/main/worktree-lineage-pruning.test.ts
+++ b/src/main/worktree-lineage-pruning.test.ts
@@ -57,6 +57,82 @@ function createStore(
 }
 
 describe('pruneLineageForMissingRepoWorktrees', () => {
+  it('keeps lineage stored under another spelling of a live worktree path', () => {
+    const parentId = 'repo-1::/repo'
+    const childId = 'repo-1::/repo/./child'
+    const edge = lineage(childId, parentId)
+    const worktreeLineageById = { [childId]: edge }
+    const workspaceLineageByChildKey = {
+      [worktreeWorkspaceKey(childId)]: workspaceLineage(childId, parentId)
+    }
+    const metaById = {
+      [parentId]: { instanceId: edge.parentWorktreeInstanceId } as WorktreeMeta
+    }
+    const store = createStore(worktreeLineageById, workspaceLineageByChildKey, metaById)
+
+    pruneLineageForMissingRepoWorktrees(
+      store as never,
+      repo,
+      [
+        { path: '/repo', head: 'a', branch: 'main', isBare: false, isMainWorktree: true },
+        { path: '/repo/child/', head: 'b', branch: 'child', isBare: false, isMainWorktree: false }
+      ],
+      { platform: 'linux' }
+    )
+
+    expect(store.removeWorktreeLineage).not.toHaveBeenCalled()
+    expect(store.removeWorkspaceLineage).not.toHaveBeenCalled()
+    expect(store.setWorktreeMeta).not.toHaveBeenCalled()
+    expect(worktreeLineageById[childId]).toBe(edge)
+  })
+
+  it('keeps captured metadata lineage not removed after Git canonicalizes paths', () => {
+    const parentId = 'repo-1::/alias/parent'
+    const childId = 'repo-1::/alias/child'
+    const edge = lineage(childId, parentId)
+    const worktreeLineageById = { [childId]: edge }
+    const workspaceLineageByChildKey = {
+      [worktreeWorkspaceKey(childId)]: workspaceLineage(childId, parentId)
+    }
+    const metaById = {
+      [childId]: { instanceId: edge.worktreeInstanceId } as WorktreeMeta,
+      [parentId]: { instanceId: edge.parentWorktreeInstanceId } as WorktreeMeta
+    }
+    const store = createStore(worktreeLineageById, workspaceLineageByChildKey, metaById)
+
+    pruneLineageForMissingRepoWorktrees(
+      store as never,
+      repo,
+      [
+        {
+          path: '/canonical/parent',
+          head: 'a',
+          branch: 'parent',
+          isBare: false,
+          isMainWorktree: false
+        },
+        {
+          path: '/canonical/child',
+          head: 'b',
+          branch: 'child',
+          isBare: false,
+          isMainWorktree: false
+        }
+      ],
+      {
+        platform: 'linux',
+        preservedMetadataCandidateIds: new Set([parentId, childId])
+      }
+    )
+
+    expect(store.removeWorktreeLineage).not.toHaveBeenCalled()
+    expect(store.removeWorkspaceLineage).not.toHaveBeenCalled()
+    expect(store.setWorktreeMeta).not.toHaveBeenCalled()
+    expect(worktreeLineageById[childId]).toBe(edge)
+    expect(workspaceLineageByChildKey[worktreeWorkspaceKey(childId)]).toBeDefined()
+    expect(metaById[parentId].instanceId).toBe(edge.parentWorktreeInstanceId)
+  })
+
   it('refuses an empty scan when the repo still has registered lineage', () => {
     const parentId = 'repo-1::/repo/parent'
     const childId = 'repo-1::/repo/child'
@@ -78,7 +154,7 @@ describe('pruneLineageForMissingRepoWorktrees', () => {
     expect(workspaceLineageByChildKey[worktreeWorkspaceKey(childId)]).toBe(workspaceEdge)
   })
 
-  it('prunes missing children and rotates missing parents after a trusted non-empty scan', () => {
+  it('prunes and rotates missing IDs absent from preserved metadata candidates', () => {
     const liveParentId = 'repo-1::/repo/live-parent'
     const missingChildId = 'repo-1::/repo/missing-child'
     const liveChildId = 'repo-1::/repo/live-child'
@@ -99,25 +175,31 @@ describe('pruneLineageForMissingRepoWorktrees', () => {
     }
     const store = createStore(worktreeLineageById, workspaceLineageByChildKey, metaById)
 
-    pruneLineageForMissingRepoWorktrees(store as never, repo, [
-      {
-        path: '/repo/live-parent',
-        head: 'a',
-        branch: 'main',
-        isBare: false,
-        isMainWorktree: false
-      },
-      {
-        path: '/repo/live-child',
-        head: 'b',
-        branch: 'child',
-        isBare: false,
-        isMainWorktree: false
-      }
-    ])
+    pruneLineageForMissingRepoWorktrees(
+      store as never,
+      repo,
+      [
+        {
+          path: '/repo/live-parent',
+          head: 'a',
+          branch: 'main',
+          isBare: false,
+          isMainWorktree: false
+        },
+        {
+          path: '/repo/live-child',
+          head: 'b',
+          branch: 'child',
+          isBare: false,
+          isMainWorktree: false
+        }
+      ],
+      { preservedMetadataCandidateIds: new Set([liveParentId, liveChildId]) }
+    )
 
     expect(store.removeWorktreeLineage).toHaveBeenCalledWith(missingChildId)
     expect(store.removeWorktreeLineage).not.toHaveBeenCalledWith(liveChildId)
+    expect(store.removeWorkspaceLineage).toHaveBeenCalledWith(worktreeWorkspaceKey(missingChildId))
     expect(store.setWorktreeMeta).toHaveBeenCalledWith(missingParentId, {
       instanceId: expect.any(String)
     })
@@ -126,4 +208,25 @@ describe('pruneLineageForMissingRepoWorktrees', () => {
       missingParentEdge.parentWorktreeInstanceId
     )
   })
+
+  it('does not rematerialize metadata already removed for a missing parent', () => {
+    const liveChildId = 'repo-1::/repo/live-child'
+    const removedParentId = 'repo-1::/repo/removed-parent'
+    const edge = lineage(liveChildId, removedParentId)
+    const worktreeLineageById = { [liveChildId]: edge }
+    const store = createStore(worktreeLineageById, {}, {})
+
+    pruneLineageForMissingRepoWorktrees(store as never, repo, [
+      {
+        path: '/repo/live-child',
+        head: 'child-head',
+        branch: 'child',
+        isBare: false,
+        isMainWorktree: false
+      }
+    ])
+
+    expect(store.setWorktreeMeta).not.toHaveBeenCalled()
+    expect(worktreeLineageById[liveChildId]).toBe(edge)
+  })
 })
diff --git a/src/main/worktree-lineage-pruning.ts b/src/main/worktree-lineage-pruning.ts
index 34a99ef6e95..6040f25c03d 100644
--- a/src/main/worktree-lineage-pruning.ts
+++ b/src/main/worktree-lineage-pruning.ts
@@ -4,6 +4,8 @@ import type { WorkspaceLineage, WorktreeLineage } from '../shared/worktree/linea
 import type { GitWorktreeInfo } from '../shared/worktree/types'
 import { getRepoExecutionHostId } from '../shared/execution-host'
 import { isWorkspaceKey, parseWorkspaceKey, worktreeWorkspaceKey } from '../shared/workspace-scope'
+import { splitWorktreeId } from '../shared/worktree/id'
+import { worktreeRetentionPathComparisonKey } from './worktree-retention-path-comparison'
 import type { Store } from './persistence'
 
 function worktreeIdBelongsToRepo(worktreeId: string, repoPrefix: string): boolean {
@@ -37,8 +39,13 @@ function hasStoredRepoLineage(
 export function pruneLineageForMissingRepoWorktrees(
   store: Store,
   repo: Repo,
-  gitWorktrees: GitWorktreeInfo[]
+  gitWorktrees: GitWorktreeInfo[],
+  options: {
+    platform?: NodeJS.Platform
+    preservedMetadataCandidateIds?: ReadonlySet<string>
+  } = {}
 ): void {
+  const { platform = process.platform, preservedMetadataCandidateIds } = options
   if (
     typeof store.getAllWorktreeLineage !== 'function' ||
     typeof store.removeWorktreeLineage !== 'function'
@@ -56,6 +63,24 @@ export function pruneLineageForMissingRepoWorktrees(
     return
   }
   const liveIds = new Set(gitWorktrees.map((worktree) => `${repo.id}::${worktree.path}`))
+  const livePathKeys = new Set(
+    [repo.path, ...gitWorktrees.map(({ path }) => path)].map((pathValue) =>
+      worktreeRetentionPathComparisonKey(pathValue, platform)
+    )
+  )
+  const isLive = (worktreeId: string): boolean => {
+    if (liveIds.has(worktreeId) || preservedMetadataCandidateIds?.has(worktreeId)) {
+      return true
+    }
+    const worktreePath = splitWorktreeId(worktreeId)?.worktreePath
+    if (!worktreePath) {
+      return false
+    }
+    if (livePathKeys.has(worktreeRetentionPathComparisonKey(worktreePath, platform))) {
+      return true
+    }
+    return false
+  }
   const expectedHostId = getRepoExecutionHostId(repo)
   const repoOwners = store.getRepos().filter((candidate) => candidate.id === repo.id)
   const canMutateWorktree = (worktreeId: string): boolean => {
@@ -68,7 +93,7 @@ export function pruneLineageForMissingRepoWorktrees(
       childScope?.type === 'worktree' &&
       worktreeIdBelongsToRepo(childScope.worktreeId, repoPrefix) &&
       canMutateWorktree(childScope.worktreeId) &&
-      !liveIds.has(childScope.worktreeId) &&
+      !isLive(childScope.worktreeId) &&
       isWorkspaceKey(childWorkspaceKey)
     ) {
       store.removeWorkspaceLineage?.(childWorkspaceKey)
@@ -78,7 +103,7 @@ export function pruneLineageForMissingRepoWorktrees(
     if (
       worktreeIdBelongsToRepo(childId, repoPrefix) &&
       canMutateWorktree(childId) &&
-      !liveIds.has(childId)
+      !isLive(childId)
     ) {
       // Why: a proven-missing path must not transfer its lineage to a future checkout at that path.
       store.removeWorktreeLineage(childId)
@@ -87,10 +112,10 @@ export function pruneLineageForMissingRepoWorktrees(
     if (
       worktreeIdBelongsToRepo(lineage.parentWorktreeId, repoPrefix) &&
       canMutateWorktree(lineage.parentWorktreeId) &&
-      !liveIds.has(lineage.parentWorktreeId)
+      !isLive(lineage.parentWorktreeId)
     ) {
       const parentMeta = store.getWorktreeMeta(lineage.parentWorktreeId)
-      if (!parentMeta || parentMeta.instanceId === lineage.parentWorktreeInstanceId) {
+      if (parentMeta?.instanceId === lineage.parentWorktreeInstanceId) {
         // Why: rotate a proven-missing parent's identity once so path reuse cannot validate old lineage.
         store.setWorktreeMeta(lineage.parentWorktreeId, { instanceId: randomUUID() })
       }
diff --git a/src/main/worktree-retention-path-comparison.ts b/src/main/worktree-retention-path-comparison.ts
new file mode 100644
index 00000000000..2ff3fd02990
--- /dev/null
+++ b/src/main/worktree-retention-path-comparison.ts
@@ -0,0 +1,24 @@
+import { splitWorktreeId } from '../shared/worktree/id'
+import { worktreePathComparisonKey } from './ipc/worktree-path-comparison'
+
+/** Comparison keys used only to retain state; canonical equivalence must never select a delete target. */
+export function worktreeRetentionPathComparisonKey(
+  pathValue: string,
+  platform: NodeJS.Platform
+): string {
+  return worktreePathComparisonKey(pathValue.normalize('NFC'), platform)
+}
+
+export function worktreeRetentionIdComparisonKey(
+  worktreeId: string,
+  platform: NodeJS.Platform
+): string | null {
+  const parsed = splitWorktreeId(worktreeId)
+  if (!parsed?.repoId || !parsed.worktreePath) {
+    return null
+  }
+  return JSON.stringify([
+    parsed.repoId,
+    worktreeRetentionPathComparisonKey(parsed.worktreePath, platform)
+  ])
+}
diff --git a/src/shared/priority-semaphore.test.ts b/src/shared/priority-semaphore.test.ts
index 035e3ca920d..aeeacda94ef 100644
--- a/src/shared/priority-semaphore.test.ts
+++ b/src/shared/priority-semaphore.test.ts
@@ -145,4 +145,19 @@ describe('PrioritySemaphore', () => {
     const r2 = await sem.acquire(0)
     r2()
   })
+
+  it('removes an aborted waiter without consuming the next permit', async () => {
+    const sem = new PrioritySemaphore(1)
+    const release = await sem.acquire(0)
+    const controller = new AbortController()
+    const reason = new Error('canceled')
+    const waiting = sem.acquire(0, controller.signal)
+
+    controller.abort(reason)
+    await expect(waiting).rejects.toBe(reason)
+    release()
+
+    const nextRelease = await sem.acquire(0)
+    nextRelease()
+  })
 })
diff --git a/src/shared/priority-semaphore.ts b/src/shared/priority-semaphore.ts
index 4d31726937d..b7a0a50e06c 100644
--- a/src/shared/priority-semaphore.ts
+++ b/src/shared/priority-semaphore.ts
@@ -1,6 +1,8 @@
 type Waiter = {
   priority: number
   resolve: (release: () => void) => void
+  signal?: AbortSignal
+  onAbort?: () => void
 }
 
 export class PrioritySemaphore {
@@ -11,7 +13,10 @@ export class PrioritySemaphore {
     this.available = concurrency
   }
 
-  acquire(priority: number): Promise<() => void> {
+  acquire(priority: number, signal?: AbortSignal): Promise<() => void> {
+    if (signal?.aborted) {
+      return Promise.reject(signal.reason)
+    }
     if (this.available > 0) {
       this.available--
       let released = false
@@ -24,8 +29,20 @@ export class PrioritySemaphore {
       })
     }
 
-    return new Promise<() => void>((resolve) => {
-      this.waiters.push({ priority, resolve })
+    return new Promise<() => void>((resolve, reject) => {
+      const waiter: Waiter = { priority, resolve, signal }
+      if (signal) {
+        waiter.onAbort = () => {
+          const index = this.waiters.indexOf(waiter)
+          if (index === -1) {
+            return
+          }
+          this.waiters.splice(index, 1)
+          reject(signal.reason)
+        }
+        signal.addEventListener('abort', waiter.onAbort, { once: true })
+      }
+      this.waiters.push(waiter)
     })
   }
 
@@ -45,6 +62,9 @@ export class PrioritySemaphore {
     }
 
     const waiter = this.waiters.splice(bestIdx, 1)[0]
+    if (waiter.signal && waiter.onAbort) {
+      waiter.signal.removeEventListener('abort', waiter.onAbort)
+    }
     let released = false
     waiter.resolve(() => {
       if (released) {

From de851d5ca7b01c0a9bd8d8e2caaea9d1e89635bc Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sat, 29 Aug 2026 16:25:30 -0700
Subject: [PATCH 14/31] perf(terminals): drop disposed queued inspections
 (#17187)

---
 ...dinator-queued-inspection-disposal.test.ts | 81 +++++++++++++++++++
 .../agent-completion-process-monitor.ts       |  1 +
 .../agent-process-inspection-queue.ts         | 11 +++
 3 files changed, 93 insertions(+)
 create mode 100644 src/renderer/src/components/terminal-pane/agent-completion-coordinator-queued-inspection-disposal.test.ts

diff --git a/src/renderer/src/components/terminal-pane/agent-completion-coordinator-queued-inspection-disposal.test.ts b/src/renderer/src/components/terminal-pane/agent-completion-coordinator-queued-inspection-disposal.test.ts
new file mode 100644
index 00000000000..9d83b1d6a93
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/agent-completion-coordinator-queued-inspection-disposal.test.ts
@@ -0,0 +1,81 @@
+import { describe, expect, it, vi } from 'vitest'
+import { createAgentCompletionCoordinator } from './agent-completion-coordinator'
+import {
+  createDeferred,
+  flushAsyncTicks,
+  processResult,
+  useAgentCompletionCoordinatorLifecycle
+} from './agent-completion-coordinator-test-harness'
+import type { RuntimeTerminalProcessInspection } from '@/runtime/runtime-terminal-inspection'
+
+describe('agent completion coordinator queued inspections', () => {
+  useAgentCompletionCoordinatorLifecycle()
+
+  it('drops inspections queued by a disposed coordinator before starting live work', async () => {
+    const blockers = Array.from({ length: 4 }, () =>
+      createDeferred<RuntimeTerminalProcessInspection>()
+    )
+    const blockerInspectors = blockers.map((inspection) => vi.fn(() => inspection.promise))
+    const blockerCoordinators = blockerInspectors.map((inspectProcess, index) =>
+      createAgentCompletionCoordinator({
+        paneKey: `tab-1:blocked-${index}`,
+        getPtyId: () => `pty-blocked-${index}`,
+        getSettings: () => null,
+        inspectProcess,
+        dispatchCompletion: vi.fn(),
+        isLive: () => true
+      })
+    )
+
+    blockerCoordinators.forEach((coordinator) => coordinator.startProcessTracking())
+    await vi.advanceTimersByTimeAsync(2_000)
+    expect(
+      blockerInspectors.every((inspectProcess) => inspectProcess.mock.calls.length === 1)
+    ).toBe(true)
+
+    const staleInspectProcesses = Array.from({ length: 8 }, () =>
+      vi.fn(async () => processResult(null, false))
+    )
+    const staleCoordinators = staleInspectProcesses.map((inspectProcess, index) =>
+      createAgentCompletionCoordinator({
+        paneKey: `tab-1:stale-${index}`,
+        getPtyId: () => `pty-stale-${index}`,
+        getSettings: () => null,
+        inspectProcess,
+        dispatchCompletion: vi.fn(),
+        isLive: () => true
+      })
+    )
+    const liveInspectProcess = vi.fn(async () => processResult(null, false))
+    const liveCoordinator = createAgentCompletionCoordinator({
+      paneKey: 'tab-1:live',
+      getPtyId: () => 'pty-live',
+      getSettings: () => null,
+      inspectProcess: liveInspectProcess,
+      dispatchCompletion: vi.fn(),
+      isLive: () => true
+    })
+
+    for (const [index, coordinator] of staleCoordinators.entries()) {
+      coordinator.observeTitle(`Codex working ${index}`)
+      coordinator.observeTitle(`~/stale-${index}`)
+    }
+    liveCoordinator.observeTitle('Codex working')
+    liveCoordinator.observeTitle('~/live')
+    staleCoordinators.forEach((coordinator) => coordinator.dispose())
+
+    blockers.forEach((inspection) => inspection.resolve(processResult(null, false)))
+    await flushAsyncTicks()
+    // Existing 100ms pump admits live work after blockers release.
+    await vi.advanceTimersByTimeAsync(100)
+    await flushAsyncTicks()
+
+    expect(
+      staleInspectProcesses.every((inspectProcess) => inspectProcess.mock.calls.length === 0)
+    ).toBe(true)
+    expect(liveInspectProcess).toHaveBeenCalledTimes(1)
+
+    blockerCoordinators.forEach((coordinator) => coordinator.dispose())
+    liveCoordinator.dispose()
+  })
+})
diff --git a/src/renderer/src/components/terminal-pane/agent-completion-process-monitor.ts b/src/renderer/src/components/terminal-pane/agent-completion-process-monitor.ts
index 39ca68e1ad4..f0a0492fdfe 100644
--- a/src/renderer/src/components/terminal-pane/agent-completion-process-monitor.ts
+++ b/src/renderer/src/components/terminal-pane/agent-completion-process-monitor.ts
@@ -146,6 +146,7 @@ export function createAgentCompletionProcessMonitor({
     const pendingTitleIdAtRequest = priority === 'pending-title' ? pendingTitle.get()?.id : null
     enqueueAgentProcessInspection({
       priority,
+      canRun: () => !state.disposed,
       run: async () => {
         let inspectedRecognizedAgent = false
         let inspectionSucceeded = false
diff --git a/src/renderer/src/components/terminal-pane/agent-process-inspection-queue.ts b/src/renderer/src/components/terminal-pane/agent-process-inspection-queue.ts
index 5c581ddc652..f7512ad8c60 100644
--- a/src/renderer/src/components/terminal-pane/agent-process-inspection-queue.ts
+++ b/src/renderer/src/components/terminal-pane/agent-process-inspection-queue.ts
@@ -2,6 +2,7 @@ export type InspectionPriority = 'cadence' | 'pending-title'
 
 type InspectionTask = {
   priority: InspectionPriority
+  canRun: () => boolean
   run: () => Promise<void>
 }
 
@@ -37,6 +38,16 @@ function scheduleInspectionPump(delayMs = 0): void {
 }
 
 function pumpInspectionQueue(): void {
+  // Drop disposed tasks before slot/rate accounting.
+  for (let index = inspectionQueue.length - 1; index >= 0; index -= 1) {
+    const task = inspectionQueue[index]
+    if (task && !task.canRun()) {
+      inspectionQueue.splice(index, 1)
+    }
+  }
+  if (inspectionQueue.length === 0) {
+    return
+  }
   const now = Date.now()
   if (!canStartInspection(now)) {
     scheduleInspectionPump(100)

From 0a995cc30d14e980cf738204e49d64dcb8467bd6 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Sat, 29 Aug 2026 18:14:03 -0700
Subject: [PATCH 15/31] Fix md file rendering 2 (#17295)

* Improve markdown rich mode: distinguish HTML tags from placeholders

- Consolidate size limit and unsupported content checks into single function
- Refine HTML/JSX detection to validate against rehype-sanitize's known tag names
- Allow bare placeholders like `<id>` and `<project-id>` in rich mode rendering

* Add decision explainer for markdown rich-mode rendering fix

* rm html explainer
---
 ...orContent.markdown-classification.test.tsx | 15 ++++--
 .../editor/editor-panel-render-model.ts       | 17 +++----
 .../editor/markdown-rich-mode.test.ts         | 44 ++++++++++++++++-
 .../components/editor/markdown-rich-mode.ts   | 49 ++++++++++++++++++-
 4 files changed, 109 insertions(+), 16 deletions(-)

diff --git a/src/renderer/src/components/editor/EditorContent.markdown-classification.test.tsx b/src/renderer/src/components/editor/EditorContent.markdown-classification.test.tsx
index 7d8767071be..4a5600192d3 100644
--- a/src/renderer/src/components/editor/EditorContent.markdown-classification.test.tsx
+++ b/src/renderer/src/components/editor/EditorContent.markdown-classification.test.tsx
@@ -10,11 +10,16 @@ const classifiers = vi.hoisted(() => ({
 }))
 
 vi.mock('./markdown-rich-mode', () => ({
-  getMarkdownRichModeUnsupportedMessage: classifiers.getUnsupportedMessage
-}))
-
-vi.mock('./markdown-rich-size-limit', () => ({
-  exceedsMarkdownRichModeSizeLimit: classifiers.exceedsSizeLimit
+  getMarkdownRichModeEligibility: ({
+    content,
+    sizeOverridden
+  }: {
+    content: string
+    sizeOverridden: boolean
+  }) => ({
+    exceedsSizeLimit: !sizeOverridden && classifiers.exceedsSizeLimit(content),
+    unsupportedMessage: classifiers.getUnsupportedMessage(content)
+  })
 }))
 
 vi.mock('./editor-lazy-views', () => {
diff --git a/src/renderer/src/components/editor/editor-panel-render-model.ts b/src/renderer/src/components/editor/editor-panel-render-model.ts
index 8a479794f83..db03e65efe1 100644
--- a/src/renderer/src/components/editor/editor-panel-render-model.ts
+++ b/src/renderer/src/components/editor/editor-panel-render-model.ts
@@ -13,8 +13,7 @@ import type { EditorToggleValue } from './EditorViewToggle'
 import type { FileContent } from './editor-panel-content-types'
 import { canUseChangesModeForFile } from './editor-panel-file-mode'
 import { getMarkdownRenderMode, type MarkdownRenderState } from './markdown-render-mode'
-import { getMarkdownRichModeUnsupportedMessage } from './markdown-rich-mode'
-import { exceedsMarkdownRichModeSizeLimit } from './markdown-rich-size-limit'
+import { getMarkdownRichModeEligibility } from './markdown-rich-mode'
 
 type StoreState = ReturnType<typeof useAppStore.getState>
 
@@ -143,16 +142,16 @@ export function getEditorPanelRenderModel({
   let inlineMarkdownRenderState: MarkdownRenderState | null = null
   if (canRenderInlineMarkdown) {
     const shouldClassifyRichMode = mdViewMode === 'rich'
-    const exceedsRichModeSizeLimit =
-      shouldClassifyRichMode &&
-      markdownRichModeSizeOverride[activeFile.id] !== true &&
-      exceedsMarkdownRichModeSizeLimit(inlineMarkdownContent)
-    const richModeUnsupportedMessage = shouldClassifyRichMode
-      ? getMarkdownRichModeUnsupportedMessage(inlineMarkdownContent)
+    const richModeEligibility = shouldClassifyRichMode
+      ? getMarkdownRichModeEligibility({
+          content: inlineMarkdownContent,
+          sizeOverridden: markdownRichModeSizeOverride[activeFile.id] === true
+        })
       : null
+    const richModeUnsupportedMessage = richModeEligibility?.unsupportedMessage ?? null
     inlineMarkdownRenderState = {
       renderMode: getMarkdownRenderMode({
-        exceedsRichModeSizeLimit,
+        exceedsRichModeSizeLimit: richModeEligibility?.exceedsSizeLimit ?? false,
         hasRichModeUnsupportedContent: richModeUnsupportedMessage !== null,
         viewMode: mdViewMode
       }),
diff --git a/src/renderer/src/components/editor/markdown-rich-mode.test.ts b/src/renderer/src/components/editor/markdown-rich-mode.test.ts
index e95b6f49c81..25f2e3bd869 100644
--- a/src/renderer/src/components/editor/markdown-rich-mode.test.ts
+++ b/src/renderer/src/components/editor/markdown-rich-mode.test.ts
@@ -1,5 +1,9 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
-import { getMarkdownRichModeUnsupportedMessage } from './markdown-rich-mode'
+import { RICH_MARKDOWN_MAX_SIZE_BYTES } from '../../../../shared/constants'
+import {
+  getMarkdownRichModeEligibility,
+  getMarkdownRichModeUnsupportedMessage
+} from './markdown-rich-mode'
 
 afterEach(() => {
   vi.restoreAllMocks()
@@ -46,6 +50,31 @@ describe('getMarkdownRichModeUnsupportedMessage', () => {
     ).toBeNull()
   })
 
+  it('allows bare lowercase placeholders in prose', () => {
+    expect(
+      getMarkdownRichModeUnsupportedMessage(
+        'Use --host runtime:<id>, --output <path>, and --project <project-id>.\n'
+      )
+    ).toBeNull()
+  })
+
+  it('allows bare lowercase placeholders in large documents', () => {
+    const content = `${'a'.repeat(50_001)}\nUse --host runtime:<id> and --project <project-id>.\n`
+
+    expect(getMarkdownRichModeUnsupportedMessage(content)).toBeNull()
+  })
+
+  it('still blocks large documents with actual html or jsx', () => {
+    const prefix = 'a'.repeat(50_001)
+
+    expect(getMarkdownRichModeUnsupportedMessage(`${prefix}\n<span>text</span>\n`)).not.toBeNull()
+    expect(getMarkdownRichModeUnsupportedMessage(`${prefix}\n<id>text</id>\n`)).not.toBeNull()
+    expect(getMarkdownRichModeUnsupportedMessage(`${prefix}\n<Widget />\n`)).not.toBeNull()
+    expect(
+      getMarkdownRichModeUnsupportedMessage(`${prefix}\n<project-id value="1">\n`)
+    ).not.toBeNull()
+  })
+
   it('allows block html and mdx-like tags by preserving them as passthrough nodes', () => {
     expect(getMarkdownRichModeUnsupportedMessage('<Widget />\n')).toBeNull()
     expect(getMarkdownRichModeUnsupportedMessage('<div>block</div>\n')).toBeNull()
@@ -90,4 +119,17 @@ describe('getMarkdownRichModeUnsupportedMessage', () => {
     )
     expect(usedGlobalHtmlFragmentMatch).toBe(false)
   })
+
+  it('keeps unsupported content blocked when it also exceeds the size limit', () => {
+    const content = `${'a'.repeat(RICH_MARKDOWN_MAX_SIZE_BYTES + 1)}<Widget />`
+
+    expect(getMarkdownRichModeEligibility({ content, sizeOverridden: false })).toEqual({
+      exceedsSizeLimit: true,
+      unsupportedMessage: expect.any(String)
+    })
+    expect(getMarkdownRichModeEligibility({ content, sizeOverridden: true })).toEqual({
+      exceedsSizeLimit: false,
+      unsupportedMessage: expect.any(String)
+    })
+  })
 })
diff --git a/src/renderer/src/components/editor/markdown-rich-mode.ts b/src/renderer/src/components/editor/markdown-rich-mode.ts
index 694a8a7ee5f..4764892a4ea 100644
--- a/src/renderer/src/components/editor/markdown-rich-mode.ts
+++ b/src/renderer/src/components/editor/markdown-rich-mode.ts
@@ -1,5 +1,7 @@
+import { defaultSchema } from 'rehype-sanitize'
 import { getRichMarkdownRoundTripOutput } from './markdown-round-trip'
 import { extractFrontMatter } from './markdown-frontmatter'
+import { exceedsMarkdownRichModeSizeLimit } from './markdown-rich-size-limit'
 import { translate } from '@/i18n/i18n'
 
 export type MarkdownRichModeUnsupportedReason =
@@ -14,6 +16,13 @@ type UnsupportedMatch = {
   pattern: RegExp
 }
 
+export type MarkdownRichModeEligibility = {
+  exceedsSizeLimit: boolean
+  unsupportedMessage: string | null
+}
+
+const KNOWN_MARKDOWN_HTML_TAG_NAMES = new Set(defaultSchema.tagNames ?? [])
+
 const UNSUPPORTED_PATTERNS: UnsupportedMatch[] = [
   {
     reason: 'html-or-jsx',
@@ -66,7 +75,7 @@ export function getMarkdownRichModeUnsupportedMessage(content: string): string |
   // opinion when HTML is detected, to verify the HTML survives the round-trip
   // before blocking the user from rich mode.
   const htmlMatcher = UNSUPPORTED_PATTERNS.find((m) => m.reason === 'html-or-jsx')
-  const hasHtml = htmlMatcher && htmlMatcher.pattern.test(contentWithoutCode)
+  const hasHtml = htmlMatcher && hasHtmlOrJsx(contentWithoutCode, htmlMatcher.pattern)
 
   for (const matcher of UNSUPPORTED_PATTERNS) {
     if (matcher.reason === 'html-or-jsx') {
@@ -91,6 +100,44 @@ export function getMarkdownRichModeUnsupportedMessage(content: string): string |
   return null
 }
 
+export function getMarkdownRichModeEligibility({
+  content,
+  sizeOverridden
+}: {
+  content: string
+  sizeOverridden: boolean
+}): MarkdownRichModeEligibility {
+  const exceedsSizeLimit = !sizeOverridden && exceedsMarkdownRichModeSizeLimit(content)
+  return {
+    exceedsSizeLimit,
+    unsupportedMessage: getMarkdownRichModeUnsupportedMessage(content)
+  }
+}
+
+function hasHtmlOrJsx(content: string, pattern: RegExp): boolean {
+  for (const match of content.matchAll(new RegExp(pattern, 'g'))) {
+    if (isHtmlOrJsxFragment(match[0])) {
+      return true
+    }
+  }
+  return false
+}
+
+function isHtmlOrJsxFragment(fragment: string): boolean {
+  if (fragment.startsWith('<!--') || fragment.startsWith('</')) {
+    return true
+  }
+
+  const tagMatch = fragment.match(/^<([A-Za-z][\w.:-]*)/)
+  const tagName = tagMatch?.[1]
+  if (!tagName) {
+    return false
+  }
+
+  const suffix = fragment.slice(tagName.length + 1, -1)
+  return suffix.length > 0 || KNOWN_MARKDOWN_HTML_TAG_NAMES.has(tagName.toLowerCase())
+}
+
 function stripMarkdownCode(content: string): string {
   let sanitized = ''
   let activeFence: '`' | '~' | null = null

From 4e9ef12861189ef149acd0c3a5f13a423a840dfe Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sat, 29 Aug 2026 19:41:01 -0700
Subject: [PATCH 16/31] test(persistence): give the 130k-leaf pane alias scale
 test headroom (#17323)

The test runs ~9-15s locally but times out against the 30s default on a
loaded CI shard, flaking the node 24 test shard and the verify gate.
---
 src/main/persistence-pane-identity-migration.test.ts | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/main/persistence-pane-identity-migration.test.ts b/src/main/persistence-pane-identity-migration.test.ts
index 606e1599fdf..c9a6fc4e592 100644
--- a/src/main/persistence-pane-identity-migration.test.ts
+++ b/src/main/persistence-pane-identity-migration.test.ts
@@ -507,6 +507,7 @@ describe('Store', () => {
     )
   })
 
+  // ~9s locally; the 30s default timeout leaves too little headroom on a loaded CI shard.
   it('loads legacy pane aliases from very large persisted split layouts', async () => {
     const leafCount = 130_000
     writeDataFile({
@@ -561,7 +562,7 @@ describe('Store', () => {
         (entry) => entry.ptyId === 'large-pty' && entry.legacyPaneKey === `tab1:${leafCount}`
       )
     ).toBe(true)
-  })
+  }, 120_000)
 
   it('converts unambiguous dev migration rows into persisted aliases', async () => {
     const stablePaneKey = makePaneKey('tab1', TEST_LEAF_1)

From 3457acb6476af0b71e8d66b3664cf468a89aa4c3 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sat, 29 Aug 2026 19:42:56 -0700
Subject: [PATCH 17/31] fix(memory): hydrate retained PTYs before diagnostics
 (#17308)

Co-authored-by: OrcaWin <293788423+OrcaWin@users.noreply.github.com>
---
 .../git/worktree-scan-cache-sharing.test.ts   |  14 +
 src/main/index.ts                             |   5 +-
 .../ipc/pty/register-headless-runtime.test.ts |  41 ++
 src/main/ipc/pty/register-headless-runtime.ts |   4 +-
 .../memory/hydrate-local-pty-registry.test.ts | 577 ++++++++++++++++--
 src/main/memory/hydrate-local-pty-registry.ts | 375 ++++++++----
 src/main/orcad/orcad-entry.ts                 |   2 +-
 src/main/repo-worktrees.test.ts               |  79 ++-
 src/main/repo-worktrees.ts                    |  17 +-
 .../startup/desktop-startup-ordering.test.ts  |   1 +
 .../headless-pty-hydration-ordering.test.ts   |  52 ++
 .../serve-desktop-activation-wiring.test.ts   |  11 +-
 ...windows-desktop-shell-path-startup.test.ts |  24 +
 .../windows-desktop-shell-path-startup.ts     |   2 +
 .../attach-main-window-services.test.ts       |  17 +-
 .../window/attach-main-window-services.ts     |  10 +-
 16 files changed, 1044 insertions(+), 187 deletions(-)
 create mode 100644 src/main/ipc/pty/register-headless-runtime.test.ts
 create mode 100644 src/main/startup/headless-pty-hydration-ordering.test.ts

diff --git a/src/main/git/worktree-scan-cache-sharing.test.ts b/src/main/git/worktree-scan-cache-sharing.test.ts
index cee700b8597..14fd5e86a90 100644
--- a/src/main/git/worktree-scan-cache-sharing.test.ts
+++ b/src/main/git/worktree-scan-cache-sharing.test.ts
@@ -30,6 +30,7 @@ import {
   _getWorktreeScanCacheSizesForTests,
   _resetWorktreeScanCacheForTests,
   listWorktrees,
+  listWorktreesStrict,
   moveWorktree,
   removeWorktree,
   WORKTREE_LIST_TIMEOUT_MS
@@ -120,6 +121,19 @@ describe('listWorktrees in-flight sharing', () => {
     }
   })
 
+  it('distinguishes fail-soft empty results from strict scan failures', async () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    try {
+      const failure = new Error('git spawn timed out')
+      gitExecFileAsyncMock.mockRejectedValue(failure)
+
+      await expect(listWorktrees('/repo')).resolves.toEqual([])
+      await expect(listWorktreesStrict('/repo')).rejects.toBe(failure)
+    } finally {
+      warnSpy.mockRestore()
+    }
+  })
+
   it('does not share scans across different repos', async () => {
     gitExecFileAsyncMock.mockImplementation((_args: string[], options: { cwd: string }) =>
       Promise.resolve({
diff --git a/src/main/index.ts b/src/main/index.ts
index 7df14b894a1..00b059885ad 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -3389,12 +3389,12 @@ void app.whenReady().then(async () => {
   let desktopWindow: BrowserWindow | null = null
   if (process.platform === 'win32' && app.isPackaged && !serveOptions) {
     const desktopStartup = startWindowsDesktopBeforeShellPathReady({
+      bindServices: bindTerminalRuntimeStartupServices,
       openWindow: () => openMainWindow({ revealOnDidFinishLoad: true }),
       shellPathReady,
       startServices: startTerminalRuntimeStartupServices
     })
     desktopWindow = desktopStartup.window
-    bindTerminalRuntimeStartupServices(desktopStartup.services)
   } else {
     await shellPathReady
     bindTerminalRuntimeStartupServices(Promise.resolve(startTerminalRuntimeStartupServices()))
@@ -3410,7 +3410,8 @@ void app.whenReady().then(async () => {
     })
     // Why: headless PTYs must not start on the fallback provider, then get swept when an activated renderer registers desktop lifecycle handlers.
     await localPtyStartupReady
-    registerHeadlessPtyRuntime(
+    await localPtyProviderStartupReady
+    await registerHeadlessPtyRuntime(
       runtime,
       prepareCodexRuntimeHomeForLaunch,
       () => store!.getSettings(),
diff --git a/src/main/ipc/pty/register-headless-runtime.test.ts b/src/main/ipc/pty/register-headless-runtime.test.ts
new file mode 100644
index 00000000000..7063ec2454d
--- /dev/null
+++ b/src/main/ipc/pty/register-headless-runtime.test.ts
@@ -0,0 +1,41 @@
+import { describe, expect, it, vi } from 'vitest'
+
+const { hydrateMock, registerHandlersMock } = vi.hoisted(() => ({
+  hydrateMock: vi.fn(),
+  registerHandlersMock: vi.fn()
+}))
+
+vi.mock('./register-handlers', () => ({
+  registerPtyHandlers: registerHandlersMock
+}))
+
+vi.mock('../../memory/hydrate-local-pty-registry', () => ({
+  hydrateLocalPtyRegistryAtBoot: hydrateMock
+}))
+
+import { registerHeadlessPtyRuntime } from './register-headless-runtime'
+
+describe('registerHeadlessPtyRuntime', () => {
+  it('registers handlers before awaiting registry hydration', async () => {
+    let resolveHydration!: () => void
+    const hydration = new Promise<void>((resolve) => {
+      resolveHydration = resolve
+    })
+    const events: string[] = []
+    registerHandlersMock.mockImplementation(() => events.push('handlers'))
+    hydrateMock.mockImplementation(() => {
+      events.push('hydrate')
+      return hydration
+    })
+    const store = {} as never
+
+    const ready = registerHeadlessPtyRuntime({} as never, undefined, undefined, undefined, store)
+
+    expect(events).toEqual(['handlers', 'hydrate'])
+    expect(registerHandlersMock).toHaveBeenCalledOnce()
+    expect(hydrateMock).toHaveBeenCalledWith(store)
+
+    resolveHydration()
+    await ready
+  })
+})
diff --git a/src/main/ipc/pty/register-headless-runtime.ts b/src/main/ipc/pty/register-headless-runtime.ts
index f380482a079..2212fbfac3a 100644
--- a/src/main/ipc/pty/register-headless-runtime.ts
+++ b/src/main/ipc/pty/register-headless-runtime.ts
@@ -9,6 +9,7 @@ import type {
   PrepareCodexSessionResume
 } from './host-env/types'
 import { registerPtyHandlers } from './register-handlers'
+import { hydrateLocalPtyRegistryAtBoot } from '../../memory/hydrate-local-pty-registry'
 
 export function registerHeadlessPtyRuntime(
   runtime: OrcaRuntimeService,
@@ -21,7 +22,7 @@ export function registerHeadlessPtyRuntime(
     onCodexHomePtySpawned?: (args: CodexHomePtySpawnedLifecycleArgs) => void
     onPtyExit?: (id: string, exitSequence: number) => void
   }
-): void {
+): Promise<void> {
   // Why: headless `orca serve` has no renderer window but still needs the same PTY handlers so remote clients can drive terminals.
   // Why a fake rather than null: `registerPtyHandlers` takes a non-null BrowserWindow. `isDestroyed: () => true`
   // is what makes that safe — every renderer-liveness guard reads it and skips, so no send is ever attempted.
@@ -44,4 +45,5 @@ export function registerHeadlessPtyRuntime(
     store,
     { prepareCodexSessionResume, ...lifecycle }
   )
+  return store ? hydrateLocalPtyRegistryAtBoot(store) : Promise.resolve()
 }
diff --git a/src/main/memory/hydrate-local-pty-registry.test.ts b/src/main/memory/hydrate-local-pty-registry.test.ts
index 7b9a90bfb73..a7a03293832 100644
--- a/src/main/memory/hydrate-local-pty-registry.test.ts
+++ b/src/main/memory/hydrate-local-pty-registry.test.ts
@@ -11,7 +11,10 @@
  */
 
 import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { resolveFolderWorkspaceHost } from '../../shared/folder-workspace-execution-host'
+import type { FolderWorkspace } from '../../shared/folder-workspace-types'
 import type { Repo } from '../../shared/repo-types'
+import type { WorktreeMeta } from '../../shared/worktree/meta-types'
 import type { SessionInfo } from '../daemon/types'
 import type { DaemonPtyAdapter } from '../daemon/daemon-pty-adapter'
 import type { Store } from '../persistence'
@@ -23,7 +26,6 @@ import type {
 } from './pty-registry'
 
 const LARGE_SESSION_COUNT = 150_000
-
 // Why: the hydrator pulls the daemon provider through this module-level
 // getter. Stubbing it lets us drive the offline / throwing / live paths
 // without spinning up real sockets.
@@ -32,32 +34,53 @@ vi.mock('../daemon/daemon-init', () => ({
   getDaemonProvider: () => getDaemonProviderMock()
 }))
 
-// Why: the hydrator builds its worktreeId → connectionId map through
-// listRepoWorktrees(repo). The git I/O is out of scope for this unit; the mock
-// also lets count tests prove repos without live sessions launch no Git work.
-const listRepoWorktreesMock = vi.fn()
-vi.mock('../repo-worktrees', () => ({
-  listRepoWorktrees: (repo: unknown) => listRepoWorktreesMock(repo)
+const getLocalProjectWorktreeGitOptionsMock = vi.fn()
+vi.mock('../project-runtime-git-options', () => ({
+  getLocalProjectWorktreeGitOptions: (store: unknown, repo: unknown) =>
+    getLocalProjectWorktreeGitOptionsMock(store, repo)
 }))
 
-// Why: hydrateLocalPtyRegistryAtBoot accepts `Pick<Store, 'getRepos'>` and
-// the hydrator only reads `id` + `connectionId` off each Repo, but Repo's
-// required fields (path, displayName, badgeColor, addedAt) still have to be
-// present at the type level. Filling them with placeholder values keeps the
-// test schema-compliant without coupling to anything the hydrator doesn't
-// touch.
+// Why: the hydrator builds its worktreeId → connectionId map through
+// listLocalRepoWorktreesStrict(repo). The git I/O is out of scope for this
+// unit; the mock also lets count tests prove repos without live sessions
+// launch no Git work.
+const listLocalRepoWorktreesStrictMock = vi.fn()
+vi.mock('../repo-worktrees', () => ({
+  listLocalRepoWorktreesStrict: (
+    repo: unknown,
+    options?: { signal?: AbortSignal; wslDistro?: string }
+  ) => listLocalRepoWorktreesStrictMock(repo, options)
+}))
+
+// The runtime option helper accepts Store; mocks keep this fixture scoped to hydration reads.
 function makeStore(
-  repos: { id: string; connectionId?: string | null }[] = []
-): Pick<Store, 'getRepos'> {
+  repos: {
+    id: string
+    connectionId?: string | null
+    executionHostId?: Repo['executionHostId']
+    kind?: Repo['kind']
+    path?: string
+  }[] = [],
+  worktreeMeta: Record<string, WorktreeMeta> = {}
+): Store {
   const built: Repo[] = repos.map((r) => ({
     id: r.id,
-    path: `/tmp/${r.id}`,
+    path: r.path ?? `/tmp/${r.id}`,
     displayName: r.id,
     badgeColor: '#000000',
     addedAt: 0,
-    connectionId: r.connectionId ?? null
+    connectionId: r.connectionId ?? null,
+    executionHostId: r.executionHostId ?? null,
+    kind: r.kind
   }))
-  return { getRepos: () => built }
+  return {
+    getRepos: () => built,
+    getAllWorktreeMeta: () => worktreeMeta,
+    getAllWorktreeMetaForHost: (hostId) =>
+      Object.fromEntries(
+        Object.entries(worktreeMeta).filter(([, meta]) => !meta.hostId || meta.hostId === hostId)
+      )
+  } as Store
 }
 
 function makeProvider(sessions: SessionInfo[]): Pick<DaemonPtyAdapter, 'listSessions'> {
@@ -66,6 +89,12 @@ function makeProvider(sessions: SessionInfo[]): Pick<DaemonPtyAdapter, 'listSess
   }
 }
 
+function makeProviderGroup(adapters: Pick<DaemonPtyAdapter, 'listSessions'>[]): {
+  getAllAdapters: () => Pick<DaemonPtyAdapter, 'listSessions'>[]
+} {
+  return { getAllAdapters: () => adapters }
+}
+
 function makeLocalSessions(repoId: string, worktreePath: string, count: number): SessionInfo[] {
   const sessions: SessionInfo[] = []
   for (let index = 0; index < count; index += 1) {
@@ -98,6 +127,8 @@ function createDeferred<T>(): {
 // a coherent pair.
 async function loadFresh(): Promise<{
   hydrate: typeof HydrateFn
+  deadlineMs: number
+  gitEnumerationConcurrency: number
   listRegisteredPtys: typeof ListFn
   registerPty: typeof RegisterFn
   unregisterPty: typeof UnregisterFn
@@ -107,6 +138,8 @@ async function loadFresh(): Promise<{
   const registryMod = await import('./pty-registry')
   return {
     hydrate: hydrateMod.hydrateLocalPtyRegistryAtBoot,
+    deadlineMs: hydrateMod.LOCAL_PTY_REGISTRY_BOOT_HYDRATION_DEADLINE_MS,
+    gitEnumerationConcurrency: hydrateMod.LOCAL_PTY_REGISTRY_GIT_ENUMERATION_CONCURRENCY,
     listRegisteredPtys: registryMod.listRegisteredPtys,
     registerPty: registryMod.registerPty,
     unregisterPty: registryMod.unregisterPty
@@ -116,7 +149,8 @@ async function loadFresh(): Promise<{
 describe('hydrateLocalPtyRegistryAtBoot', () => {
   beforeEach(() => {
     getDaemonProviderMock.mockReset()
-    listRepoWorktreesMock.mockReset()
+    getLocalProjectWorktreeGitOptionsMock.mockReset().mockReturnValue({})
+    listLocalRepoWorktreesStrictMock.mockReset()
   })
 
   it('no-op when daemon provider is null at first call (retries on later activation)', async () => {
@@ -126,19 +160,19 @@ describe('hydrateLocalPtyRegistryAtBoot', () => {
     await hydrate(makeStore([{ id: 'repo-a' }]))
 
     expect(listRegisteredPtys()).toHaveLength(0)
-    expect(listRepoWorktreesMock).not.toHaveBeenCalled()
+    expect(listLocalRepoWorktreesStrictMock).not.toHaveBeenCalled()
 
     // Why: the design says the hasHydrated guard must stay false until a
     // provider is obtained, so a later macOS dock re-activation can retry.
     // Provider becomes available; second call should now perform the pass.
     const provider = makeProvider([])
     getDaemonProviderMock.mockReturnValue(provider)
-    listRepoWorktreesMock.mockResolvedValue([])
+    listLocalRepoWorktreesStrictMock.mockResolvedValue([])
 
     await hydrate(makeStore([{ id: 'repo-a' }]))
 
     expect(provider.listSessions).toHaveBeenCalledTimes(1)
-    expect(listRepoWorktreesMock).not.toHaveBeenCalled()
+    expect(listLocalRepoWorktreesStrictMock).not.toHaveBeenCalled()
   })
 
   it('catches provider.listSessions rejection and does not throw', async () => {
@@ -147,7 +181,9 @@ describe('hydrateLocalPtyRegistryAtBoot', () => {
       listSessions: vi.fn().mockRejectedValue(new Error('socket EPIPE'))
     }
     getDaemonProviderMock.mockReturnValue(provider)
-    listRepoWorktreesMock.mockResolvedValue([{ path: '/local/Triton', isMainWorktree: true }])
+    listLocalRepoWorktreesStrictMock.mockResolvedValue([
+      { path: '/local/Triton', isMainWorktree: true }
+    ])
 
     // Why: the renderer-side step-2 merge fallback covers this case. The
     // hydrator must not surface the failure to the caller — it logs and
@@ -157,7 +193,234 @@ describe('hydrateLocalPtyRegistryAtBoot', () => {
     warnSpy.mockRestore()
 
     expect(listRegisteredPtys()).toHaveLength(0)
-    expect(listRepoWorktreesMock).not.toHaveBeenCalled()
+    expect(listLocalRepoWorktreesStrictMock).not.toHaveBeenCalled()
+  })
+
+  it('coalesces concurrent calls onto one inventory attempt', async () => {
+    const { hydrate } = await loadFresh()
+    const inventory = createDeferred<SessionInfo[]>()
+    const provider = { listSessions: vi.fn(() => inventory.promise) }
+    getDaemonProviderMock.mockReturnValue(provider)
+
+    const first = hydrate(makeStore())
+    const second = hydrate(makeStore())
+
+    expect(first).toBe(second)
+    expect(provider.listSessions).toHaveBeenCalledOnce()
+
+    inventory.resolve([])
+    await first
+  })
+
+  it('retries after worktree enumeration throws', async () => {
+    const { hydrate, listRegisteredPtys } = await loadFresh()
+    const ptyId = 'repo-a::/local/repo-a@@00000001'
+    const provider = makeProvider([
+      { sessionId: ptyId, pid: 4001, cwd: '/local/repo-a' } as unknown as SessionInfo
+    ])
+    getDaemonProviderMock.mockReturnValue(provider)
+    listLocalRepoWorktreesStrictMock
+      .mockRejectedValueOnce(new Error('git unavailable'))
+      .mockResolvedValue([
+        { path: '/local/repo-a', head: '', branch: '', isBare: false, isMainWorktree: true }
+      ])
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    await hydrate(makeStore([{ id: 'repo-a' }]))
+    expect(listRegisteredPtys()).toHaveLength(0)
+    expect(listLocalRepoWorktreesStrictMock).toHaveBeenCalledOnce()
+
+    await hydrate(makeStore([{ id: 'repo-a' }]))
+    warnSpy.mockRestore()
+
+    expect(listRegisteredPtys()).toEqual([expect.objectContaining({ ptyId })])
+    expect(listLocalRepoWorktreesStrictMock).toHaveBeenCalledTimes(2)
+  })
+
+  it('forwards the WSL project runtime and live deadline signal to strict enumeration', async () => {
+    const { hydrate } = await loadFresh()
+    const ptyId = 'repo-a::/mnt/c/repo-a@@00000001'
+    const store = makeStore([{ id: 'repo-a', path: '/mnt/c/repo-a' }])
+    getDaemonProviderMock.mockReturnValue(
+      makeProvider([
+        { sessionId: ptyId, pid: 4001, cwd: '/mnt/c/repo-a' } as unknown as SessionInfo
+      ])
+    )
+    getLocalProjectWorktreeGitOptionsMock.mockReturnValue({ wslDistro: 'Ubuntu' })
+    listLocalRepoWorktreesStrictMock.mockResolvedValue([
+      { path: '/mnt/c/repo-a', head: '', branch: '', isBare: false, isMainWorktree: true }
+    ])
+
+    await hydrate(store)
+
+    const [repo, options] = listLocalRepoWorktreesStrictMock.mock.calls[0] as [
+      Repo,
+      { signal: AbortSignal; wslDistro?: string }
+    ]
+    expect(getLocalProjectWorktreeGitOptionsMock).toHaveBeenCalledWith(store, repo)
+    expect(options.wslDistro).toBe('Ubuntu')
+    expect(options.signal).toBeInstanceOf(AbortSignal)
+    expect(options.signal.aborted).toBe(false)
+  })
+
+  it('resolves by the boot deadline and lets a later call retry stalled enumeration', async () => {
+    vi.useFakeTimers()
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    try {
+      const { hydrate, deadlineMs, listRegisteredPtys } = await loadFresh()
+      const ptyId = 'repo-a::/local/repo-a@@00000001'
+      const provider = makeProvider([
+        { sessionId: ptyId, pid: 4001, cwd: '/local/repo-a' } as unknown as SessionInfo
+      ])
+      const signals: AbortSignal[] = []
+      getDaemonProviderMock.mockReturnValue(provider)
+      listLocalRepoWorktreesStrictMock
+        .mockImplementationOnce((_repo: Repo, options?: { signal?: AbortSignal }) => {
+          if (options?.signal) {
+            signals.push(options.signal)
+          }
+          return new Promise(() => {})
+        })
+        .mockImplementation(async (_repo: Repo, options?: { signal?: AbortSignal }) => {
+          if (options?.signal) {
+            signals.push(options.signal)
+          }
+          return [
+            {
+              path: '/local/repo-a',
+              head: '',
+              branch: '',
+              isBare: false,
+              isMainWorktree: true
+            }
+          ]
+        })
+
+      let settled = false
+      const first = hydrate(makeStore([{ id: 'repo-a' }])).then(() => {
+        settled = true
+      })
+      await vi.advanceTimersByTimeAsync(deadlineMs - 1)
+      expect(settled).toBe(false)
+
+      await vi.advanceTimersByTimeAsync(1)
+      expect(settled).toBe(true)
+      await first
+      expect(signals[0]?.aborted).toBe(true)
+
+      await hydrate(makeStore([{ id: 'repo-a' }]))
+
+      expect(listLocalRepoWorktreesStrictMock).toHaveBeenCalledTimes(2)
+      expect(listRegisteredPtys()).toEqual([expect.objectContaining({ ptyId })])
+      expect(vi.getTimerCount()).toBe(0)
+    } finally {
+      warnSpy.mockRestore()
+      vi.clearAllTimers()
+      vi.useRealTimers()
+    }
+  })
+
+  it('bounds concurrent Git worktree enumeration', async () => {
+    const { hydrate, gitEnumerationConcurrency } = await loadFresh()
+    const repoCount = 6
+    const gate = createDeferred<void>()
+    let active = 0
+    let maxActive = 0
+    const sessions = Array.from({ length: repoCount }, (_, index) => {
+      const repoId = `repo-${index}`
+      return {
+        sessionId: `${repoId}::/local/${repoId}@@0000000${index}`,
+        pid: 4000 + index,
+        cwd: `/local/${repoId}`
+      } as unknown as SessionInfo
+    })
+    getDaemonProviderMock.mockReturnValue(makeProvider(sessions))
+    listLocalRepoWorktreesStrictMock.mockImplementation(async (repo: Repo) => {
+      active += 1
+      maxActive = Math.max(maxActive, active)
+      await gate.promise
+      active -= 1
+      return [
+        { path: `/local/${repo.id}`, head: '', branch: '', isBare: false, isMainWorktree: true }
+      ]
+    })
+
+    const hydration = hydrate(
+      makeStore(Array.from({ length: repoCount }, (_, index) => ({ id: `repo-${index}` })))
+    )
+    let startedBeforeRelease = 0
+    try {
+      await vi.waitFor(() =>
+        expect(listLocalRepoWorktreesStrictMock).toHaveBeenCalledTimes(gitEnumerationConcurrency)
+      )
+      startedBeforeRelease = listLocalRepoWorktreesStrictMock.mock.calls.length
+    } finally {
+      gate.resolve(undefined)
+      await hydration
+    }
+
+    expect(startedBeforeRelease).toBe(gitEnumerationConcurrency)
+    expect(maxActive).toBe(gitEnumerationConcurrency)
+  })
+
+  it('registers successful adapter rows but retries a failed adapter', async () => {
+    const { hydrate, listRegisteredPtys } = await loadFresh()
+    const sessionA = {
+      sessionId: 'repo-a::/local/repo-a@@00000001',
+      pid: 4001,
+      cwd: '/local/repo-a'
+    } as unknown as SessionInfo
+    const sessionB = {
+      sessionId: 'repo-b::/local/repo-b@@00000002',
+      pid: 4002,
+      cwd: '/local/repo-b'
+    } as unknown as SessionInfo
+    const adapterA = makeProvider([sessionA])
+    const adapterB = {
+      listSessions: vi
+        .fn()
+        .mockRejectedValueOnce(new Error('legacy unavailable'))
+        .mockRejectedValueOnce(new Error('legacy unavailable'))
+        .mockResolvedValue([sessionB])
+    }
+    getDaemonProviderMock.mockReturnValue(makeProviderGroup([adapterA, adapterB]))
+    listLocalRepoWorktreesStrictMock.mockImplementation(async (repo: Repo) => [
+      { path: `/local/${repo.id}`, head: '', branch: '', isBare: false, isMainWorktree: true }
+    ])
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const store = makeStore([{ id: 'repo-a' }, { id: 'repo-b' }])
+
+    await hydrate(store)
+    expect(listRegisteredPtys().map((pty) => pty.ptyId)).toEqual([sessionA.sessionId])
+
+    await hydrate(store)
+    warnSpy.mockRestore()
+
+    expect(
+      listRegisteredPtys()
+        .map((pty) => pty.ptyId)
+        .sort()
+    ).toEqual([sessionA.sessionId, sessionB.sessionId].sort())
+  })
+
+  it('retries an all-adapter inventory failure and latches only the complete retry', async () => {
+    const { hydrate } = await loadFresh()
+    const firstAdapter = {
+      listSessions: vi.fn().mockRejectedValueOnce(new Error('current down')).mockResolvedValue([])
+    }
+    const secondAdapter = {
+      listSessions: vi.fn().mockRejectedValueOnce(new Error('legacy down')).mockResolvedValue([])
+    }
+    getDaemonProviderMock.mockReturnValue(makeProviderGroup([firstAdapter, secondAdapter]))
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    await hydrate(makeStore())
+    await hydrate(makeStore())
+    await hydrate(makeStore())
+    warnSpy.mockRestore()
+
+    expect(firstAdapter.listSessions).toHaveBeenCalledTimes(2)
+    expect(secondAdapter.listSessions).toHaveBeenCalledTimes(2)
   })
 
   it('does not clobber a pre-existing registry pid with a null pid from listSessions', async () => {
@@ -183,7 +446,7 @@ describe('hydrateLocalPtyRegistryAtBoot', () => {
       { sessionId: ptyId, pid: null, cwd: '/local/Triton' } as unknown as SessionInfo
     ])
     getDaemonProviderMock.mockReturnValue(provider)
-    listRepoWorktreesMock.mockResolvedValue([
+    listLocalRepoWorktreesStrictMock.mockResolvedValue([
       { path: '/local/Triton', head: '', branch: '', isBare: false, isMainWorktree: true }
     ])
 
@@ -193,7 +456,7 @@ describe('hydrateLocalPtyRegistryAtBoot', () => {
     expect(entry).toBeDefined()
     expect(entry!.pid).toBe(12345)
     expect(entry!.paneKey).toBe('tab-1:1')
-    expect(listRepoWorktreesMock).not.toHaveBeenCalled()
+    expect(listLocalRepoWorktreesStrictMock).not.toHaveBeenCalled()
   })
 
   it('does not clobber a pty:spawn registration that arrives during worktree enumeration', async () => {
@@ -207,10 +470,10 @@ describe('hydrateLocalPtyRegistryAtBoot', () => {
       createDeferred<
         { path: string; head: string; branch: string; isBare: boolean; isMainWorktree: boolean }[]
       >()
-    listRepoWorktreesMock.mockReturnValue(worktrees.promise)
+    listLocalRepoWorktreesStrictMock.mockReturnValue(worktrees.promise)
 
     const hydration = hydrate(makeStore([{ id: 'repo-a', connectionId: null }]))
-    await vi.waitFor(() => expect(listRepoWorktreesMock).toHaveBeenCalledTimes(1))
+    await vi.waitFor(() => expect(listLocalRepoWorktreesStrictMock).toHaveBeenCalledTimes(1))
     registerPty({
       ptyId,
       worktreeId: 'repo-a::/local/Triton',
@@ -244,10 +507,10 @@ describe('hydrateLocalPtyRegistryAtBoot', () => {
       createDeferred<
         { path: string; head: string; branch: string; isBare: boolean; isMainWorktree: boolean }[]
       >()
-    listRepoWorktreesMock.mockReturnValue(worktrees.promise)
+    listLocalRepoWorktreesStrictMock.mockReturnValue(worktrees.promise)
 
     const hydration = hydrate(makeStore([{ id: 'repo-a', connectionId: null }]))
-    await vi.waitFor(() => expect(listRepoWorktreesMock).toHaveBeenCalledTimes(1))
+    await vi.waitFor(() => expect(listLocalRepoWorktreesStrictMock).toHaveBeenCalledTimes(1))
     unregisterPty(ptyId)
     worktrees.resolve([
       { path: '/local/Triton', head: '', branch: '', isBare: false, isMainWorktree: true }
@@ -266,7 +529,7 @@ describe('hydrateLocalPtyRegistryAtBoot', () => {
       { sessionId: ptyId, pid: 999, cwd: '/remote/Stingray' } as unknown as SessionInfo
     ])
     getDaemonProviderMock.mockReturnValue(provider)
-    listRepoWorktreesMock.mockResolvedValue([
+    listLocalRepoWorktreesStrictMock.mockResolvedValue([
       { path: '/remote/Stingray', head: '', branch: '', isBare: false, isMainWorktree: true }
     ])
 
@@ -276,7 +539,24 @@ describe('hydrateLocalPtyRegistryAtBoot', () => {
     // visible to the local process sampler. Mirrors the spawn-time gate
     // around `registerPty` in `pty.ts`'s `pty:spawn` handler.
     expect(listRegisteredPtys()).toHaveLength(0)
-    expect(listRepoWorktreesMock).not.toHaveBeenCalled()
+    expect(listLocalRepoWorktreesStrictMock).not.toHaveBeenCalled()
+  })
+
+  it('skips paired-runtime repos even when connectionId is absent', async () => {
+    const { hydrate, listRegisteredPtys } = await loadFresh()
+    const provider = makeProvider([
+      {
+        sessionId: 'repo-runtime::/runtime/Stingray@@feedface',
+        pid: 999,
+        cwd: '/runtime/Stingray'
+      } as unknown as SessionInfo
+    ])
+    getDaemonProviderMock.mockReturnValue(provider)
+
+    await hydrate(makeStore([{ id: 'repo-runtime', executionHostId: 'runtime:environment-1' }]))
+
+    expect(listRegisteredPtys()).toHaveLength(0)
+    expect(listLocalRepoWorktreesStrictMock).not.toHaveBeenCalled()
   })
 
   it('registers a local session whose worktree is in the store with the daemon-published pid', async () => {
@@ -287,7 +567,7 @@ describe('hydrateLocalPtyRegistryAtBoot', () => {
       { sessionId: ptyId, pid: 4242, cwd: '/local/Triton' } as unknown as SessionInfo
     ])
     getDaemonProviderMock.mockReturnValue(provider)
-    listRepoWorktreesMock.mockResolvedValue([
+    listLocalRepoWorktreesStrictMock.mockResolvedValue([
       { path: '/local/Triton', head: '', branch: '', isBare: false, isMainWorktree: true }
     ])
 
@@ -299,6 +579,221 @@ describe('hydrateLocalPtyRegistryAtBoot', () => {
     expect(entry!.worktreeId).toBe('repo-a::/local/Triton')
   })
 
+  it('matches Windows worktree path spelling while preserving the daemon worktree id', async () => {
+    const { hydrate, listRegisteredPtys } = await loadFresh()
+    const worktreeId = 'repo-a::C:/Users/Neil/Orca'
+    const ptyId = `${worktreeId}@@cafebabe`
+    getDaemonProviderMock.mockReturnValue(
+      makeProvider([
+        { sessionId: ptyId, pid: 4242, cwd: 'C:/Users/Neil/Orca' } as unknown as SessionInfo
+      ])
+    )
+    listLocalRepoWorktreesStrictMock.mockResolvedValue([
+      {
+        path: 'c:\\users\\neil\\orca',
+        head: '',
+        branch: '',
+        isBare: false,
+        isMainWorktree: true
+      }
+    ])
+
+    await hydrate(makeStore([{ id: 'repo-a', path: 'C:\\Users\\Neil\\Orca' }]))
+
+    expect(listRegisteredPtys()).toEqual([expect.objectContaining({ ptyId, worktreeId })])
+  })
+
+  it('fails closed when live worktrees collide on one normalized key', async () => {
+    const { hydrate, listRegisteredPtys } = await loadFresh()
+    const ptyId = 'repo-a::C:/Users/Neil/Orca@@cafebabe'
+    getDaemonProviderMock.mockReturnValue(
+      makeProvider([
+        { sessionId: ptyId, pid: 4242, cwd: 'C:/Users/Neil/Orca' } as unknown as SessionInfo
+      ])
+    )
+    listLocalRepoWorktreesStrictMock.mockResolvedValue([
+      {
+        path: 'C:/Users/Neil/Orca',
+        head: '',
+        branch: '',
+        isBare: false,
+        isMainWorktree: true
+      },
+      {
+        path: 'c:\\users\\neil\\orca',
+        head: '',
+        branch: '',
+        isBare: false,
+        isMainWorktree: false
+      }
+    ])
+
+    await hydrate(makeStore([{ id: 'repo-a', path: 'C:/Users/Neil/Orca' }]))
+
+    expect(listRegisteredPtys()).toHaveLength(0)
+  })
+
+  it('matches local WSL UNC aliases without treating WSL as a remote host', async () => {
+    const { hydrate, listRegisteredPtys } = await loadFresh()
+    const worktreeId = 'repo-a::\\\\wsl$\\Ubuntu\\home\\neil\\orca'
+    const ptyId = `${worktreeId}@@cafebabe`
+    getDaemonProviderMock.mockReturnValue(
+      makeProvider([
+        {
+          sessionId: ptyId,
+          pid: 4242,
+          cwd: '\\\\wsl$\\Ubuntu\\home\\neil\\orca'
+        } as unknown as SessionInfo
+      ])
+    )
+    listLocalRepoWorktreesStrictMock.mockResolvedValue([
+      {
+        path: '\\\\wsl.localhost\\ubuntu\\home\\neil\\orca',
+        head: '',
+        branch: '',
+        isBare: false,
+        isMainWorktree: true
+      }
+    ])
+
+    await hydrate(makeStore([{ id: 'repo-a', path: '\\\\wsl$\\Ubuntu\\home\\neil\\orca' }]))
+
+    expect(listRegisteredPtys()).toEqual([expect.objectContaining({ ptyId, worktreeId })])
+  })
+
+  it('preserves an exact repo-backed folder instance id from local-host metadata', async () => {
+    const { hydrate, listRegisteredPtys } = await loadFresh()
+    const instanceId =
+      'folder-repo::/workspace/folder::workspace:aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa'
+    const ptyId = `${instanceId}@@cafebabe`
+    getDaemonProviderMock.mockReturnValue(
+      makeProvider([
+        { sessionId: ptyId, pid: 4242, cwd: '/workspace/folder' } as unknown as SessionInfo
+      ])
+    )
+
+    await hydrate(
+      makeStore([{ id: 'folder-repo', kind: 'folder', path: '/workspace/folder' }], {
+        [instanceId]: { hostId: 'local' } as WorktreeMeta
+      })
+    )
+
+    expect(listRegisteredPtys()).toEqual([
+      expect.objectContaining({ ptyId, worktreeId: instanceId })
+    ])
+    expect(listLocalRepoWorktreesStrictMock).not.toHaveBeenCalled()
+  })
+
+  it('accepts legacy unhosted folder-instance metadata for a uniquely local repo', async () => {
+    const { hydrate, listRegisteredPtys } = await loadFresh()
+    const instanceId =
+      'folder-repo::/workspace/folder::workspace:aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa'
+    const ptyId = `${instanceId}@@cafebabe`
+    getDaemonProviderMock.mockReturnValue(
+      makeProvider([
+        { sessionId: ptyId, pid: 4242, cwd: '/workspace/folder' } as unknown as SessionInfo
+      ])
+    )
+
+    await hydrate(
+      makeStore([{ id: 'folder-repo', kind: 'folder', path: '/workspace/folder' }], {
+        [instanceId]: {} as WorktreeMeta
+      })
+    )
+
+    expect(listRegisteredPtys()).toEqual([expect.objectContaining({ ptyId })])
+  })
+
+  it('rejects legacy folder-instance metadata when the repo id also has a remote owner', async () => {
+    const { hydrate, listRegisteredPtys } = await loadFresh()
+    const instanceId =
+      'folder-repo::/workspace/folder::workspace:aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa'
+    getDaemonProviderMock.mockReturnValue(
+      makeProvider([
+        {
+          sessionId: `${instanceId}@@cafebabe`,
+          pid: 4242,
+          cwd: '/workspace/folder'
+        } as unknown as SessionInfo
+      ])
+    )
+
+    await hydrate(
+      makeStore(
+        [
+          { id: 'folder-repo', kind: 'folder', path: '/workspace/folder' },
+          {
+            id: 'folder-repo',
+            kind: 'folder',
+            path: '/workspace/folder',
+            executionHostId: 'runtime:environment-1'
+          }
+        ],
+        { [instanceId]: {} as WorktreeMeta }
+      )
+    )
+
+    expect(listRegisteredPtys()).toHaveLength(0)
+  })
+
+  it('accepts explicit local folder-instance metadata beside a same-id runtime owner', async () => {
+    const { hydrate, listRegisteredPtys } = await loadFresh()
+    const instanceId =
+      'folder-repo::/workspace/folder::workspace:aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa'
+    const ptyId = `${instanceId}@@cafebabe`
+    getDaemonProviderMock.mockReturnValue(
+      makeProvider([
+        { sessionId: ptyId, pid: 4242, cwd: '/workspace/folder' } as unknown as SessionInfo
+      ])
+    )
+
+    await hydrate(
+      makeStore(
+        [
+          { id: 'folder-repo', kind: 'folder', path: '/workspace/folder' },
+          {
+            id: 'folder-repo',
+            kind: 'folder',
+            path: '/workspace/folder',
+            executionHostId: 'runtime:environment-1'
+          }
+        ],
+        { [instanceId]: { hostId: 'local' } as WorktreeMeta }
+      )
+    )
+
+    expect(listRegisteredPtys()).toEqual([expect.objectContaining({ ptyId })])
+  })
+
+  it('keeps true folder workspace PTY ids as an accepted hydration gap', async () => {
+    const { hydrate, listRegisteredPtys } = await loadFresh()
+    const workspace = {
+      id: 'folder-workspace-1',
+      executionHostId: 'local'
+    } as FolderWorkspace
+    getDaemonProviderMock.mockReturnValue(
+      makeProvider([
+        {
+          sessionId: 'folder:folder-workspace-1@@cafebabe',
+          pid: 4242,
+          cwd: '/workspace/folder'
+        } as unknown as SessionInfo
+      ])
+    )
+
+    expect(
+      resolveFolderWorkspaceHost(
+        { folderWorkspaces: [workspace], projectGroups: [], repos: [] },
+        workspace.id
+      )
+    ).toEqual({ kind: 'local' })
+
+    await hydrate(makeStore())
+
+    expect(listRegisteredPtys()).toHaveLength(0)
+    expect(listLocalRepoWorktreesStrictMock).not.toHaveBeenCalled()
+  })
+
   it('does not register a daemon session whose worktree was removed', async () => {
     const { hydrate, listRegisteredPtys } = await loadFresh()
     const provider = makeProvider([
@@ -309,13 +804,13 @@ describe('hydrateLocalPtyRegistryAtBoot', () => {
       } as unknown as SessionInfo
     ])
     getDaemonProviderMock.mockReturnValue(provider)
-    listRepoWorktreesMock.mockResolvedValue([
+    listLocalRepoWorktreesStrictMock.mockResolvedValue([
       { path: '/local/current', head: '', branch: '', isBare: false, isMainWorktree: true }
     ])
 
     await hydrate(makeStore([{ id: 'repo-a', connectionId: null }]))
 
-    expect(listRepoWorktreesMock).toHaveBeenCalledTimes(1)
+    expect(listLocalRepoWorktreesStrictMock).toHaveBeenCalledTimes(1)
     expect(listRegisteredPtys()).toHaveLength(0)
   })
 
@@ -334,7 +829,7 @@ describe('hydrateLocalPtyRegistryAtBoot', () => {
       )
     )
     getDaemonProviderMock.mockReturnValue(provider)
-    listRepoWorktreesMock.mockImplementation(async (repo: Repo) => [
+    listLocalRepoWorktreesStrictMock.mockImplementation(async (repo: Repo) => [
       {
         path: `/local/${repo.id}`,
         head: '',
@@ -346,8 +841,8 @@ describe('hydrateLocalPtyRegistryAtBoot', () => {
 
     await hydrate(makeStore(repos))
 
-    expect(listRepoWorktreesMock).toHaveBeenCalledTimes(activeRepoIds.length)
-    expect(listRepoWorktreesMock.mock.calls.map(([repo]) => (repo as Repo).id)).toEqual(
+    expect(listLocalRepoWorktreesStrictMock).toHaveBeenCalledTimes(activeRepoIds.length)
+    expect(listLocalRepoWorktreesStrictMock.mock.calls.map(([repo]) => (repo as Repo).id)).toEqual(
       activeRepoIds
     )
     expect(listRegisteredPtys()).toHaveLength(activeRepoIds.length)
@@ -374,13 +869,13 @@ describe('hydrateLocalPtyRegistryAtBoot', () => {
       .mockResolvedValueOnce([sessionA])
       .mockResolvedValue([sessionA, sessionB])
     getDaemonProviderMock.mockReturnValue({ listSessions })
-    listRepoWorktreesMock.mockImplementation(async (repo: Repo) => [
+    listLocalRepoWorktreesStrictMock.mockImplementation(async (repo: Repo) => [
       { path: `/local/${repo.id}`, head: '', branch: '', isBare: false, isMainWorktree: true }
     ])
 
     await hydrate(makeStore([{ id: 'repo-a' }, { id: 'repo-b' }]))
 
-    expect(listRepoWorktreesMock.mock.calls.map(([repo]) => (repo as Repo).id)).toEqual([
+    expect(listLocalRepoWorktreesStrictMock.mock.calls.map(([repo]) => (repo as Repo).id)).toEqual([
       'repo-a',
       'repo-b'
     ])
@@ -398,7 +893,7 @@ describe('hydrateLocalPtyRegistryAtBoot', () => {
     const sessions = makeLocalSessions('repo-a', '/local/Triton', LARGE_SESSION_COUNT)
     const provider = makeProvider(sessions)
     getDaemonProviderMock.mockReturnValue(provider)
-    listRepoWorktreesMock.mockResolvedValue([
+    listLocalRepoWorktreesStrictMock.mockResolvedValue([
       { path: '/local/Triton', head: '', branch: '', isBare: false, isMainWorktree: true }
     ])
 
diff --git a/src/main/memory/hydrate-local-pty-registry.ts b/src/main/memory/hydrate-local-pty-registry.ts
index 3388eeebed9..b384439f0f2 100644
--- a/src/main/memory/hydrate-local-pty-registry.ts
+++ b/src/main/memory/hydrate-local-pty-registry.ts
@@ -1,146 +1,279 @@
-/**
- * Boot-time hydration of `pty-registry` from the live daemon.
- *
- * Why: on warm reattach (fresh Orca process, still-running daemon) the renderer
- * hasn't re-mounted every pane, so `pty:spawn` never fired for those sessions
- * and they surfaced as "REMOTE" despite being local. Fill the gap once at boot,
- * registering only sessions whose repo has no `connectionId` — mirroring the
- * spawn-time gate in `src/main/ipc/pty.ts`.
- */
-
-import { getDaemonProvider } from '../daemon/daemon-init'
-import { DaemonPtyRouter } from '../daemon/daemon-pty-router'
-import { DegradedDaemonPtyProvider } from '../daemon/degraded-daemon-pty-provider'
-import type { DaemonPtyAdapter } from '../daemon/daemon-pty-adapter'
-import type { SessionInfo } from '../daemon/types'
-import { listRegisteredPtys, registerPty } from './pty-registry'
-import { listRepoWorktrees } from '../repo-worktrees'
+import { getRepoExecutionHostId, LOCAL_EXECUTION_HOST_ID } from '../../shared/execution-host'
+import { throwIfSignalAborted, waitForPromiseWithSignal } from '../../shared/abort-signal-reason'
+import { mapSettledWithConcurrency } from '../../shared/map-with-concurrency'
 import { parsePtySessionId } from '../../shared/pty-session-id-format'
-import { splitWorktreeId } from '../../shared/worktree/id'
+import { isFolderRepo } from '../../shared/repo-kind'
+import type { Repo } from '../../shared/repo-types'
+import { splitWorktreeId, worktreeIdComparisonKey } from '../../shared/worktree/id'
+import { getDaemonProvider } from '../daemon/daemon-init'
+import type { DaemonPtyAdapter } from '../daemon/daemon-pty-adapter'
+import type { DaemonPtyRouter } from '../daemon/daemon-pty-router'
+import type { DegradedDaemonPtyProvider } from '../daemon/degraded-daemon-pty-provider'
+import type { SessionInfo } from '../daemon/types'
+import { isFolderWorkspaceIdForRepo } from '../ipc/worktrees/folder-workspace-model'
 import type { Store } from '../persistence'
+import { readAllWorktreeMetaForHost } from '../persistence/host-qualified-worktree-meta'
+import { getLocalProjectWorktreeGitOptions } from '../project-runtime-git-options'
+import { listLocalRepoWorktreesStrict } from '../repo-worktrees'
+import { listRegisteredPtys, registerPty } from './pty-registry'
+
+type HydrationStore = Store
+
+type DaemonInventory = {
+  complete: boolean
+  sessions: SessionInfo[]
+}
+
+type LocalRepoCatalog = {
+  byId: Map<string, Repo>
+  ownerCountById: Map<string, number>
+}
+
+// Why: matches existing local Git/read startup budgets while allowing for Defender-heavy repos.
+export const LOCAL_PTY_REGISTRY_BOOT_HYDRATION_DEADLINE_MS = 5_000
+export const LOCAL_PTY_REGISTRY_GIT_ENUMERATION_CONCURRENCY = 4
 
-// Why: macOS dock reactivation reruns setup; avoid repeating Git I/O and daemon RPC.
 let hasHydrated = false
+let hydrationInFlight: Promise<void> | null = null
 
-/**
- * Read the live daemon session list and register every local session the
- * registry doesn't already know about.
- *
- * Why: failures here are a coverage degradation (the renderer-side union still
- * covers the gap), not a correctness regression, so they're swallowed.
- */
-export async function hydrateLocalPtyRegistryAtBoot(store: Pick<Store, 'getRepos'>): Promise<void> {
-  try {
-    if (hasHydrated) {
-      return
-    }
-    const provider = getDaemonProvider()
-    if (!provider) {
-      // Why: leave hasHydrated false so a later activation can retry once the daemon is up.
-      return
-    }
-    // Why: flip only after a provider exists; retrying a failed RPC on the same socket won't help.
-    hasHydrated = true
+export function hydrateLocalPtyRegistryAtBoot(store: HydrationStore): Promise<void> {
+  if (hasHydrated) {
+    return Promise.resolve()
+  }
+  if (hydrationInFlight) {
+    return hydrationInFlight
+  }
 
-    // Why: enumerate Git worktrees only for live-session repos.
-    const reposById = new Map(store.getRepos().map((repo) => [repo.id, repo]))
-    // Why: verify via live git that a referenced worktree still exists, to avoid resurrecting removed ones.
-    const liveLocalWorktreeIds = new Set<string>()
-    const resolvedRepoIds = new Set<string>()
-
-    let sessionInfos = await collectSessionInfos(provider)
-    let alreadyRegistered = new Set(listRegisteredPtys().map((p) => p.ptyId))
-
-    // Why: re-read live sessions each pass to avoid resurrecting exited sessions.
-    for (;;) {
-      const newlyReferencedRepos = new Map<string, ReturnType<(typeof store)['getRepos']>[number]>()
-      for (const info of sessionInfos) {
-        if (alreadyRegistered.has(info.sessionId)) {
-          continue
-        }
-        const { worktreeId } = parsePtySessionId(info.sessionId)
-        const parsedWorktreeId = worktreeId ? splitWorktreeId(worktreeId) : null
-        if (!parsedWorktreeId || resolvedRepoIds.has(parsedWorktreeId.repoId)) {
-          continue
-        }
-        const repo = reposById.get(parsedWorktreeId.repoId)
-        if (!repo || (repo.connectionId ?? null)) {
-          // Why: unknown and SSH repos cannot be proven local, so do not enumerate them.
-          resolvedRepoIds.add(parsedWorktreeId.repoId)
-          continue
-        }
-        newlyReferencedRepos.set(repo.id, repo)
+  const controller = new AbortController()
+  const deadline = setTimeout(() => {
+    controller.abort(new Error('Boot-time pty-registry hydration deadline expired'))
+  }, LOCAL_PTY_REGISTRY_BOOT_HYDRATION_DEADLINE_MS)
+  let attempt!: Promise<void>
+  attempt = waitForPromiseWithSignal(
+    hydrateLocalPtyRegistry(store, controller.signal),
+    controller.signal
+  )
+    .then((complete) => {
+      if (complete) {
+        hasHydrated = true
       }
-      if (newlyReferencedRepos.size === 0) {
-        break
+    })
+    .catch((error) => {
+      console.warn(
+        '[memory] Boot-time pty-registry hydration failed:',
+        error instanceof Error ? error.message : String(error)
+      )
+    })
+    .finally(() => {
+      clearTimeout(deadline)
+      if (hydrationInFlight === attempt) {
+        hydrationInFlight = null
       }
+    })
+  hydrationInFlight = attempt
+  return attempt
+}
 
-      for (const repo of newlyReferencedRepos.values()) {
-        resolvedRepoIds.add(repo.id)
-        const worktrees = await listRepoWorktrees(repo)
-        for (const wt of worktrees) {
-          liveLocalWorktreeIds.add(`${repo.id}::${wt.path}`)
-        }
-      }
+async function hydrateLocalPtyRegistry(
+  store: HydrationStore,
+  signal: AbortSignal
+): Promise<boolean> {
+  throwIfSignalAborted(signal)
+  const provider = getDaemonProvider()
+  if (!provider) {
+    return false
+  }
 
-      sessionInfos = await collectSessionInfos(provider)
-      alreadyRegistered = new Set(listRegisteredPtys().map((p) => p.ptyId))
-    }
-    for (const info of sessionInfos) {
-      // Why: pty:spawn is the authoritative pid writer; don't overwrite its entry with a stale listSessions() pid.
+  const repoCatalog = getLocalRepoCatalog(store.getRepos())
+  const reposById = repoCatalog.byId
+  const verifiedFolderWorktreeIds = getVerifiedFolderWorktreeIds(store, repoCatalog)
+  const liveGitWorktreeIdsByKey = new Map<string, string | null>()
+  const resolvedRepoIds = new Set<string>()
+  let inventory = await collectSessionInfos(provider, signal)
+  let complete = inventory.complete
+  let alreadyRegistered = new Set(listRegisteredPtys().map((pty) => pty.ptyId))
+
+  for (;;) {
+    const referencedRepos = new Map<string, Repo>()
+    for (const info of inventory.sessions) {
       if (alreadyRegistered.has(info.sessionId)) {
         continue
       }
-      const { worktreeId } = parsePtySessionId(info.sessionId)
-      if (!worktreeId) {
+      const parsed = splitWorktreeId(parsePtySessionId(info.sessionId).worktreeId ?? '')
+      if (!parsed || resolvedRepoIds.has(parsed.repoId)) {
         continue
       }
-      // Why: register only proven-local worktrees, matching the spawn-time gate.
-      if (!liveLocalWorktreeIds.has(worktreeId)) {
+      const repo = reposById.get(parsed.repoId)
+      if (!repo || isFolderRepo(repo)) {
+        resolvedRepoIds.add(parsed.repoId)
         continue
       }
-      registerPty({
-        ptyId: info.sessionId,
-        worktreeId,
-        sessionId: info.sessionId,
-        paneKey: null,
-        pid:
-          typeof info.pid === 'number' && Number.isFinite(info.pid) && info.pid > 0
-            ? info.pid
-            : null
-      })
+      referencedRepos.set(repo.id, repo)
     }
-  } catch (err) {
-    console.warn(
-      '[memory] Boot-time pty-registry hydration failed:',
-      err instanceof Error ? err.message : String(err)
+    if (referencedRepos.size === 0) {
+      break
+    }
+    for (const repo of referencedRepos.values()) {
+      resolvedRepoIds.add(repo.id)
+    }
+
+    const worktreeResults = await mapSettledWithConcurrency(
+      [...referencedRepos.values()],
+      LOCAL_PTY_REGISTRY_GIT_ENUMERATION_CONCURRENCY,
+      async (repo) => {
+        throwIfSignalAborted(signal)
+        const worktrees = await waitForPromiseWithSignal(
+          listLocalRepoWorktreesStrict(repo, {
+            ...getLocalProjectWorktreeGitOptions(store, repo),
+            signal
+          }),
+          signal
+        )
+        throwIfSignalAborted(signal)
+        return { repo, worktrees }
+      }
     )
+    throwIfSignalAborted(signal)
+
+    for (const result of worktreeResults) {
+      if (result.status === 'rejected') {
+        complete = false
+        console.warn(
+          '[memory] Worktree enumeration failed during pty-registry hydration:',
+          result.reason instanceof Error ? result.reason.message : String(result.reason)
+        )
+        continue
+      }
+      const { repo, worktrees } = result.value
+      for (const worktree of worktrees) {
+        const worktreeId = `${repo.id}::${worktree.path}`
+        const key = worktreeIdComparisonKey(worktreeId)
+        if (key) {
+          const existing = liveGitWorktreeIdsByKey.get(key)
+          liveGitWorktreeIdsByKey.set(
+            key,
+            existing === undefined || existing === worktreeId ? worktreeId : null
+          )
+        }
+      }
+    }
+
+    inventory = await collectSessionInfos(provider, signal)
+    complete = complete && inventory.complete
+    alreadyRegistered = new Set(listRegisteredPtys().map((pty) => pty.ptyId))
+  }
+
+  throwIfSignalAborted(signal)
+  for (const info of inventory.sessions) {
+    throwIfSignalAborted(signal)
+    if (alreadyRegistered.has(info.sessionId)) {
+      continue
+    }
+    const { worktreeId } = parsePtySessionId(info.sessionId)
+    if (!worktreeId || !isVerifiedLocalWorktree(worktreeId)) {
+      continue
+    }
+    registerPty({
+      ptyId: info.sessionId,
+      worktreeId,
+      sessionId: info.sessionId,
+      paneKey: null,
+      pid:
+        typeof info.pid === 'number' && Number.isFinite(info.pid) && info.pid > 0 ? info.pid : null
+    })
+  }
+  return complete
+
+  function isVerifiedLocalWorktree(worktreeId: string): boolean {
+    if (verifiedFolderWorktreeIds.has(worktreeId)) {
+      return true
+    }
+    const key = worktreeIdComparisonKey(worktreeId)
+    return key !== null && typeof liveGitWorktreeIdsByKey.get(key) === 'string'
   }
 }
 
-async function collectSessionInfos(
-  provider: DaemonPtyRouter | DaemonPtyAdapter | DegradedDaemonPtyProvider
-): Promise<SessionInfo[]> {
-  // Why: fan listSessions across current + legacy adapters so no daemon protocol version is missed.
-  const adapters: readonly DaemonPtyAdapter[] =
-    provider instanceof DaemonPtyRouter || provider instanceof DegradedDaemonPtyProvider
-      ? provider.getAllAdapters()
-      : [provider]
-  const out: SessionInfo[] = []
-  for (const adapter of adapters) {
-    try {
-      const sessions = await adapter.listSessions()
-      // Why: session count can exceed the JS argument limit, so avoid push(...sessions).
-      for (const session of sessions) {
-        out.push(session)
-      }
-    } catch (err) {
-      // Why: one adapter's socket being unreachable is normal; don't abort the others.
-      console.warn(
-        '[memory] listSessions failed for one adapter during hydration:',
-        err instanceof Error ? err.message : String(err)
-      )
+function getLocalRepoCatalog(repos: Repo[]): LocalRepoCatalog {
+  const byId = new Map<string, Repo>()
+  const ownerCountById = new Map<string, number>()
+  const ambiguousIds = new Set<string>()
+  for (const repo of repos) {
+    ownerCountById.set(repo.id, (ownerCountById.get(repo.id) ?? 0) + 1)
+    if (getRepoExecutionHostId(repo) !== LOCAL_EXECUTION_HOST_ID) {
+      continue
+    }
+    if (byId.has(repo.id)) {
+      ambiguousIds.add(repo.id)
+    } else {
+      byId.set(repo.id, repo)
     }
   }
-  return out
+  for (const repoId of ambiguousIds) {
+    byId.delete(repoId)
+  }
+  return { byId, ownerCountById }
+}
+
+function getVerifiedFolderWorktreeIds(
+  store: HydrationStore,
+  repoCatalog: LocalRepoCatalog
+): Set<string> {
+  const verified = new Set<string>()
+  const metadata = readAllWorktreeMetaForHost(store, LOCAL_EXECUTION_HOST_ID)
+  for (const [worktreeId, meta] of Object.entries(metadata)) {
+    const parsed = splitWorktreeId(worktreeId)
+    const repo = parsed ? repoCatalog.byId.get(parsed.repoId) : undefined
+    const hasLocalAuthority =
+      meta.hostId === LOCAL_EXECUTION_HOST_ID ||
+      (meta.hostId === undefined && repoCatalog.ownerCountById.get(parsed?.repoId ?? '') === 1)
+    if (
+      repo &&
+      isFolderRepo(repo) &&
+      hasLocalAuthority &&
+      isFolderWorkspaceIdForRepo(repo, worktreeId)
+    ) {
+      verified.add(worktreeId)
+    }
+  }
+  return verified
+}
+
+async function collectSessionInfos(
+  provider: DaemonPtyRouter | DaemonPtyAdapter | DegradedDaemonPtyProvider,
+  signal: AbortSignal
+): Promise<DaemonInventory> {
+  const adapters =
+    'getAllAdapters' in provider && typeof provider.getAllAdapters === 'function'
+      ? provider.getAllAdapters()
+      : [provider]
+  const results = await Promise.all(
+    adapters.map(async (adapter) => {
+      try {
+        throwIfSignalAborted(signal)
+        const sessions = await waitForPromiseWithSignal<SessionInfo[]>(
+          adapter.listSessions(),
+          signal
+        )
+        throwIfSignalAborted(signal)
+        return { complete: true, sessions }
+      } catch (error) {
+        throwIfSignalAborted(signal)
+        console.warn(
+          '[memory] listSessions failed for one adapter during hydration:',
+          error instanceof Error ? error.message : String(error)
+        )
+        return { complete: false, sessions: [] }
+      }
+    })
+  )
+  const sessions: SessionInfo[] = []
+  for (const result of results) {
+    for (const session of result.sessions) {
+      sessions.push(session)
+    }
+  }
+  return {
+    complete: results.length > 0 && results.every((result) => result.complete),
+    sessions
+  }
 }
diff --git a/src/main/orcad/orcad-entry.ts b/src/main/orcad/orcad-entry.ts
index 4af2a87c45d..3b10ca985e9 100644
--- a/src/main/orcad/orcad-entry.ts
+++ b/src/main/orcad/orcad-entry.ts
@@ -190,7 +190,7 @@ async function startOrcadRuntime(
   // Codex-home and Claude-auth preparation are left unset: both are desktop account
   // flows. A launch that needs one fails with its own message rather than silently
   // spawning an unauthenticated agent.
-  registerHeadlessPtyRuntime(runtime, undefined, () => store.getSettings(), undefined, store)
+  await registerHeadlessPtyRuntime(runtime, undefined, () => store.getSettings(), undefined, store)
 
   // Why: same post-registration reconciliation `--serve` performs. Skipping it leaves
   // restored orchestration rows claiming an authority this host never took over.
diff --git a/src/main/repo-worktrees.test.ts b/src/main/repo-worktrees.test.ts
index 3c6910991f0..d0c0ea5c617 100644
--- a/src/main/repo-worktrees.test.ts
+++ b/src/main/repo-worktrees.test.ts
@@ -1,18 +1,26 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
-const { listWorktreesMock } = vi.hoisted(() => ({
-  listWorktreesMock: vi.fn()
+const { listWorktreesMock, listWorktreesStrictMock } = vi.hoisted(() => ({
+  listWorktreesMock: vi.fn(),
+  listWorktreesStrictMock: vi.fn()
 }))
 
 vi.mock('./git/worktree', () => ({
-  listWorktrees: listWorktreesMock
+  listWorktrees: listWorktreesMock,
+  listWorktreesStrict: listWorktreesStrictMock
 }))
 
-import { createFolderWorktree, isRepoRoot, listRepoWorktrees } from './repo-worktrees'
+import {
+  createFolderWorktree,
+  isRepoRoot,
+  listLocalRepoWorktreesStrict,
+  listRepoWorktrees
+} from './repo-worktrees'
 
 describe('repo-worktrees', () => {
   beforeEach(() => {
     listWorktreesMock.mockReset()
+    listWorktreesStrictMock.mockReset()
   })
 
   it('creates a stable synthetic worktree for folder repos', () => {
@@ -56,6 +64,29 @@ describe('repo-worktrees', () => {
     expect(listWorktreesMock).not.toHaveBeenCalled()
   })
 
+  it('returns the synthetic folder worktree for strict local listing', async () => {
+    const result = await listLocalRepoWorktreesStrict({
+      id: 'repo-1',
+      path: '/workspace/folder',
+      displayName: 'folder',
+      badgeColor: '#000',
+      addedAt: 0,
+      kind: 'folder'
+    })
+
+    expect(result).toEqual([
+      createFolderWorktree({
+        id: 'repo-1',
+        path: '/workspace/folder',
+        displayName: 'folder',
+        badgeColor: '#000',
+        addedAt: 0,
+        kind: 'folder'
+      })
+    ])
+    expect(listWorktreesStrictMock).not.toHaveBeenCalled()
+  })
+
   it('delegates to git worktree listing for git repos', async () => {
     listWorktreesMock.mockResolvedValue([
       { path: '/workspace/repo', head: 'abc', branch: '', isBare: false, isMainWorktree: true }
@@ -78,6 +109,46 @@ describe('repo-worktrees', () => {
     expect(result).toHaveLength(1)
   })
 
+  it('delegates strict local listing with the signal and WSL options', async () => {
+    listWorktreesStrictMock.mockResolvedValue([
+      { path: '/workspace/repo', head: 'abc', branch: '', isBare: false, isMainWorktree: true }
+    ])
+    const signal = new AbortController().signal
+
+    const result = await listLocalRepoWorktreesStrict(
+      {
+        id: 'repo-1',
+        path: '/workspace/repo',
+        displayName: 'repo',
+        badgeColor: '#000',
+        addedAt: 0,
+        kind: 'git'
+      },
+      { signal, wslDistro: 'Ubuntu' }
+    )
+
+    expect(listWorktreesStrictMock).toHaveBeenCalledWith('/workspace/repo', {
+      signal,
+      wslDistro: 'Ubuntu'
+    })
+    expect(result).toHaveLength(1)
+  })
+
+  it('rejects strict listing for remote repos', async () => {
+    await expect(
+      listLocalRepoWorktreesStrict({
+        id: 'repo-1',
+        path: '/workspace/repo',
+        displayName: 'repo',
+        badgeColor: '#000',
+        addedAt: 0,
+        connectionId: 'ssh-1',
+        kind: 'git'
+      })
+    ).rejects.toThrow('remote repository')
+    expect(listWorktreesStrictMock).not.toHaveBeenCalled()
+  })
+
   it('treats Windows repo root casing differences as the same local root', () => {
     const repos = [
       {
diff --git a/src/main/repo-worktrees.ts b/src/main/repo-worktrees.ts
index f4123c18889..14751c17861 100644
--- a/src/main/repo-worktrees.ts
+++ b/src/main/repo-worktrees.ts
@@ -1,6 +1,6 @@
 import type { Repo } from '../shared/repo-types'
 import type { GitWorktreeInfo } from '../shared/worktree/types'
-import { listWorktrees } from './git/worktree'
+import { listWorktrees, listWorktreesStrict } from './git/worktree'
 import { isFolderRepo } from '../shared/repo-kind'
 import { getSshGitProvider } from './providers/ssh-git-dispatch'
 import { areWorktreePathsEqual } from './ipc/worktree-logic'
@@ -51,3 +51,18 @@ export async function listRepoWorktrees(
     ? await listWorktrees(repo.path, options)
     : await listWorktrees(repo.path)
 }
+
+export async function listLocalRepoWorktreesStrict(
+  repo: Repo,
+  options?: LocalRepoWorktreeListOptions
+): Promise<GitWorktreeInfo[]> {
+  if (repo.connectionId) {
+    throw new Error('Cannot list worktrees for a remote repository')
+  }
+  if (isFolderRepo(repo)) {
+    return [createFolderWorktree(repo)]
+  }
+  return hasLocalRepoWorktreeListOptions(options)
+    ? await listWorktreesStrict(repo.path, options)
+    : await listWorktreesStrict(repo.path)
+}
diff --git a/src/main/startup/desktop-startup-ordering.test.ts b/src/main/startup/desktop-startup-ordering.test.ts
index 9c26b12292d..b80d7adee41 100644
--- a/src/main/startup/desktop-startup-ordering.test.ts
+++ b/src/main/startup/desktop-startup-ordering.test.ts
@@ -121,6 +121,7 @@ describe('startup ordering', () => {
     expect(desktopStartup).toContain(
       'openWindow: () => openMainWindow({ revealOnDidFinishLoad: true })'
     )
+    expect(desktopStartup).toContain('bindServices: bindTerminalRuntimeStartupServices')
     expect(desktopStartup).toContain('shellPathReady,')
     expect(desktopStartup).toContain('startServices: startTerminalRuntimeStartupServices')
     expect(barrier).toContain('managedWslCliStartupBarrierReady')
diff --git a/src/main/startup/headless-pty-hydration-ordering.test.ts b/src/main/startup/headless-pty-hydration-ordering.test.ts
new file mode 100644
index 00000000000..2263cdbf94f
--- /dev/null
+++ b/src/main/startup/headless-pty-hydration-ordering.test.ts
@@ -0,0 +1,52 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+describe('headless PTY registry hydration ordering', () => {
+  it('uses exactly one deferred-or-immediate desktop hydration path', () => {
+    const source = readFileSync(
+      join(process.cwd(), 'src/main/window/attach-main-window-services.ts'),
+      'utf8'
+    )
+    const start = source.indexOf('const localPtyProviderStartupReady =')
+    const end = source.indexOf('registerSshHandlers(', start)
+    const hydration = source.slice(start, end)
+
+    expect(start).toBeGreaterThanOrEqual(0)
+    expect(end).toBeGreaterThan(start)
+    expect(hydration).toContain('if (localPtyProviderStartupReady)')
+    expect(hydration).toContain('.then(() => hydrateLocalPtyRegistryAtBoot(store))')
+    expect(hydration).toContain('} else {\n    void hydrateLocalPtyRegistryAtBoot(store)')
+    expect(hydration.match(/hydrateLocalPtyRegistryAtBoot\(store\)/g)).toHaveLength(2)
+  })
+
+  it('hydrates Electron serve after provider and handler readiness but before RPC', () => {
+    const source = readFileSync(join(process.cwd(), 'src/main/index.ts'), 'utf8')
+    const serve = source.indexOf('if (serveOptions) {')
+    const provider = source.indexOf('await localPtyProviderStartupReady', serve)
+    const handlersAndHydration = source.indexOf('await registerHeadlessPtyRuntime(', provider)
+    const rpc = source.indexOf('await runtimeRpc.start()', handlersAndHydration)
+    const readiness = source.indexOf('await printServeReady(serveOptions)', rpc)
+
+    expect(serve).toBeGreaterThanOrEqual(0)
+    expect(provider).toBeGreaterThan(serve)
+    expect(handlersAndHydration).toBeGreaterThan(provider)
+    expect(rpc).toBeGreaterThan(handlersAndHydration)
+    expect(readiness).toBeGreaterThan(rpc)
+  })
+
+  it('hydrates orcad after Store and daemon readiness but before RPC and publication', () => {
+    const source = readFileSync(join(process.cwd(), 'src/main/orcad/orcad-entry.ts'), 'utf8')
+    const store = source.indexOf('const store = new Store(')
+    const daemon = source.indexOf('await startOrcadDaemon()', store)
+    const handlersAndHydration = source.indexOf('await registerHeadlessPtyRuntime(', daemon)
+    const rpc = source.indexOf('await rpc.start()', handlersAndHydration)
+    const readiness = source.indexOf('await new ServeReadinessPublisher().publish(', rpc)
+
+    expect(store).toBeGreaterThanOrEqual(0)
+    expect(daemon).toBeGreaterThan(store)
+    expect(handlersAndHydration).toBeGreaterThan(daemon)
+    expect(rpc).toBeGreaterThan(handlersAndHydration)
+    expect(readiness).toBeGreaterThan(rpc)
+  })
+})
diff --git a/src/main/startup/serve-desktop-activation-wiring.test.ts b/src/main/startup/serve-desktop-activation-wiring.test.ts
index 239a7618567..0aea295c657 100644
--- a/src/main/startup/serve-desktop-activation-wiring.test.ts
+++ b/src/main/startup/serve-desktop-activation-wiring.test.ts
@@ -21,12 +21,19 @@ describe('serve desktop activation wiring', () => {
     )
     const serveIndex = source.indexOf('if (serveOptions) {', appReadyIndex)
     const ptyReadyIndex = source.indexOf('await localPtyStartupReady', serveIndex)
-    const headlessRegistrationIndex = source.indexOf('registerHeadlessPtyRuntime(', serveIndex)
+    const providerReadyIndex = source.indexOf('await localPtyProviderStartupReady', serveIndex)
+    const headlessRegistrationIndex = source.indexOf(
+      'await registerHeadlessPtyRuntime(',
+      serveIndex
+    )
+    const rpcIndex = source.indexOf('await runtimeRpc.start()', serveIndex)
 
     expect(startupIndex).toBeGreaterThanOrEqual(0)
     expect(startupIndex).toBeLessThan(serveIndex)
     expect(ptyReadyIndex).toBeGreaterThan(serveIndex)
-    expect(headlessRegistrationIndex).toBeGreaterThan(ptyReadyIndex)
+    expect(providerReadyIndex).toBeGreaterThan(ptyReadyIndex)
+    expect(headlessRegistrationIndex).toBeGreaterThan(providerReadyIndex)
+    expect(headlessRegistrationIndex).toBeLessThan(rpcIndex)
     expect(source).not.toContain(
       'if (!isServeMode) {\n    startDesktopFirstWindowStartupServices()'
     )
diff --git a/src/main/startup/windows-desktop-shell-path-startup.test.ts b/src/main/startup/windows-desktop-shell-path-startup.test.ts
index 3778e0b2688..d38b24aa05e 100644
--- a/src/main/startup/windows-desktop-shell-path-startup.test.ts
+++ b/src/main/startup/windows-desktop-shell-path-startup.test.ts
@@ -10,6 +10,29 @@ function deferred(): { promise: Promise<void>; resolve: () => void } {
 }
 
 describe('Windows desktop shell PATH startup', () => {
+  it('binds the services promise before opening the window while shell PATH is unresolved', () => {
+    const shellPath = deferred()
+    const events: string[] = []
+    const bindServices = vi.fn(() => events.push('bind'))
+    const openWindow = vi.fn(() => events.push('open'))
+    const options = {
+      bindServices,
+      openWindow,
+      shellPathReady: shellPath.promise,
+      startServices: vi.fn(() => ({
+        firstWindowReady: Promise.resolve(),
+        localPtyReady: Promise.resolve(),
+        localPtyProviderReady: Promise.resolve()
+      }))
+    }
+
+    startWindowsDesktopBeforeShellPathReady(options)
+
+    expect(events).toEqual(['bind', 'open'])
+    expect(bindServices).toHaveBeenCalledOnce()
+    expect(options.startServices).not.toHaveBeenCalled()
+  })
+
   it('opens the first window while shell PATH hydration remains unresolved', async () => {
     const shellPath = deferred()
     const window = { visible: true }
@@ -21,6 +44,7 @@ describe('Windows desktop shell PATH startup', () => {
     }))
 
     const startup = startWindowsDesktopBeforeShellPathReady({
+      bindServices: vi.fn(),
       openWindow,
       shellPathReady: shellPath.promise,
       startServices
diff --git a/src/main/startup/windows-desktop-shell-path-startup.ts b/src/main/startup/windows-desktop-shell-path-startup.ts
index 3933a79b64b..3fda3fad168 100644
--- a/src/main/startup/windows-desktop-shell-path-startup.ts
+++ b/src/main/startup/windows-desktop-shell-path-startup.ts
@@ -5,6 +5,7 @@ export type WindowsDesktopStartupServices = {
 }
 
 type WindowsDesktopShellPathStartupOptions<TWindow> = {
+  bindServices: (services: Promise<WindowsDesktopStartupServices>) => void
   openWindow: () => TWindow
   shellPathReady: Promise<void>
   startServices: () => WindowsDesktopStartupServices
@@ -14,5 +15,6 @@ export function startWindowsDesktopBeforeShellPathReady<TWindow>(
   options: WindowsDesktopShellPathStartupOptions<TWindow>
 ): { window: TWindow; services: Promise<WindowsDesktopStartupServices> } {
   const services = options.shellPathReady.then(options.startServices)
+  options.bindServices(services)
   return { window: options.openWindow(), services }
 }
diff --git a/src/main/window/attach-main-window-services.test.ts b/src/main/window/attach-main-window-services.test.ts
index 8a340d840ec..ae83f5b7712 100644
--- a/src/main/window/attach-main-window-services.test.ts
+++ b/src/main/window/attach-main-window-services.test.ts
@@ -271,8 +271,8 @@ describe('attachMainWindowServices', () => {
     expect(mainWindow.webContents.reload).toHaveBeenCalledTimes(1)
   })
 
-  it('retries local PTY registry hydration after local startup services are ready', async () => {
-    const localStartup = deferred()
+  it('hydrates once after the local PTY provider barrier resolves', async () => {
+    const providerStartup = deferred()
     const store = createStore()
 
     attachMainWindowServices(
@@ -281,18 +281,17 @@ describe('attachMainWindowServices', () => {
       createRuntime() as never,
       undefined,
       undefined,
-      { awaitLocalPtyStartup: () => localStartup.promise }
+      { awaitLocalPtyProviderStartup: () => providerStartup.promise }
     )
 
-    expect(hydrateLocalPtyRegistryAtBootMock).toHaveBeenCalledTimes(1)
-    expect(hydrateLocalPtyRegistryAtBootMock).toHaveBeenCalledWith(store)
+    expect(hydrateLocalPtyRegistryAtBootMock).not.toHaveBeenCalled()
 
-    localStartup.resolve()
-    await localStartup.promise
+    providerStartup.resolve()
+    await providerStartup.promise
     await Promise.resolve()
 
-    expect(hydrateLocalPtyRegistryAtBootMock).toHaveBeenCalledTimes(2)
-    expect(hydrateLocalPtyRegistryAtBootMock).toHaveBeenLastCalledWith(store)
+    expect(hydrateLocalPtyRegistryAtBootMock).toHaveBeenCalledOnce()
+    expect(hydrateLocalPtyRegistryAtBootMock).toHaveBeenCalledWith(store)
   })
 
   it('passes injected update quit cleanup to the auto-updater', async () => {
diff --git a/src/main/window/attach-main-window-services.ts b/src/main/window/attach-main-window-services.ts
index ce62a6d3da4..5910a001649 100644
--- a/src/main/window/attach-main-window-services.ts
+++ b/src/main/window/attach-main-window-services.ts
@@ -146,11 +146,9 @@ export function attachMainWindowServices(
   scheduleHistoryGc(async () => {
     return getKnownWorktreeIdsForHistoryGc(store)
   })
-  // Why: daemon PTYs survive renderer restarts, so at boot they're unregistered; hydrate so they aren't mislabeled REMOTE (idempotent, safe to re-run).
-  void hydrateLocalPtyRegistryAtBoot(store)
-  const localPtyStartupReady = options?.awaitLocalPtyStartup?.()
-  if (localPtyStartupReady) {
-    void localPtyStartupReady
+  const localPtyProviderStartupReady = options?.awaitLocalPtyProviderStartup?.()
+  if (localPtyProviderStartupReady) {
+    void localPtyProviderStartupReady
       .then(() => hydrateLocalPtyRegistryAtBoot(store))
       .catch((error) => {
         console.warn(
@@ -158,6 +156,8 @@ export function attachMainWindowServices(
           error instanceof Error ? error.message : String(error)
         )
       })
+  } else {
+    void hydrateLocalPtyRegistryAtBoot(store)
   }
   registerSshHandlers(store, () => mainWindow, runtime)
   registerRemoteWorkspaceHandlers(store, () => mainWindow)

From 162df6e5e93c77c17de293bce87177a753f0b0b1 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sat, 29 Aug 2026 19:43:23 -0700
Subject: [PATCH 18/31] fix(crash): suppress Linux namespace SIGTERM reports
 (#17315)

---
 .../expected-teardown-state.test.ts           |  1 +
 .../gpu-crash-fallback-field-sessions.test.ts |  8 +++-
 .../process-gone-classification.test.ts       | 46 ++++++++++++++++++-
 .../process-gone-classification.ts            | 10 +++-
 .../process-gone-recorder.test.ts             | 45 ++++++++++++++++--
 .../crash-reporting/process-gone-recorder.ts  | 15 +++---
 6 files changed, 107 insertions(+), 18 deletions(-)

diff --git a/src/main/crash-reporting/expected-teardown-state.test.ts b/src/main/crash-reporting/expected-teardown-state.test.ts
index 17a296bb582..ccfc729092b 100644
--- a/src/main/crash-reporting/expected-teardown-state.test.ts
+++ b/src/main/crash-reporting/expected-teardown-state.test.ts
@@ -13,6 +13,7 @@ import {
 
 function shouldRecordKilledRenderer(expectedTeardown: 'none' | 'renderer-reload' | 'app-shutdown') {
   return shouldRecordProcessGoneCrash({
+    platform: 'win32',
     source: 'renderer',
     processType: 'renderer',
     reason: 'killed',
diff --git a/src/main/crash-reporting/gpu-crash-fallback-field-sessions.test.ts b/src/main/crash-reporting/gpu-crash-fallback-field-sessions.test.ts
index 3df9849505d..aec22e2e446 100644
--- a/src/main/crash-reporting/gpu-crash-fallback-field-sessions.test.ts
+++ b/src/main/crash-reporting/gpu-crash-fallback-field-sessions.test.ts
@@ -66,7 +66,13 @@ const FIELD_GPU_EVENT = {
 describe('1.4.190 win32 GPU-child crash cluster', () => {
   it('does not let process_gone_suppressed gate the fallback candidate check', () => {
     // The GPU death is suppressed as recoverable churn (no user-facing report)...
-    expect(shouldRecordProcessGoneCrash({ ...FIELD_GPU_EVENT, exitCode: -2147483645 })).toBe(false)
+    expect(
+      shouldRecordProcessGoneCrash({
+        ...FIELD_GPU_EVENT,
+        platform: 'win32',
+        exitCode: -2147483645
+      })
+    ).toBe(false)
     // ...but the fallback path reads the raw child-process-gone event, so the
     // suppression cannot hide a broken driver from recovery.
     expect(
diff --git a/src/main/crash-reporting/process-gone-classification.test.ts b/src/main/crash-reporting/process-gone-classification.test.ts
index 78522b76617..c26d3385406 100644
--- a/src/main/crash-reporting/process-gone-classification.test.ts
+++ b/src/main/crash-reporting/process-gone-classification.test.ts
@@ -1,9 +1,20 @@
 import { describe, expect, it } from 'vitest'
 import {
-  shouldRecordProcessGoneCrash,
+  shouldRecordProcessGoneCrash as classifyProcessGoneCrash,
   shouldRecoverRendererAfterProcessGone
 } from './process-gone-classification'
 
+type ProcessGoneClassificationInput = Parameters<typeof classifyProcessGoneCrash>[0]
+
+function shouldRecordProcessGoneCrash({
+  platform = 'darwin',
+  ...event
+}: Omit<ProcessGoneClassificationInput, 'platform'> & {
+  platform?: NodeJS.Platform
+}): boolean {
+  return classifyProcessGoneCrash({ platform, ...event })
+}
+
 describe('shouldRecordProcessGoneCrash', () => {
   it('suppresses killed process exits during expected lifecycle teardown', () => {
     expect(
@@ -258,15 +269,36 @@ describe('shouldRecordProcessGoneCrash', () => {
     ).toBe(true)
   })
 
-  it('still records renderer kills from the recent Linux crash-report cluster', () => {
+  it('suppresses namespace-encoded SIGTERM kills from the recent Linux cluster', () => {
     expect(
       shouldRecordProcessGoneCrash({
+        platform: 'linux',
         source: 'renderer',
         processType: 'renderer',
         reason: 'killed',
         exitCode: 61696,
         expectedTeardown: 'none'
       })
+    ).toBe(false)
+  })
+
+  it('keeps wait status 61696 reportable outside the exact Linux killed boundary', () => {
+    const processGone = {
+      source: 'renderer' as const,
+      processType: 'renderer',
+      reason: 'killed',
+      exitCode: 61696,
+      expectedTeardown: 'none' as const
+    }
+
+    expect(shouldRecordProcessGoneCrash({ ...processGone, platform: 'darwin' })).toBe(true)
+    expect(shouldRecordProcessGoneCrash({ ...processGone, platform: 'win32' })).toBe(true)
+    expect(
+      shouldRecordProcessGoneCrash({
+        ...processGone,
+        platform: 'linux',
+        reason: 'abnormal-exit'
+      })
     ).toBe(true)
   })
 
@@ -285,6 +317,7 @@ describe('shouldRecordProcessGoneCrash', () => {
   it('records non-SIGTERM killed process exits outside expected lifecycle teardown', () => {
     expect(
       shouldRecordProcessGoneCrash({
+        platform: 'linux',
         source: 'renderer',
         processType: 'renderer',
         reason: 'killed',
@@ -339,6 +372,15 @@ describe('shouldRecordProcessGoneCrash', () => {
 })
 
 describe('shouldRecoverRendererAfterProcessGone', () => {
+  it('recovers unexpected killed renderers', () => {
+    expect(
+      shouldRecoverRendererAfterProcessGone({
+        reason: 'killed',
+        expectedTeardown: 'none'
+      })
+    ).toBe(true)
+  })
+
   it('does not recover expected renderer reload teardown', () => {
     expect(
       shouldRecoverRendererAfterProcessGone({
diff --git a/src/main/crash-reporting/process-gone-classification.ts b/src/main/crash-reporting/process-gone-classification.ts
index d3f363d1332..ee6dcdc868d 100644
--- a/src/main/crash-reporting/process-gone-classification.ts
+++ b/src/main/crash-reporting/process-gone-classification.ts
@@ -2,6 +2,8 @@ export type ProcessGoneSource = 'renderer' | 'child'
 export type ExpectedTeardownScope = 'none' | 'renderer-reload' | 'app-shutdown'
 
 const WINDOWS_CONTROL_TERMINATION_EXIT_CODES = new Set([0xc000013a, 0x40010004])
+// Chromium's PID-namespace SIGTERM handler exits 241; waitpid reports 241 << 8.
+const LINUX_NAMESPACE_SIGTERM_WAIT_STATUS = 0xf100
 const RECOVERABLE_CHILD_PROCESS_TYPES = new Set(['gpu'])
 const RECOVERABLE_UTILITY_SERVICE_NAMES = new Set([
   'audio.mojom.AudioService',
@@ -49,6 +51,7 @@ function isRecoverableChromiumChildProcess({
 }
 
 export function shouldRecordProcessGoneCrash({
+  platform,
   source,
   processType,
   serviceName,
@@ -56,6 +59,7 @@ export function shouldRecordProcessGoneCrash({
   exitCode,
   expectedTeardown
 }: {
+  platform: NodeJS.Platform
   source: ProcessGoneSource
   processType?: string
   serviceName?: string
@@ -76,7 +80,11 @@ export function shouldRecordProcessGoneCrash({
   // Why: Electron reports expected Chromium teardown during reload/update as
   // `killed` + SIGTERM or Windows control termination statuses. Treat real
   // crash reasons as reportable, but skip these normal termination shapes.
-  if (exitCode === 15 || isWindowsControlTerminationExitCode(exitCode)) {
+  if (
+    exitCode === 15 ||
+    isWindowsControlTerminationExitCode(exitCode) ||
+    (platform === 'linux' && exitCode === LINUX_NAMESPACE_SIGTERM_WAIT_STATUS)
+  ) {
     return false
   }
   if (expectedTeardown === 'app-shutdown') {
diff --git a/src/main/crash-reporting/process-gone-recorder.test.ts b/src/main/crash-reporting/process-gone-recorder.test.ts
index 95dbd992401..6c5962f688e 100644
--- a/src/main/crash-reporting/process-gone-recorder.test.ts
+++ b/src/main/crash-reporting/process-gone-recorder.test.ts
@@ -117,6 +117,41 @@ describe('recordProcessGoneCrash', () => {
     expect(sink.flushMock).toHaveBeenCalledOnce()
   })
 
+  it('durably suppresses a Linux namespace-encoded renderer SIGTERM', () => {
+    const record = vi.fn()
+
+    withStubbedPlatform('linux', () => {
+      recordProcessGoneCrash(
+        { record } as never,
+        event({ reason: 'killed', exitCode: 61696 }),
+        new ProcessGoneDedupe()
+      )
+    })
+
+    expect(record).not.toHaveBeenCalled()
+    expect(getCrashBreadcrumbSnapshot()).toEqual([
+      expect.objectContaining({
+        name: 'process_gone_suppressed',
+        data: expect.objectContaining({
+          source: 'renderer',
+          reason: 'killed',
+          exitCode: 61696,
+          expectedTeardown: 'none'
+        })
+      })
+    ])
+    expect(sink.records).toEqual([
+      expect.objectContaining({
+        name: 'crash.breadcrumb',
+        attributes: expect.objectContaining({
+          'breadcrumb.name': 'process_gone_suppressed',
+          'breadcrumb.data': expect.objectContaining({ exitCode: 61696 })
+        })
+      })
+    ])
+    expect(sink.flushMock).toHaveBeenCalledOnce()
+  })
+
   it('keeps suppressed renderer evidence scoped to its renderer', () => {
     const dedupe = new ProcessGoneDedupe()
     const suppressed = (webContentsId: number) =>
@@ -475,10 +510,10 @@ describe('recordProcessGoneCrash', () => {
     }
   }
 
-  // Why child kills: the decode gate is source-agnostic and reads
+  // Why child exits: the decode gate is source-agnostic and reads
   // process.platform synchronously at record time, so the platform stub is
   // still in force when it runs.
-  const nonRecoverableChildKill = (
+  const nonRecoverableChildExit = (
     overrides: Partial<ProcessGoneCrashEvent>
   ): ProcessGoneCrashEvent =>
     event({
@@ -494,7 +529,7 @@ describe('recordProcessGoneCrash', () => {
     withStubbedPlatform('linux', () => {
       recordProcessGoneCrash(
         { record } as never,
-        nonRecoverableChildKill({ reason: 'killed', exitCode: 61696 }),
+        nonRecoverableChildExit({ reason: 'abnormal-exit', exitCode: 61696 }),
         new ProcessGoneDedupe()
       )
     })
@@ -518,14 +553,14 @@ describe('recordProcessGoneCrash', () => {
     withStubbedPlatform('win32', () => {
       recordProcessGoneCrash(
         { record } as never,
-        nonRecoverableChildKill({ reason: 'killed', exitCode: 1 }),
+        nonRecoverableChildExit({ reason: 'killed', exitCode: 1 }),
         new ProcessGoneDedupe()
       )
     })
     withStubbedPlatform('linux', () => {
       recordProcessGoneCrash(
         { record } as never,
-        nonRecoverableChildKill({ reason: 'launch-failed', exitCode: 18 }),
+        nonRecoverableChildExit({ reason: 'launch-failed', exitCode: 18 }),
         new ProcessGoneDedupe()
       )
     })
diff --git a/src/main/crash-reporting/process-gone-recorder.ts b/src/main/crash-reporting/process-gone-recorder.ts
index 47ac561c4a7..acb33c71b7e 100644
--- a/src/main/crash-reporting/process-gone-recorder.ts
+++ b/src/main/crash-reporting/process-gone-recorder.ts
@@ -80,10 +80,6 @@ const captureProcessMinidump: MinidumpCapture = (crashedAtMs, expectedProcessTyp
 // one here would weaken the other 30s coalescers. Stay uniform with them.
 const SUPPRESSED_PROCESS_GONE_COALESCE_MS = 30_000
 
-function processGoneBreadcrumbData(event: ProcessGoneCrashEvent) {
-  return buildSuppressedProcessGoneBreadcrumbData(event)
-}
-
 function processGoneRendererOrigin(event: ProcessGoneCrashEvent): string | undefined {
   return event.webContentsId === undefined
     ? undefined
@@ -122,7 +118,7 @@ function persistFailureData(event: ProcessGoneCrashEvent, error: unknown) {
       ? error.code
       : undefined
   return {
-    ...processGoneBreadcrumbData(event),
+    ...buildSuppressedProcessGoneBreadcrumbData(event),
     errorName: error instanceof Error ? error.name : typeof error,
     errorMessage: sanitizeCrashReportString(error instanceof Error ? error.message : String(error)),
     ...(errorCode ? { errorCode } : {})
@@ -194,6 +190,7 @@ export function recordProcessGoneCrash(
   scheduleCrashpadDumpPrune()
   if (
     !shouldRecordProcessGoneCrash({
+      platform: process.platform,
       source: event.source,
       processType: event.processType,
       serviceName,
@@ -205,7 +202,7 @@ export function recordProcessGoneCrash(
     // Why: Chromium can crash-loop a recoverable child (network service seen at
     // 1459/min) and each suppressed event costs a span plus a forced disk flush,
     // which both floods the 30-entry ring and evicts the real pre-crash trail.
-    const suppressedData = processGoneBreadcrumbData(event)
+    const suppressedData = buildSuppressedProcessGoneBreadcrumbData(event)
     const origin = processGoneRendererOrigin(event)
     recordCoalescedDurableCrashBreadcrumb({
       name: 'process_gone_suppressed',
@@ -221,7 +218,7 @@ export function recordProcessGoneCrash(
   if (!store) {
     recordDurableCrashBreadcrumb(
       'crash_report_store_unavailable',
-      processGoneBreadcrumbData(event),
+      buildSuppressedProcessGoneBreadcrumbData(event),
       'Crash report store unavailable',
       processGoneRendererOrigin(event)
     )
@@ -305,7 +302,7 @@ export function recordProcessGoneCrash(
     siblingDeaths,
     (reportId, details) => store.attachDetails(reportId, details),
     recorded,
-    processGoneBreadcrumbData(event),
+    buildSuppressedProcessGoneBreadcrumbData(event),
     processGoneRendererOrigin(event)
   )
   void recorded
@@ -322,7 +319,7 @@ export function recordProcessGoneCrash(
         console.error('[crash-reporting] Failed to attach minidump signature:', error)
         recordDurableCrashBreadcrumb(
           'minidump_signature_attach_failed',
-          processGoneBreadcrumbData(event),
+          buildSuppressedProcessGoneBreadcrumbData(event),
           error instanceof Error ? error.message : String(error),
           processGoneRendererOrigin(event)
         )

From 63ff0a515da4dbf9bd241cb3a956be538069b55a Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sat, 29 Aug 2026 19:53:50 -0700
Subject: [PATCH 19/31] Prime native cache before E2E fanout (#17280)

* Prime E2E native cache before fanout

* Update E2E permission contract
---
 .github/workflows/e2e.yml                     | 37 +++++++++++++++----
 .../release-cut-token-permissions.test.mjs    |  1 +
 .../release-e2e-dispatch-contract.test.mjs    | 24 +++++++++++-
 3 files changed, 54 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/e2e.yml b/.github/workflows/e2e.yml
index 92e33a18d19..c23aa0cb679 100644
--- a/.github/workflows/e2e.yml
+++ b/.github/workflows/e2e.yml
@@ -55,9 +55,13 @@ jobs:
         env:
           VITE_EXPOSE_STORE: 'true'
         run: |
-          npx electron-vite build --mode e2e
-          pnpm run build:web-from-renderer
-          pnpm run build:relay
+          status=0
+          pnpm run build:relay &
+          relay_pid=$!
+          npx electron-vite build --mode e2e || status=1
+          pnpm run build:web-from-renderer || status=1
+          wait "$relay_pid" || status=1
+          exit "$status"
 
       - name: Upload E2E build output
         uses: actions/upload-artifact@v7
@@ -71,9 +75,29 @@ jobs:
           retention-days: 1
           if-no-files-found: error
 
+  # Build Electron-native dependencies once per workflow. Consumer shards restore
+  # this immutable cache instead of compiling the same ABI concurrently.
+  prepare-native-cache:
+    name: prepare Electron native cache
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.ref || github.ref }}
+
+      - name: Install native build tools
+        run: sudo apt-get update && sudo apt-get install -y build-essential python3
+
+      - uses: ./.github/actions/install-node-dependencies
+        with:
+          native-runtime: electron
+
   e2e:
     name: e2e ${{ matrix.shard_name }}
-    needs: build
+    needs: [build, prepare-native-cache]
     if: inputs.test_files == ''
     runs-on: ubuntu-latest
     timeout-minutes: 30
@@ -159,7 +183,7 @@ jobs:
 
   changed-e2e:
     name: changed e2e specs
-    needs: build
+    needs: [build, prepare-native-cache]
     if: inputs.test_files != ''
     runs-on: ubuntu-latest
     # Why 45: pr.yml now maps SSH source edits onto Docker-backed specs, so this lane can
@@ -227,8 +251,7 @@ jobs:
 
   ssh-docker-watcher-isolation:
     name: ssh docker watcher isolation
-    needs: build
-    # Why ssh_source_changed first: this lane used to trigger on SSH source only as a side
+    needs: [build, prepare-native-cache]
     # effect of one route listing a startup-readiness spec — pruning that spec would have
     # silently retired the whole lane. The signal is now derived from the SSH routes directly.
     # The two spec clauses stay for their honest purpose: changed-e2e hands these specs to this
diff --git a/config/scripts/release-cut-token-permissions.test.mjs b/config/scripts/release-cut-token-permissions.test.mjs
index 24f138723c9..2478087ba8a 100644
--- a/config/scripts/release-cut-token-permissions.test.mjs
+++ b/config/scripts/release-cut-token-permissions.test.mjs
@@ -8,6 +8,7 @@ const EXPECTED_MATRIX = {
   '.github/workflows/e2e.yml#build': { contents: 'read' },
   '.github/workflows/e2e.yml#changed-e2e': { contents: 'read' },
   '.github/workflows/e2e.yml#e2e': { contents: 'read' },
+  '.github/workflows/e2e.yml#prepare-native-cache': { contents: 'read' },
   '.github/workflows/e2e.yml#ssh-docker-watcher-isolation': { contents: 'read' },
   '.github/workflows/homebrew-bump.yml#bump-cask': { contents: 'read' },
   '.github/workflows/release-mac-build.yml#build-mac': { contents: 'write' },
diff --git a/config/scripts/release-e2e-dispatch-contract.test.mjs b/config/scripts/release-e2e-dispatch-contract.test.mjs
index d48c7b3fa30..5fd4503d4e3 100644
--- a/config/scripts/release-e2e-dispatch-contract.test.mjs
+++ b/config/scripts/release-e2e-dispatch-contract.test.mjs
@@ -46,6 +46,28 @@ describe('release E2E dispatch contract', () => {
     expect(refInput.required).toBe(false)
   })
 
+  it('overlaps the relay bundle with the Electron build', () => {
+    const buildStep = e2eWorkflow.jobs.build.steps.find((step) => step.name === 'Build E2E outputs')
+
+    expect(buildStep.run).toContain('pnpm run build:relay &')
+    expect(buildStep.run).toContain('relay_pid=$!')
+    expect(buildStep.run).toContain('wait "$relay_pid"')
+    expect(buildStep.run).toContain('pnpm run build:web-from-renderer')
+  })
+
+  it('primes the Electron native cache before every E2E consumer', () => {
+    const primer = e2eWorkflow.jobs['prepare-native-cache']
+    expect(primer.steps).toBeDefined()
+    expect(
+      primer.steps.find((step) => step.uses === './.github/actions/install-node-dependencies').with
+    ).toEqual({
+      'native-runtime': 'electron'
+    })
+    for (const jobName of ['e2e', 'changed-e2e', 'ssh-docker-watcher-isolation']) {
+      expect(e2eWorkflow.jobs[jobName].needs, jobName).toEqual(['build', 'prepare-native-cache'])
+    }
+  })
+
   it('includes the paired-runtime web client in the shared E2E build artifact', () => {
     const buildStep = e2eWorkflow.jobs.build.steps.find((step) => step.name === 'Build E2E outputs')
 
@@ -71,7 +93,7 @@ describe('release E2E dispatch contract', () => {
       const downloadStep = job.steps.find((step) => step.name === 'Download E2E build output')
       const runStep = job.steps.find((step) => step.name === runStepName)
 
-      expect(job.needs).toBe('build')
+      expect(job.needs).toEqual(['build', 'prepare-native-cache'])
       expect(downloadStep.with.name).toBe('e2e-build-out')
       expect(downloadStep.with.path).toBe('out/')
       expect(runStep.run).toContain('ORCA_RELAY_PATH="$GITHUB_WORKSPACE/out/relay"')

From 53eb21b44809da3bb66e5b5ca3a5308d9509bc04 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sat, 29 Aug 2026 20:04:04 -0700
Subject: [PATCH 20/31] Split speech session lifecycle (#17123)

* Split speech session lifecycle

* Fix F3-speech for #17123
---
 config/max-lines-baseline.txt           |   1 -
 src/main/speech/stt-service.ts          | 472 ++----------------------
 src/main/speech/stt-session-start.ts    | 164 ++++++++
 src/main/speech/stt-session-state.ts    |  48 +++
 src/main/speech/stt-session-stop.ts     | 197 ++++++++++
 src/main/speech/stt-session-timeouts.ts |   3 +
 src/main/speech/stt-worker-startup.ts   |  97 +++++
 7 files changed, 530 insertions(+), 452 deletions(-)
 create mode 100644 src/main/speech/stt-session-start.ts
 create mode 100644 src/main/speech/stt-session-state.ts
 create mode 100644 src/main/speech/stt-session-stop.ts
 create mode 100644 src/main/speech/stt-session-timeouts.ts
 create mode 100644 src/main/speech/stt-worker-startup.ts

diff --git a/config/max-lines-baseline.txt b/config/max-lines-baseline.txt
index 75e536a2198..8d2496f1d69 100644
--- a/config/max-lines-baseline.txt
+++ b/config/max-lines-baseline.txt
@@ -28,7 +28,6 @@ inline src/main/runtime/orca-runtime.ts
 inline src/main/runtime/rpc/methods/orchestration.ts
 inline src/main/runtime/runtime-rpc.ts
 inline src/main/source-control/hosted-review-creation.ts
-inline src/main/speech/stt-service.ts
 inline src/main/ssh/ssh-channel-multiplexer.ts
 inline src/main/ssh/ssh-connection.ts
 inline src/main/ssh/ssh-relay-deploy.ts
diff --git a/src/main/speech/stt-service.ts b/src/main/speech/stt-service.ts
index a840d7aa256..21d3fba2714 100644
--- a/src/main/speech/stt-service.ts
+++ b/src/main/speech/stt-service.ts
@@ -1,16 +1,9 @@
-/* eslint-disable max-lines -- Why: speech worker ownership, warm reuse, and
-timeout teardown stay co-located so dictation lifecycle state cannot drift. */
-import { Worker } from 'node:worker_threads'
-import { getCatalogModel } from './model-catalog'
 import type { ModelManager } from './model-manager'
-import { OpenAiTranscriptionSession } from './openai-transcription-client'
-import { readOpenAiSpeechApiKey } from './openai-api-key-store'
-import { getSherpaModulePath, getSttWorkerPath } from './stt-worker-paths'
-import { waitForSttWorkerStop, type SttWorkerStopOutcome } from './stt-worker-stop'
+import { startSttDictation } from './stt-session-start'
+import { createSttSessionState, type SttSessionState } from './stt-session-state'
+import { prepareSttModelForDeletion, stopSttDictation } from './stt-session-stop'
 
-export const START_DICTATION_TIMEOUT_MS = 60_000
-const STOP_DICTATION_TIMEOUT_MS = 60_000
-export const IDLE_WORKER_TEARDOWN_MS = 60 * 60 * 1000
+export { IDLE_WORKER_TEARDOWN_MS, START_DICTATION_TIMEOUT_MS } from './stt-session-timeouts'
 
 export type SttEvent =
   | { type: 'ready' }
@@ -21,481 +14,58 @@ export type SttEvent =
 
 export type SttEventSink = (event: SttEvent) => void
 
-type StopInFlight = {
-  worker: Worker
-  owner: string
-  promise: Promise<void>
-}
-
 export class SttService {
-  private worker: Worker | null = null
-  private cloudSession: OpenAiTranscriptionSession | null = null
-  private modelManager: ModelManager
-  private activeModelId: string | null = null
-  private activeHotwordsFilePath: string | undefined
-  private activeOwner: string | null = null
-  private startingOwner: string | null = null
-  private startingModelId: string | null = null
-  private starting = false
-  private canceledOwners = new Set<string>()
-  private eventSink: SttEventSink | null = null
-  private idleTeardownTimer: NodeJS.Timeout | null = null
-  private stopInFlight: StopInFlight | null = null
-  // Why: stop resolves only after the worker flushes; in-flight feedAudio IPC
-  // must not enqueue samples after that flush or they stick on the warm worker
-  // and contaminate the next dictation session.
-  private stopping = false
-  // Why: warm workers intentionally keep lifecycle listeners while reusable;
-  // stale workers must not retain this service after error, exit, or teardown.
-  private cleanupWorkerLifecycleListeners: (() => void) | null = null
+  private readonly state: SttSessionState
 
   constructor(modelManager: ModelManager) {
-    this.modelManager = modelManager
+    this.state = createSttSessionState(modelManager)
   }
 
-  async startDictation(
+  startDictation(
     modelId: string,
     sink: SttEventSink,
     hotwordsFilePath?: string,
     owner = 'desktop'
   ): Promise<void> {
-    if (this.starting) {
-      if (this.startingOwner !== owner) {
-        throw new Error('dictation_already_active')
-      }
-      return
-    }
-    if ((this.worker || this.cloudSession) && this.activeOwner && this.activeOwner !== owner) {
-      throw new Error('dictation_already_active')
-    }
-    this.starting = true
-    this.startingOwner = owner
-    this.startingModelId = modelId
-    this.clearIdleTeardownTimer()
-
-    try {
-      await this._startDictation(modelId, sink, hotwordsFilePath, owner)
-      if (this.canceledOwners.delete(owner)) {
-        await this.stopDictation(owner, { cancelStarting: false })
-        throw new Error('dictation_canceled')
-      }
-      this.activeOwner = owner
-    } finally {
-      this.starting = false
-      this.startingOwner = null
-      this.startingModelId = null
-      this.canceledOwners.delete(owner)
-    }
-  }
-
-  private async _startDictation(
-    modelId: string,
-    sink: SttEventSink,
-    hotwordsFilePath?: string,
-    owner = 'desktop'
-  ): Promise<void> {
-    const manifest = getCatalogModel(modelId)
-    if (!manifest) {
-      throw new Error(`Unknown model: ${modelId}`)
-    }
-
-    if (manifest.provider === 'openai') {
-      if (this.worker) {
-        const existingWorker = this.worker
-        await this.stopDictation(owner, { cancelStarting: false })
-        await this.teardownWorker(existingWorker)
-      }
-
-      const modelState = await this.modelManager.getModelState(modelId)
-      if (modelState.status !== 'ready') {
-        throw new Error(`Model not ready: ${modelState.status}`)
-      }
-
-      this.cloudSession = new OpenAiTranscriptionSession(modelId, readOpenAiSpeechApiKey)
-      this.activeModelId = modelId
-      this.activeHotwordsFilePath = undefined
-      this.eventSink = sink
-      sink({ type: 'ready' })
-      return
-    }
-
-    if (this.cloudSession) {
-      await this.stopDictation(owner, { cancelStarting: false })
-    }
-
-    const reusableWorker = this.worker
-    if (
-      reusableWorker &&
-      this.activeModelId === modelId &&
-      this.activeHotwordsFilePath === hotwordsFilePath &&
-      this.stopInFlight?.worker !== reusableWorker
-    ) {
-      const worker = reusableWorker
-      if (!this.activeOwner) {
-        const modelState = await this.modelManager.getModelState(modelId)
-        if (modelState.status !== 'ready') {
-          await this.teardownWorker(worker)
-          throw new Error(`Model not ready: ${modelState.status}`)
-        }
-      }
-      if (
-        this.worker === worker &&
-        this.activeModelId === modelId &&
-        this.activeHotwordsFilePath === hotwordsFilePath &&
-        this.stopInFlight?.worker !== worker
-      ) {
-        this.eventSink = sink
-        sink({ type: 'ready' })
-        return
-      }
-    }
-
-    if (this.worker) {
-      const existingWorker = this.worker
-      await this.stopDictation(owner, { cancelStarting: false })
-      await this.teardownWorker(existingWorker)
-    }
-
-    const modelState = await this.modelManager.getModelState(modelId)
-    if (modelState.status !== 'ready') {
-      throw new Error(`Model not ready: ${modelState.status}`)
-    }
-
-    const workerPath = getSttWorkerPath()
-    const sherpaModulePath = getSherpaModulePath()
-
-    this.worker = new Worker(workerPath, {
-      workerData: { sherpaModulePath }
-    })
-    const worker = this.worker
-
-    this.activeModelId = modelId
-    this.activeHotwordsFilePath = hotwordsFilePath
-    this.eventSink = sink
-
-    const readyPromise = new Promise<void>((resolve, reject) => {
-      let settled = false
-      let startupTimeout: ReturnType<typeof setTimeout> | null = null
-      const cleanup = () => {
-        if (startupTimeout) {
-          clearTimeout(startupTimeout)
-          startupTimeout = null
-        }
-        worker.off('message', onReadyOrError)
-        worker.off('error', onStartupError)
-        worker.off('exit', onStartupExit)
-      }
-      const failStartup = (error: Error): void => {
-        if (settled) {
-          return
-        }
-        settled = true
-        cleanup()
-        reject(error)
-      }
-      const onReadyOrError = (msg: { type: string; text?: string; error?: string }) => {
-        if (settled) {
-          return
-        }
-        if (msg.type === 'ready') {
-          settled = true
-          cleanup()
-          resolve()
-        } else if (msg.type === 'error') {
-          failStartup(new Error(msg.error ?? 'Speech worker failed to initialize'))
-        }
-      }
-      const onStartupError = (err: Error) => {
-        failStartup(err)
-      }
-      const onStartupExit = (code: number) => {
-        failStartup(new Error(`Speech worker exited before ready: ${code}`))
-      }
-      worker.on('message', onReadyOrError)
-      worker.on('error', onStartupError)
-      worker.on('exit', onStartupExit)
-      // Why: a native STT worker can wedge while loading model bindings without
-      // emitting ready/error/exit; startup must leave the UI's Starting state.
-      startupTimeout = setTimeout(() => {
-        failStartup(new Error('Speech worker timed out while starting.'))
-      }, START_DICTATION_TIMEOUT_MS)
-      startupTimeout.unref?.()
-    })
-
-    const onWorkerMessage = (msg: SttEvent) => {
-      if (this.worker === worker) {
-        this.eventSink?.(msg)
-      }
-    }
-
-    const onWorkerError = (err: Error) => {
-      if (this.worker === worker) {
-        this.eventSink?.({ type: 'error', error: String(err) })
-        this.cleanupActiveWorkerLifecycleListeners()
-        this.worker = null
-        this.activeModelId = null
-        this.activeHotwordsFilePath = undefined
-        this.activeOwner = null
-        this.eventSink = null
-      }
-    }
-
-    const onWorkerExit = () => {
-      if (this.worker === worker) {
-        this.cleanupActiveWorkerLifecycleListeners()
-        this.worker = null
-        this.activeModelId = null
-        this.activeHotwordsFilePath = undefined
-        this.activeOwner = null
-        this.eventSink = null
-      }
-    }
-
-    worker.on('message', onWorkerMessage)
-    worker.on('error', onWorkerError)
-    worker.on('exit', onWorkerExit)
-    this.cleanupWorkerLifecycleListeners = () => {
-      worker.off('message', onWorkerMessage)
-      worker.off('error', onWorkerError)
-      worker.off('exit', onWorkerExit)
-    }
-
-    const modelDir = this.modelManager.getModelDir(modelId)
-    worker.postMessage({
-      type: 'init',
-      modelDir,
-      modelType: manifest.type,
-      streaming: manifest.streaming,
-      sampleRate: manifest.sampleRate,
-      files: manifest.files ?? [],
-      hotwordsFilePath,
-      modelingUnit: manifest.modelingUnit
-    })
-
-    try {
-      await readyPromise
-    } catch (error) {
-      this.cleanupActiveWorkerLifecycleListeners()
-      worker.removeAllListeners()
-      void worker.terminate()
-      if (this.worker === worker) {
-        this.worker = null
-        this.activeModelId = null
-        this.activeHotwordsFilePath = undefined
-        this.activeOwner = null
-        this.eventSink = null
-      }
-      throw error
-    }
+    return startSttDictation(this.state, modelId, sink, hotwordsFilePath, owner)
   }
 
   feedAudio(samples: Float32Array, sampleRate: number, owner = 'desktop'): void {
-    if (this.stopping) {
+    if (this.state.stopping) {
       return
     }
-    const currentOwner = this.activeOwner ?? this.startingOwner
+    const currentOwner = this.state.activeOwner ?? this.state.startingOwner
     if (!currentOwner) {
       return
     }
     if (currentOwner !== owner) {
       throw new Error('dictation_owner_mismatch')
     }
-    if (this.cloudSession) {
-      this.cloudSession.feedAudio(samples, sampleRate)
+    if (this.state.cloudSession) {
+      this.state.cloudSession.feedAudio(samples, sampleRate)
       return
     }
-    this.worker?.postMessage({ type: 'feed', samples, sampleRate }, [samples.buffer as ArrayBuffer])
+    this.state.worker?.postMessage({ type: 'feed', samples, sampleRate }, [
+      samples.buffer as ArrayBuffer
+    ])
   }
 
-  async stopDictation(
+  stopDictation(
     owner = 'desktop',
     options: { cancelStarting?: boolean } = { cancelStarting: true }
   ): Promise<void> {
-    if (options.cancelStarting !== false && this.startingOwner === owner) {
-      this.canceledOwners.add(owner)
-    }
-    if (!this.worker && !this.cloudSession) {
-      return
-    }
-    const currentOwner = this.activeOwner ?? this.startingOwner
-    if (currentOwner && currentOwner !== owner) {
-      throw new Error('dictation_owner_mismatch')
-    }
-
-    if (this.cloudSession) {
-      this.stopping = true
-      try {
-        const session = this.cloudSession
-        this.cloudSession = null
-        try {
-          const text = await session.finish()
-          if (text) {
-            this.eventSink?.({ type: 'final', text })
-          }
-        } catch (error) {
-          this.eventSink?.({
-            type: 'error',
-            error: error instanceof Error ? error.message : String(error)
-          })
-        } finally {
-          this.eventSink?.({ type: 'stopped' })
-          this.activeModelId = null
-          this.activeHotwordsFilePath = undefined
-          this.activeOwner = null
-          this.eventSink = null
-        }
-      } finally {
-        this.stopping = false
-      }
-      return
-    }
-
-    const worker = this.worker
-    if (!worker) {
-      return
-    }
-    if (this.stopInFlight?.worker === worker) {
-      if (this.stopInFlight.owner !== owner) {
-        throw new Error('dictation_owner_mismatch')
-      }
-      return this.stopInFlight.promise
-    }
-
-    const capturedSink = this.eventSink
-    let stopPromise!: Promise<void>
-    stopPromise = this.createStopPromise(worker, capturedSink).finally(() => {
-      if (this.stopInFlight?.worker === worker && this.stopInFlight.promise === stopPromise) {
-        this.stopInFlight = null
-      }
-    })
-    this.stopInFlight = { worker, owner, promise: stopPromise }
-    this.stopping = true
-    try {
-      // Why: keep the stop message inside the try so a postMessage throw still
-      // clears `stopping` — otherwise feedAudio silently drops all future audio.
-      worker.postMessage({ type: 'stop' })
-      await stopPromise
-    } finally {
-      this.stopping = false
-    }
-  }
-
-  private createStopPromise(worker: Worker, capturedSink: SttEventSink | null): Promise<void> {
-    return waitForSttWorkerStop({
-      worker,
-      capturedSink,
-      timeoutMs: STOP_DICTATION_TIMEOUT_MS,
-      finish: (outcome) => this.finishWorkerStop(worker, outcome)
-    })
-  }
-
-  private finishWorkerStop(worker: Worker, outcome: SttWorkerStopOutcome): void {
-    if (outcome === 'stopped') {
-      if (this.worker === worker) {
-        this.activeOwner = null
-        this.eventSink = null
-        this.scheduleIdleTeardown()
-      }
-      return
-    }
-    // Why: a worker that cannot finish dictation is no longer reusable; drop
-    // its lifecycle listeners so a stale worker can't retain this service.
-    this.cleanupActiveWorkerLifecycleListeners()
-    worker.removeAllListeners()
-    if (outcome !== 'exit') {
-      void worker.terminate().catch(() => undefined)
-    }
-    if (this.worker === worker) {
-      this.worker = null
-      this.activeModelId = null
-      this.activeHotwordsFilePath = undefined
-      this.activeOwner = null
-      this.eventSink = null
-    }
+    return stopSttDictation(this.state, owner, options)
   }
 
   isActive(): boolean {
-    return this.worker !== null || this.cloudSession !== null
+    return this.state.worker !== null || this.state.cloudSession !== null
   }
 
   getActiveModelId(): string | null {
-    return this.activeModelId
+    return this.state.activeModelId
   }
 
-  async prepareModelForDeletion(modelId: string): Promise<void> {
-    if (this.startingModelId === modelId || (this.activeOwner && this.activeModelId === modelId)) {
-      throw new Error('voice_model_in_use')
-    }
-    if (this.worker && this.activeModelId === modelId) {
-      await this.teardownIdleWorker({ ignoreTerminateErrors: false })
-      if (this.worker && this.activeModelId === modelId) {
-        throw new Error('voice_model_in_use')
-      }
-    }
-  }
-
-  private clearIdleTeardownTimer(): void {
-    if (this.idleTeardownTimer) {
-      clearTimeout(this.idleTeardownTimer)
-      this.idleTeardownTimer = null
-    }
-  }
-
-  private scheduleIdleTeardown(): void {
-    this.clearIdleTeardownTimer()
-    // Why: keep the native recognizer warm for repeated dictations, but release
-    // the ONNX model after a quiet period so long-running Orca sessions don't
-    // pin speech memory forever.
-    this.idleTeardownTimer = setTimeout(() => {
-      void this.teardownIdleWorker()
-    }, IDLE_WORKER_TEARDOWN_MS)
-    this.idleTeardownTimer.unref?.()
-  }
-
-  private async teardownIdleWorker(
-    options: { ignoreTerminateErrors?: boolean } = { ignoreTerminateErrors: true }
-  ): Promise<void> {
-    this.clearIdleTeardownTimer()
-    if (!this.worker || this.activeOwner || this.startingOwner) {
-      return
-    }
-    await this.teardownWorker(this.worker, options)
-  }
-
-  private async teardownWorker(
-    worker: Worker,
-    options: { ignoreTerminateErrors?: boolean } = { ignoreTerminateErrors: true }
-  ): Promise<void> {
-    this.clearIdleTeardownTimer()
-    if (this.stopInFlight?.worker === worker) {
-      await this.stopInFlight.promise
-    }
-    try {
-      worker.postMessage({ type: 'teardown' })
-    } catch {
-      // The worker may already have exited on a forced stop path.
-    }
-    this.cleanupActiveWorkerLifecycleListeners()
-    worker.removeAllListeners()
-    try {
-      await worker.terminate()
-    } catch (error) {
-      if (!options.ignoreTerminateErrors) {
-        throw error
-      }
-    }
-    if (this.worker === worker) {
-      this.worker = null
-      this.activeModelId = null
-      this.activeHotwordsFilePath = undefined
-      this.activeOwner = null
-      this.eventSink = null
-    }
-  }
-
-  private cleanupActiveWorkerLifecycleListeners(): void {
-    const cleanup = this.cleanupWorkerLifecycleListeners
-    this.cleanupWorkerLifecycleListeners = null
-    cleanup?.()
+  prepareModelForDeletion(modelId: string): Promise<void> {
+    return prepareSttModelForDeletion(this.state, modelId)
   }
 }
diff --git a/src/main/speech/stt-session-start.ts b/src/main/speech/stt-session-start.ts
new file mode 100644
index 00000000000..5377699b382
--- /dev/null
+++ b/src/main/speech/stt-session-start.ts
@@ -0,0 +1,164 @@
+import { Worker } from 'node:worker_threads'
+import { getCatalogModel } from './model-catalog'
+import { OpenAiTranscriptionSession } from './openai-transcription-client'
+import { readOpenAiSpeechApiKey } from './openai-api-key-store'
+import type { SttEventSink } from './stt-service'
+import type { SttSessionState } from './stt-session-state'
+import {
+  clearSttIdleTeardownTimer,
+  cleanupActiveSttWorkerLifecycleListeners,
+  handleSttWorkerFailure,
+  stopSttDictation,
+  teardownSttWorker
+} from './stt-session-stop'
+import { getSherpaModulePath, getSttWorkerPath } from './stt-worker-paths'
+import {
+  attachSttWorkerLifecycle,
+  initializeSttWorker,
+  waitForSttWorkerReady
+} from './stt-worker-startup'
+import { START_DICTATION_TIMEOUT_MS } from './stt-session-timeouts'
+
+export async function startSttDictation(
+  state: SttSessionState,
+  modelId: string,
+  sink: SttEventSink,
+  hotwordsFilePath?: string,
+  owner = 'desktop'
+): Promise<void> {
+  if (state.starting) {
+    if (state.startingOwner !== owner) {
+      throw new Error('dictation_already_active')
+    }
+    return
+  }
+  if ((state.worker || state.cloudSession) && state.activeOwner && state.activeOwner !== owner) {
+    throw new Error('dictation_already_active')
+  }
+  state.starting = true
+  state.startingOwner = owner
+  state.startingModelId = modelId
+  clearSttIdleTeardownTimer(state)
+
+  try {
+    await startSttSession(state, modelId, sink, hotwordsFilePath, owner)
+    if (state.canceledOwners.delete(owner)) {
+      await stopSttDictation(state, owner, { cancelStarting: false })
+      throw new Error('dictation_canceled')
+    }
+    state.activeOwner = owner
+  } finally {
+    state.starting = false
+    state.startingOwner = null
+    state.startingModelId = null
+    state.canceledOwners.delete(owner)
+  }
+}
+
+async function startSttSession(
+  state: SttSessionState,
+  modelId: string,
+  sink: SttEventSink,
+  hotwordsFilePath: string | undefined,
+  owner: string
+): Promise<void> {
+  const manifest = getCatalogModel(modelId)
+  if (!manifest) {
+    throw new Error(`Unknown model: ${modelId}`)
+  }
+
+  if (manifest.provider === 'openai') {
+    if (state.worker) {
+      const existingWorker = state.worker
+      await stopSttDictation(state, owner, { cancelStarting: false })
+      await teardownSttWorker(state, existingWorker)
+    }
+    const modelState = await state.modelManager.getModelState(modelId)
+    if (modelState.status !== 'ready') {
+      throw new Error(`Model not ready: ${modelState.status}`)
+    }
+    state.cloudSession = new OpenAiTranscriptionSession(modelId, readOpenAiSpeechApiKey)
+    state.activeModelId = modelId
+    state.activeHotwordsFilePath = undefined
+    state.eventSink = sink
+    sink({ type: 'ready' })
+    return
+  }
+
+  if (state.cloudSession) {
+    await stopSttDictation(state, owner, { cancelStarting: false })
+  }
+  const reusableWorker = state.worker
+  if (
+    reusableWorker &&
+    state.activeModelId === modelId &&
+    state.activeHotwordsFilePath === hotwordsFilePath &&
+    state.stopInFlight?.worker !== reusableWorker
+  ) {
+    if (!state.activeOwner) {
+      const modelState = await state.modelManager.getModelState(modelId)
+      if (modelState.status !== 'ready') {
+        await teardownSttWorker(state, reusableWorker)
+        throw new Error(`Model not ready: ${modelState.status}`)
+      }
+    }
+    if (
+      state.worker === reusableWorker &&
+      state.activeModelId === modelId &&
+      state.activeHotwordsFilePath === hotwordsFilePath &&
+      state.stopInFlight?.worker !== reusableWorker
+    ) {
+      state.eventSink = sink
+      sink({ type: 'ready' })
+      return
+    }
+  }
+
+  if (state.worker) {
+    const existingWorker = state.worker
+    await stopSttDictation(state, owner, { cancelStarting: false })
+    await teardownSttWorker(state, existingWorker)
+  }
+  const modelState = await state.modelManager.getModelState(modelId)
+  if (modelState.status !== 'ready') {
+    throw new Error(`Model not ready: ${modelState.status}`)
+  }
+
+  const worker = new Worker(getSttWorkerPath(), {
+    workerData: { sherpaModulePath: getSherpaModulePath() }
+  })
+  state.worker = worker
+  state.activeModelId = modelId
+  state.activeHotwordsFilePath = hotwordsFilePath
+  state.eventSink = sink
+
+  const readyPromise = waitForSttWorkerReady(worker, START_DICTATION_TIMEOUT_MS)
+  state.cleanupWorkerLifecycleListeners = attachSttWorkerLifecycle({
+    worker,
+    isCurrent: () => state.worker === worker,
+    onMessage: (event) => state.eventSink?.(event),
+    onError: (error) => handleSttWorkerFailure(state, error),
+    onExit: () => handleSttWorkerFailure(state)
+  })
+  initializeSttWorker(worker, {
+    modelDir: state.modelManager.getModelDir(modelId),
+    modelType: manifest.type,
+    streaming: manifest.streaming,
+    sampleRate: manifest.sampleRate,
+    files: manifest.files ?? [],
+    hotwordsFilePath,
+    modelingUnit: manifest.modelingUnit
+  })
+
+  try {
+    await readyPromise
+  } catch (error) {
+    cleanupActiveSttWorkerLifecycleListeners(state)
+    worker.removeAllListeners()
+    void worker.terminate()
+    if (state.worker === worker) {
+      handleSttWorkerFailure(state)
+    }
+    throw error
+  }
+}
diff --git a/src/main/speech/stt-session-state.ts b/src/main/speech/stt-session-state.ts
new file mode 100644
index 00000000000..f9054b41b8d
--- /dev/null
+++ b/src/main/speech/stt-session-state.ts
@@ -0,0 +1,48 @@
+import type { Worker } from 'node:worker_threads'
+import type { ModelManager } from './model-manager'
+import type { OpenAiTranscriptionSession } from './openai-transcription-client'
+import type { SttEventSink } from './stt-service'
+
+export type StopInFlight = {
+  worker: Worker
+  owner: string
+  promise: Promise<void>
+}
+
+export type SttSessionState = {
+  worker: Worker | null
+  cloudSession: OpenAiTranscriptionSession | null
+  modelManager: ModelManager
+  activeModelId: string | null
+  activeHotwordsFilePath: string | undefined
+  activeOwner: string | null
+  startingOwner: string | null
+  startingModelId: string | null
+  starting: boolean
+  canceledOwners: Set<string>
+  eventSink: SttEventSink | null
+  idleTeardownTimer: NodeJS.Timeout | null
+  stopInFlight: StopInFlight | null
+  stopping: boolean
+  cleanupWorkerLifecycleListeners: (() => void) | null
+}
+
+export function createSttSessionState(modelManager: ModelManager): SttSessionState {
+  return {
+    worker: null,
+    cloudSession: null,
+    modelManager,
+    activeModelId: null,
+    activeHotwordsFilePath: undefined,
+    activeOwner: null,
+    startingOwner: null,
+    startingModelId: null,
+    starting: false,
+    canceledOwners: new Set(),
+    eventSink: null,
+    idleTeardownTimer: null,
+    stopInFlight: null,
+    stopping: false,
+    cleanupWorkerLifecycleListeners: null
+  }
+}
diff --git a/src/main/speech/stt-session-stop.ts b/src/main/speech/stt-session-stop.ts
new file mode 100644
index 00000000000..f8f1893a493
--- /dev/null
+++ b/src/main/speech/stt-session-stop.ts
@@ -0,0 +1,197 @@
+import type { Worker } from 'node:worker_threads'
+import type { SttSessionState } from './stt-session-state'
+import { waitForSttWorkerStop, type SttWorkerStopOutcome } from './stt-worker-stop'
+import { IDLE_WORKER_TEARDOWN_MS } from './stt-session-timeouts'
+
+const STOP_DICTATION_TIMEOUT_MS = 60_000
+
+export async function stopSttDictation(
+  state: SttSessionState,
+  owner = 'desktop',
+  options: { cancelStarting?: boolean } = { cancelStarting: true }
+): Promise<void> {
+  if (options.cancelStarting !== false && state.startingOwner === owner) {
+    state.canceledOwners.add(owner)
+  }
+  if (!state.worker && !state.cloudSession) {
+    return
+  }
+  const currentOwner = state.activeOwner ?? state.startingOwner
+  if (currentOwner && currentOwner !== owner) {
+    throw new Error('dictation_owner_mismatch')
+  }
+
+  if (state.cloudSession) {
+    state.stopping = true
+    try {
+      const session = state.cloudSession
+      state.cloudSession = null
+      try {
+        const text = await session.finish()
+        if (text) {
+          state.eventSink?.({ type: 'final', text })
+        }
+      } catch (error) {
+        state.eventSink?.({
+          type: 'error',
+          error: error instanceof Error ? error.message : String(error)
+        })
+      } finally {
+        state.eventSink?.({ type: 'stopped' })
+        state.activeModelId = null
+        state.activeHotwordsFilePath = undefined
+        state.activeOwner = null
+        state.eventSink = null
+      }
+    } finally {
+      state.stopping = false
+    }
+    return
+  }
+
+  const worker = state.worker
+  if (!worker) {
+    return
+  }
+  if (state.stopInFlight?.worker === worker) {
+    if (state.stopInFlight.owner !== owner) {
+      throw new Error('dictation_owner_mismatch')
+    }
+    return state.stopInFlight.promise
+  }
+
+  const capturedSink = state.eventSink
+  let stopPromise!: Promise<void>
+  stopPromise = waitForSttWorkerStop({
+    worker,
+    capturedSink,
+    timeoutMs: STOP_DICTATION_TIMEOUT_MS,
+    finish: (outcome) => finishSttWorkerStop(state, worker, outcome)
+  }).finally(() => {
+    if (state.stopInFlight?.worker === worker && state.stopInFlight.promise === stopPromise) {
+      state.stopInFlight = null
+    }
+  })
+  state.stopInFlight = { worker, owner, promise: stopPromise }
+  state.stopping = true
+  try {
+    worker.postMessage({ type: 'stop' })
+    await stopPromise
+  } finally {
+    state.stopping = false
+  }
+}
+
+function finishSttWorkerStop(
+  state: SttSessionState,
+  worker: Worker,
+  outcome: SttWorkerStopOutcome
+): void {
+  if (outcome === 'stopped') {
+    if (state.worker === worker) {
+      state.activeOwner = null
+      state.eventSink = null
+      scheduleSttIdleTeardown(state)
+    }
+    return
+  }
+  cleanupActiveSttWorkerLifecycleListeners(state)
+  worker.removeAllListeners()
+  if (outcome !== 'exit') {
+    void worker.terminate().catch(() => undefined)
+  }
+  if (state.worker === worker) {
+    clearSttWorkerState(state)
+  }
+}
+
+export async function prepareSttModelForDeletion(
+  state: SttSessionState,
+  modelId: string
+): Promise<void> {
+  if (state.startingModelId === modelId || (state.activeOwner && state.activeModelId === modelId)) {
+    throw new Error('voice_model_in_use')
+  }
+  if (state.worker && state.activeModelId === modelId) {
+    await teardownIdleSttWorker(state, { ignoreTerminateErrors: false })
+    if (state.worker && state.activeModelId === modelId) {
+      throw new Error('voice_model_in_use')
+    }
+  }
+}
+
+export function clearSttIdleTeardownTimer(state: SttSessionState): void {
+  if (state.idleTeardownTimer) {
+    clearTimeout(state.idleTeardownTimer)
+    state.idleTeardownTimer = null
+  }
+}
+
+function scheduleSttIdleTeardown(state: SttSessionState): void {
+  clearSttIdleTeardownTimer(state)
+  state.idleTeardownTimer = setTimeout(() => {
+    void teardownIdleSttWorker(state)
+  }, IDLE_WORKER_TEARDOWN_MS)
+  state.idleTeardownTimer.unref?.()
+}
+
+async function teardownIdleSttWorker(
+  state: SttSessionState,
+  options: { ignoreTerminateErrors?: boolean } = { ignoreTerminateErrors: true }
+): Promise<void> {
+  clearSttIdleTeardownTimer(state)
+  if (!state.worker || state.activeOwner || state.startingOwner) {
+    return
+  }
+  await teardownSttWorker(state, state.worker, options)
+}
+
+export async function teardownSttWorker(
+  state: SttSessionState,
+  worker: Worker,
+  options: { ignoreTerminateErrors?: boolean } = { ignoreTerminateErrors: true }
+): Promise<void> {
+  clearSttIdleTeardownTimer(state)
+  if (state.stopInFlight?.worker === worker) {
+    await state.stopInFlight.promise
+  }
+  try {
+    worker.postMessage({ type: 'teardown' })
+  } catch {
+    // The worker may already have exited on a forced stop path.
+  }
+  cleanupActiveSttWorkerLifecycleListeners(state)
+  worker.removeAllListeners()
+  try {
+    await worker.terminate()
+  } catch (error) {
+    if (!options.ignoreTerminateErrors) {
+      throw error
+    }
+  }
+  if (state.worker === worker) {
+    clearSttWorkerState(state)
+  }
+}
+
+export function handleSttWorkerFailure(state: SttSessionState, error?: Error): void {
+  if (error) {
+    state.eventSink?.({ type: 'error', error: String(error) })
+  }
+  cleanupActiveSttWorkerLifecycleListeners(state)
+  clearSttWorkerState(state)
+}
+
+export function cleanupActiveSttWorkerLifecycleListeners(state: SttSessionState): void {
+  const cleanup = state.cleanupWorkerLifecycleListeners
+  state.cleanupWorkerLifecycleListeners = null
+  cleanup?.()
+}
+
+function clearSttWorkerState(state: SttSessionState): void {
+  state.worker = null
+  state.activeModelId = null
+  state.activeHotwordsFilePath = undefined
+  state.activeOwner = null
+  state.eventSink = null
+}
diff --git a/src/main/speech/stt-session-timeouts.ts b/src/main/speech/stt-session-timeouts.ts
new file mode 100644
index 00000000000..75dfddb845f
--- /dev/null
+++ b/src/main/speech/stt-session-timeouts.ts
@@ -0,0 +1,3 @@
+/** Single source for the dictation timeouts the start and stop paths share. */
+export const START_DICTATION_TIMEOUT_MS = 60_000
+export const IDLE_WORKER_TEARDOWN_MS = 60 * 60 * 1000
diff --git a/src/main/speech/stt-worker-startup.ts b/src/main/speech/stt-worker-startup.ts
new file mode 100644
index 00000000000..18653da1bd5
--- /dev/null
+++ b/src/main/speech/stt-worker-startup.ts
@@ -0,0 +1,97 @@
+import type { Worker } from 'node:worker_threads'
+import type { SttEvent } from './stt-service'
+
+export function waitForSttWorkerReady(worker: Worker, timeoutMs: number): Promise<void> {
+  const { promise, resolve, reject } = Promise.withResolvers<void>()
+  let settled = false
+  let startupTimeout: ReturnType<typeof setTimeout> | null = null
+  const cleanup = (): void => {
+    if (startupTimeout) {
+      clearTimeout(startupTimeout)
+      startupTimeout = null
+    }
+    worker.off('message', onReadyOrError)
+    worker.off('error', onStartupError)
+    worker.off('exit', onStartupExit)
+  }
+  const failStartup = (error: Error): void => {
+    if (settled) {
+      return
+    }
+    settled = true
+    cleanup()
+    reject(error)
+  }
+  const onReadyOrError = (message: { type: string; error?: string }): void => {
+    if (settled) {
+      return
+    }
+    if (message.type === 'ready') {
+      settled = true
+      cleanup()
+      resolve()
+    } else if (message.type === 'error') {
+      failStartup(new Error(message.error ?? 'Speech worker failed to initialize'))
+    }
+  }
+  const onStartupError = (error: Error): void => failStartup(error)
+  const onStartupExit = (code: number): void => {
+    failStartup(new Error(`Speech worker exited before ready: ${code}`))
+  }
+  worker.on('message', onReadyOrError)
+  worker.on('error', onStartupError)
+  worker.on('exit', onStartupExit)
+  startupTimeout = setTimeout(
+    () => failStartup(new Error('Speech worker timed out while starting.')),
+    timeoutMs
+  )
+  startupTimeout.unref?.()
+  return promise
+}
+
+export function attachSttWorkerLifecycle(args: {
+  worker: Worker
+  isCurrent: () => boolean
+  onMessage: (event: SttEvent) => void
+  onError: (error: Error) => void
+  onExit: () => void
+}): () => void {
+  const onWorkerMessage = (event: SttEvent): void => {
+    if (args.isCurrent()) {
+      args.onMessage(event)
+    }
+  }
+  const onWorkerError = (error: Error): void => {
+    if (args.isCurrent()) {
+      args.onError(error)
+    }
+  }
+  const onWorkerExit = (): void => {
+    if (args.isCurrent()) {
+      args.onExit()
+    }
+  }
+  args.worker.on('message', onWorkerMessage)
+  args.worker.on('error', onWorkerError)
+  args.worker.on('exit', onWorkerExit)
+  return () => {
+    args.worker.off('message', onWorkerMessage)
+    args.worker.off('error', onWorkerError)
+    args.worker.off('exit', onWorkerExit)
+  }
+}
+
+export function initializeSttWorker(
+  worker: Worker,
+  input: {
+    modelDir: string
+    modelType: string
+    streaming: boolean
+    sampleRate: number
+    files: readonly string[]
+    hotwordsFilePath?: string
+    modelingUnit?: string
+  }
+): void {
+  worker.postMessage({ type: 'init', ...input })
+}

From e39c22c1ceb81a6a767e388c228be6b5cf342ae7 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sat, 29 Aug 2026 20:04:35 -0700
Subject: [PATCH 21/31] Split terminal output scheduler pipeline (#17131)

* Split speech session lifecycle

* Split terminal output scheduler pipeline

* Fix F3-speech for #17123

* Fix F1-cycle for #17131
---
 config/max-lines-baseline.txt                 |    1 -
 .../pane-terminal-foreground-queue-state.ts   |  128 +++
 .../pane-terminal-output-drain.ts             |  128 +++
 .../pane-terminal-output-flusher.ts           |  130 +++
 .../pane-terminal-output-pipeline.ts          |  171 +++
 .../pane-terminal-output-queue-backlog.ts     |  104 ++
 .../pane-terminal-output-queue-chunks.ts      |    2 +-
 .../pane-terminal-output-queue-registry.ts    |  246 ++++
 .../pane-terminal-output-scheduler.ts         | 1009 +----------------
 .../pane-terminal-output-writer.ts            |  246 ++++
 10 files changed, 1197 insertions(+), 968 deletions(-)
 create mode 100644 src/renderer/src/lib/pane-manager/pane-terminal-foreground-queue-state.ts
 create mode 100644 src/renderer/src/lib/pane-manager/pane-terminal-output-drain.ts
 create mode 100644 src/renderer/src/lib/pane-manager/pane-terminal-output-flusher.ts
 create mode 100644 src/renderer/src/lib/pane-manager/pane-terminal-output-pipeline.ts
 create mode 100644 src/renderer/src/lib/pane-manager/pane-terminal-output-queue-backlog.ts
 create mode 100644 src/renderer/src/lib/pane-manager/pane-terminal-output-queue-registry.ts
 create mode 100644 src/renderer/src/lib/pane-manager/pane-terminal-output-writer.ts

diff --git a/config/max-lines-baseline.txt b/config/max-lines-baseline.txt
index 8d2496f1d69..2dc0e163346 100644
--- a/config/max-lines-baseline.txt
+++ b/config/max-lines-baseline.txt
@@ -62,7 +62,6 @@ inline src/renderer/src/components/terminal-pane/remote-runtime-pty-transport.ts
 inline src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts
 inline src/renderer/src/hooks/useAutomationDispatchEvents.ts
 inline src/renderer/src/hooks/useSettingsNavigationMetadata.ts
-inline src/renderer/src/lib/pane-manager/pane-terminal-output-scheduler.ts
 inline src/renderer/src/lib/pane-manager/pane-tree-ops.ts
 inline src/renderer/src/runtime/remote-runtime-terminal-multiplexer.ts
 inline src/renderer/src/runtime/runtime-file-client.ts
diff --git a/src/renderer/src/lib/pane-manager/pane-terminal-foreground-queue-state.ts b/src/renderer/src/lib/pane-manager/pane-terminal-foreground-queue-state.ts
new file mode 100644
index 00000000000..6d9d7524e27
--- /dev/null
+++ b/src/renderer/src/lib/pane-manager/pane-terminal-foreground-queue-state.ts
@@ -0,0 +1,128 @@
+import {
+  queuedByTerminal,
+  scheduleDrain,
+  type QueueEntry,
+  type TerminalOutputTarget,
+  type WriteTerminalOutputOptions
+} from './pane-terminal-output-queue-registry'
+
+const DEFAULT_FOREGROUND_COALESCE_DELAY_MS = 1000
+export const FOREGROUND_HOLD_SAFETY_DELAY_MS = 250
+export const LATENCY_SENSITIVE_FOREGROUND_COALESCE_DELAY_MS = 16
+export const LATENCY_SENSITIVE_FOREGROUND_HOLD_SAFETY_DELAY_MS = 32
+
+export function createQueueEntry(
+  terminal: TerminalOutputTarget,
+  options: WriteTerminalOutputOptions
+): QueueEntry {
+  return {
+    terminal,
+    chunks: [],
+    chunkIndex: 0,
+    queuedChars: 0,
+    onBackgroundBacklogDropped: options.onBackgroundBacklogDropped,
+    backgroundBacklogDropped: false,
+    highPriority: true,
+    foregroundHold: false,
+    foregroundHoldSafetyDelayMs: FOREGROUND_HOLD_SAFETY_DELAY_MS,
+    foregroundCoalesce: false,
+    foregroundCoalesceDelayMs: DEFAULT_FOREGROUND_COALESCE_DELAY_MS,
+    foregroundHoldSafetyTimer: null,
+    foregroundCoalesceTimer: null,
+    foregroundReleaseDeadlineAt: null,
+    foregroundReleaseDeadlineFixed: false
+  }
+}
+
+function getDrainNow(): number {
+  return typeof performance !== 'undefined' ? performance.now() : Date.now()
+}
+
+function armForegroundReleaseDeadline(
+  entry: QueueEntry,
+  delayMs: number,
+  mayExtend: boolean
+): number {
+  const now = getDrainNow()
+  const requested = now + delayMs
+  entry.foregroundReleaseDeadlineAt =
+    entry.foregroundReleaseDeadlineAt === null ||
+    (mayExtend && !entry.foregroundReleaseDeadlineFixed)
+      ? requested
+      : Math.min(entry.foregroundReleaseDeadlineAt, requested)
+  return Math.max(0, entry.foregroundReleaseDeadlineAt - now)
+}
+
+// Why: reopen the gate only once the entry is drainable again, so the next synchronized frame gets a full budget.
+function resetForegroundReleaseGate(entry: QueueEntry): void {
+  entry.foregroundReleaseDeadlineAt = null
+  entry.foregroundReleaseDeadlineFixed = false
+}
+
+export function clearForegroundRelease(entry: QueueEntry): void {
+  clearForegroundHoldSafety(entry)
+  clearForegroundCoalesce(entry)
+  resetForegroundReleaseGate(entry)
+}
+
+export function clearForegroundHoldSafety(entry: QueueEntry): void {
+  if (entry.foregroundHoldSafetyTimer === null) {
+    return
+  }
+  clearTimeout(entry.foregroundHoldSafetyTimer)
+  entry.foregroundHoldSafetyTimer = null
+  entry.foregroundHoldSafetyDelayMs = FOREGROUND_HOLD_SAFETY_DELAY_MS
+}
+
+export function clearForegroundCoalesce(entry: QueueEntry): void {
+  if (entry.foregroundCoalesceTimer !== null) {
+    clearTimeout(entry.foregroundCoalesceTimer)
+    entry.foregroundCoalesceTimer = null
+  }
+  entry.foregroundCoalesce = false
+  entry.foregroundCoalesceDelayMs = DEFAULT_FOREGROUND_COALESCE_DELAY_MS
+}
+
+export function scheduleForegroundHoldSafety(entry: QueueEntry): void {
+  clearForegroundHoldSafety(entry)
+  const delayMs = armForegroundReleaseDeadline(entry, entry.foregroundHoldSafetyDelayMs, true)
+  entry.foregroundHoldSafetyTimer = setTimeout(() => {
+    entry.foregroundHoldSafetyTimer = null
+    entry.foregroundHold = false
+    clearForegroundCoalesce(entry)
+    resetForegroundReleaseGate(entry)
+    if (queuedByTerminal.has(entry.terminal)) {
+      scheduleDrain(0)
+    }
+  }, delayMs)
+}
+
+export function scheduleForegroundCoalesceRelease(
+  entry: QueueEntry,
+  options?: { rescheduleEarlier?: boolean }
+): void {
+  if (entry.foregroundCoalesceTimer !== null) {
+    if (options?.rescheduleEarlier !== true) {
+      entry.foregroundCoalesce = true
+      return
+    }
+    clearTimeout(entry.foregroundCoalesceTimer)
+    entry.foregroundCoalesceTimer = null
+  }
+  entry.foregroundCoalesce = true
+  // Why fixed from here: a later hold chunk must clamp to this deadline instead of restarting the pair's mutual re-arm (#8754).
+  entry.foregroundReleaseDeadlineFixed = true
+  const delayMs = armForegroundReleaseDeadline(entry, entry.foregroundCoalesceDelayMs, false)
+  entry.foregroundCoalesceTimer = setTimeout(() => {
+    entry.foregroundCoalesceTimer = null
+    entry.foregroundCoalesce = false
+    resetForegroundReleaseGate(entry)
+    if (queuedByTerminal.has(entry.terminal)) {
+      scheduleDrain(0)
+    }
+  }, delayMs)
+}
+
+export function isEntryDrainable(entry: QueueEntry): boolean {
+  return !entry.foregroundHold && !entry.foregroundCoalesce
+}
diff --git a/src/renderer/src/lib/pane-manager/pane-terminal-output-drain.ts b/src/renderer/src/lib/pane-manager/pane-terminal-output-drain.ts
new file mode 100644
index 00000000000..4753eb38feb
--- /dev/null
+++ b/src/renderer/src/lib/pane-manager/pane-terminal-output-drain.ts
@@ -0,0 +1,128 @@
+import {
+  recordTerminalOutputQueueDebugPressure as recordQueueDebugPressure,
+  terminalOutputSchedulerDebugEnabled as debugEnabled,
+  terminalOutputSchedulerDebugState as debugState
+} from './pane-terminal-output-scheduler-debug'
+import { clearForegroundRelease, isEntryDrainable } from './pane-terminal-foreground-queue-state'
+import { hasHighPriorityBacklog, hasQueuedChunks } from './pane-terminal-output-queue-backlog'
+import {
+  BACKGROUND_DRAIN_INTERVAL_MS,
+  DRAIN_TIME_BUDGET_MS,
+  HIGH_PRIORITY_DRAIN_INTERVAL_MS,
+  HIGH_PRIORITY_MAX_WRITES_PER_DRAIN,
+  LARGE_BACKLOG_CHARS,
+  MAX_WRITES_PER_DRAIN,
+  isMessageChannelDrainEnabled,
+  markTerminalOutputDrainStarted,
+  queuedByTerminal,
+  scheduleDrain,
+  setTerminalOutputDrainRunner,
+  type QueueEntry
+} from './pane-terminal-output-queue-registry'
+
+import { writeQueuedChunk } from './pane-terminal-output-pipeline'
+
+function hasDrainableBacklog(): boolean {
+  for (const entry of queuedByTerminal.values()) {
+    if (isEntryDrainable(entry)) {
+      return true
+    }
+  }
+  return false
+}
+
+// Why no per-write scroll enforcement: xterm's BufferService.isUserScrolling owns live follow/pin; app-side enforcement is limited to structural ops xterm can't identify, like replay.
+
+function takeNextDrainableEntry(): QueueEntry | null {
+  let largeBacklogEntry: QueueEntry | null = null
+  for (const entry of queuedByTerminal.values()) {
+    if (!isEntryDrainable(entry)) {
+      continue
+    }
+    // Why: active/foreground output should be chosen first, not left in insertion order behind older background terminals.
+    if (entry.highPriority) {
+      queuedByTerminal.delete(entry.terminal)
+      return entry
+    }
+    if (!largeBacklogEntry && entry.queuedChars > LARGE_BACKLOG_CHARS) {
+      largeBacklogEntry = entry
+    }
+  }
+  if (largeBacklogEntry) {
+    queuedByTerminal.delete(largeBacklogEntry.terminal)
+    return largeBacklogEntry
+  }
+  for (const entry of queuedByTerminal.values()) {
+    if (!isEntryDrainable(entry)) {
+      continue
+    }
+    queuedByTerminal.delete(entry.terminal)
+    return entry
+  }
+  return null
+}
+
+// Why: re-arm a zero-delay drain once xterm confirms the previous high-priority batch parsed; the fixed 4/16ms cadence otherwise drips far below xterm's ~100 MB/s parse. Only visible panes are pacer-clocked; background keeps the fixed cadence to protect the focused terminal.
+
+function getDrainNow(): number {
+  if (typeof performance !== 'undefined') {
+    return performance.now()
+  }
+  return Date.now()
+}
+
+export function drainQueuedOutputImpl(): void {
+  markTerminalOutputDrainStarted()
+  let writes = 0
+  const startedAt = getDrainNow()
+  const highPriority = hasHighPriorityBacklog()
+  const maxWrites = highPriority ? HIGH_PRIORITY_MAX_WRITES_PER_DRAIN : MAX_WRITES_PER_DRAIN
+
+  while (queuedByTerminal.size > 0 && writes < maxWrites) {
+    const entry = takeNextDrainableEntry()
+    if (!entry) {
+      break
+    }
+
+    const writeKind = writeQueuedChunk(entry)
+    if (writeKind) {
+      writes++
+      if (debugEnabled) {
+        if (writeKind === 'foreground') {
+          debugState.deferredForegroundWriteCount++
+        } else {
+          debugState.backgroundWriteCount++
+        }
+      }
+    }
+    if (hasQueuedChunks(entry)) {
+      queuedByTerminal.set(entry.terminal, entry)
+    } else {
+      entry.highPriority = false
+      clearForegroundRelease(entry)
+    }
+    // Why: xterm parsing and DOM work share the renderer thread with input; keep draining cooperative so WSL/agent output can't pin the UI.
+    if (writes > 0 && getDrainNow() - startedAt >= DRAIN_TIME_BUDGET_MS) {
+      break
+    }
+  }
+
+  if (debugEnabled && writes > 0) {
+    debugState.drainWrites.push(writes)
+    debugState.drainHighPriority.push(highPriority)
+  }
+  recordQueueDebugPressure()
+  if (queuedByTerminal.size > 0 && hasDrainableBacklog()) {
+    // Why 0 on the channel path: a posted message already yields (input/paint serviced between macrotasks), so the 4ms interval only deepened the queue; timer path keeps it for fake-timer tests.
+    scheduleDrain(
+      hasHighPriorityBacklog()
+        ? isMessageChannelDrainEnabled()
+          ? 0
+          : HIGH_PRIORITY_DRAIN_INTERVAL_MS
+        : BACKGROUND_DRAIN_INTERVAL_MS
+    )
+  }
+}
+
+// Why at module scope: the registry's scheduleDrain must never fire before a runner exists, so registration happens as this module is evaluated rather than on first use.
+setTerminalOutputDrainRunner(drainQueuedOutputImpl)
diff --git a/src/renderer/src/lib/pane-manager/pane-terminal-output-flusher.ts b/src/renderer/src/lib/pane-manager/pane-terminal-output-flusher.ts
new file mode 100644
index 00000000000..cf6727bb7ff
--- /dev/null
+++ b/src/renderer/src/lib/pane-manager/pane-terminal-output-flusher.ts
@@ -0,0 +1,130 @@
+import { writeForegroundTerminalChunk } from './pane-terminal-foreground-render-settle'
+import { registerTerminalOutputAckCredits } from './pane-terminal-output-ack-credit'
+import {
+  armTerminalWriteStallWatch,
+  cancelTerminalWriteStallWatch,
+  isTerminalWritePipelineCertifiedDead
+} from './terminal-write-pipeline-health'
+import { removeTransientCursorShowSequences } from './pane-terminal-cursor-sequencing'
+import { takeQueuedChunk } from './pane-terminal-output-queue-chunks'
+import {
+  exposeTerminalOutputSchedulerDebugApi as exposeDebugApi,
+  recordTerminalOutputQueueDebugPressure as recordQueueDebugPressure,
+  terminalOutputSchedulerDebugEnabled as debugEnabled,
+  terminalOutputSchedulerDebugState as debugState
+} from './pane-terminal-output-scheduler-debug'
+import {
+  composeParsedCallback,
+  composeWriteFailureCallback,
+  writeBackgroundTerminalChunk
+} from './pane-terminal-output-pipeline'
+import { discardDetachedQueueEntry, hasQueuedChunks } from './pane-terminal-output-queue-backlog'
+import { clearForegroundRelease, isEntryDrainable } from './pane-terminal-foreground-queue-state'
+import {
+  BACKGROUND_CHUNK_CHARS,
+  discardTerminalOutput,
+  fireQueuedAckCredits,
+  queuedByTerminal,
+  requestRegisteredTerminalBacklogRecovery,
+  scheduleDrain,
+  type TerminalOutputTarget
+} from './pane-terminal-output-queue-registry'
+
+export function flushTerminalOutputImpl(
+  terminal: TerminalOutputTarget,
+  options?: { maxChars?: number }
+): void {
+  exposeDebugApi()
+  const entry = queuedByTerminal.get(terminal)
+  if (!entry) {
+    return
+  }
+  queuedByTerminal.delete(terminal)
+  if (isTerminalWritePipelineCertifiedDead(terminal)) {
+    discardDetachedQueueEntry(entry)
+    discardTerminalOutput(terminal)
+    return
+  }
+  if (!isEntryDrainable(entry)) {
+    queuedByTerminal.set(terminal, entry)
+    return
+  }
+  if (entry.backgroundBacklogDropped && requestRegisteredTerminalBacklogRecovery(terminal)) {
+    fireQueuedAckCredits(entry)
+    entry.chunks.length = 0
+    entry.chunkIndex = 0
+    entry.queuedChars = 0
+    entry.highPriority = false
+    clearForegroundRelease(entry)
+    recordQueueDebugPressure()
+    return
+  }
+
+  let flushedChars = 0
+  let queuedWrite = takeQueuedChunk(entry, BACKGROUND_CHUNK_CHARS)
+  while (queuedWrite) {
+    flushedChars += queuedWrite.data.length
+    if (debugEnabled) {
+      debugState.flushWriteCount++
+    }
+    const ackCreditsParsed = registerTerminalOutputAckCredits(terminal, queuedWrite.ackCredits)
+    armTerminalWriteStallWatch(terminal, {
+      onCertifiedDead: () => discardTerminalOutput(terminal)
+    })
+    try {
+      queuedWrite.beforeWrite?.(queuedWrite.data)
+      const writeAccepted = queuedWrite.foreground
+        ? writeForegroundTerminalChunk(
+            terminal,
+            queuedWrite.stripTransientCursorShows
+              ? removeTransientCursorShowSequences(queuedWrite.data)
+              : queuedWrite.data,
+            {
+              forceViewportRefresh: queuedWrite.forceForegroundRefresh,
+              followupViewportRefresh: queuedWrite.followupForegroundRefresh,
+              shouldRefreshViewportSynchronously: queuedWrite.shouldRefreshForegroundSynchronously,
+              onParsed: composeParsedCallback(
+                terminal,
+                queuedWrite.onParsed,
+                ackCreditsParsed,
+                undefined
+              ),
+              onWriteFailure: composeWriteFailureCallback(terminal, ackCreditsParsed)
+            }
+          )
+        : writeBackgroundTerminalChunk(
+            terminal,
+            queuedWrite.data,
+            composeParsedCallback(terminal, queuedWrite.onParsed, ackCreditsParsed, undefined),
+            composeWriteFailureCallback(terminal, ackCreditsParsed)
+          )
+      if (!writeAccepted) {
+        fireQueuedAckCredits(entry)
+        clearForegroundRelease(entry)
+        recordQueueDebugPressure()
+        return
+      }
+    } catch {
+      // Why: pre-write hooks/setup failed before xterm owned these bytes; cancel the watch, but consumed + abandoned chunks still credit delivery.
+      cancelTerminalWriteStallWatch(terminal)
+      ackCreditsParsed?.()
+      fireQueuedAckCredits(entry)
+      clearForegroundRelease(entry)
+      recordQueueDebugPressure()
+      return
+    }
+    if (options?.maxChars !== undefined && flushedChars >= options.maxChars) {
+      break
+    }
+    queuedWrite = takeQueuedChunk(entry, BACKGROUND_CHUNK_CHARS)
+  }
+  if (hasQueuedChunks(entry)) {
+    entry.highPriority = true
+    queuedByTerminal.set(terminal, entry)
+    scheduleDrain(0)
+  } else {
+    entry.highPriority = false
+    clearForegroundRelease(entry)
+  }
+  recordQueueDebugPressure()
+}
diff --git a/src/renderer/src/lib/pane-manager/pane-terminal-output-pipeline.ts b/src/renderer/src/lib/pane-manager/pane-terminal-output-pipeline.ts
new file mode 100644
index 00000000000..06ba58568d2
--- /dev/null
+++ b/src/renderer/src/lib/pane-manager/pane-terminal-output-pipeline.ts
@@ -0,0 +1,171 @@
+import { writeForegroundTerminalChunk } from './pane-terminal-foreground-render-settle'
+import { runGuardedWriteCompletionStep } from './xterm-write-callback-guard'
+import { registerTerminalOutputAckCredits } from './pane-terminal-output-ack-credit'
+import {
+  armTerminalWriteStallWatch,
+  cancelTerminalWriteStallWatch,
+  failTerminalWriteStallWatch,
+  isTerminalWritePipelineCertifiedDead,
+  settleTerminalWriteStallWatch
+} from './terminal-write-pipeline-health'
+import { removeTransientCursorShowSequences } from './pane-terminal-cursor-sequencing'
+import { takeQueuedChunk } from './pane-terminal-output-queue-chunks'
+import { recordTerminalOutputQueueDebugPressure as recordQueueDebugPressure } from './pane-terminal-output-scheduler-debug'
+import { clearForegroundRelease } from './pane-terminal-foreground-queue-state'
+import {
+  BACKGROUND_CHUNK_CHARS,
+  discardTerminalOutput,
+  fireQueuedAckCredits,
+  queuedByTerminal,
+  scheduleDrain,
+  type QueueEntry,
+  type TerminalOutputParsedCallback,
+  type TerminalOutputTarget
+} from './pane-terminal-output-queue-registry'
+import {
+  discardDetachedQueueEntry,
+  hasHighPriorityBacklog
+} from './pane-terminal-output-queue-backlog'
+
+// Why no per-write scroll enforcement: xterm's BufferService.isUserScrolling owns live follow/pin; app-side enforcement is limited to structural ops xterm can't identify, like replay.
+export function writeBackgroundTerminalChunk(
+  terminal: TerminalOutputTarget,
+  data: string,
+  onParsed?: TerminalOutputParsedCallback,
+  onWriteFailure?: () => void
+): boolean {
+  // Why guarded: these callbacks run inside xterm's WriteBuffer loop, where an escaping throw permanently wedges the terminal (see xterm-write-callback-guard.ts).
+  const runOnParsed = onParsed
+    ? (): void => runGuardedWriteCompletionStep('background-on-parsed', onParsed)
+    : undefined
+  const runOnWriteFailure = onWriteFailure
+    ? (): void => runGuardedWriteCompletionStep('background-on-write-failure', onWriteFailure)
+    : undefined
+  try {
+    if (!runOnParsed || terminal.write.length < 2) {
+      terminal.write(data)
+      runOnParsed?.()
+      return true
+    }
+    terminal.write(data, runOnParsed)
+    return true
+  } catch {
+    runOnWriteFailure?.()
+    return false
+  }
+}
+
+// Why: re-arm a zero-delay drain once xterm confirms the previous high-priority batch parsed; the fixed 4/16ms cadence otherwise drips far below xterm's ~100 MB/s parse. Only visible panes are pacer-clocked; background keeps the fixed cadence to protect the focused terminal.
+function makeParseClockPacer(): () => void {
+  return () => {
+    try {
+      if (queuedByTerminal.size > 0 && hasHighPriorityBacklog()) {
+        scheduleDrain(0)
+      }
+    } catch {
+      // Why: runs inside xterm's write-callback chain; a throw here would wedge the terminal (see xterm-write-callback-guard.ts).
+    }
+  }
+}
+
+export function composeParsedCallback(
+  terminal: TerminalOutputTarget,
+  onParsed: TerminalOutputParsedCallback | undefined,
+  ackCreditsParsed: (() => void) | undefined,
+  pacer: (() => void) | undefined
+): TerminalOutputParsedCallback {
+  // Why always non-undefined: the callback doubles as the pipeline-health settle signal — with none, the stall watch could never settle, forcing a probe round-trip per healthy idle pane.
+  return () => {
+    try {
+      onParsed?.()
+    } finally {
+      ackCreditsParsed?.()
+      pacer?.()
+      settleTerminalWriteStallWatch(terminal)
+    }
+  }
+}
+
+export function composeWriteFailureCallback(
+  terminal: TerminalOutputTarget,
+  ackCreditsParsed: (() => void) | undefined
+): () => void {
+  return () => {
+    try {
+      // A rejected write still consumed the main-owned delivery window.
+      ackCreditsParsed?.()
+    } finally {
+      // Why: a synchronous rejection proves undeliverability but nothing about parse progress; recover without extending replay guards.
+      failTerminalWriteStallWatch(terminal)
+    }
+  }
+}
+
+export function writeQueuedChunk(entry: QueueEntry): 'foreground' | 'background' | null {
+  if (isTerminalWritePipelineCertifiedDead(entry.terminal)) {
+    // The drain owns this detached entry, so map-based discard cannot see it.
+    discardDetachedQueueEntry(entry)
+    discardTerminalOutput(entry.terminal)
+    return null
+  }
+  const queuedWrite = takeQueuedChunk(entry, BACKGROUND_CHUNK_CHARS)
+  if (!queuedWrite) {
+    return null
+  }
+  const pacer = entry.highPriority ? makeParseClockPacer() : undefined
+  const ackCreditsParsed = registerTerminalOutputAckCredits(entry.terminal, queuedWrite.ackCredits)
+  // Why armed BEFORE the write: a wedged WriteBuffer (issue #2836) or disposed xterm (6.1.0-beta.287) never runs the parsed callback, so the watch must be live first to catch it.
+  armTerminalWriteStallWatch(entry.terminal, {
+    onCertifiedDead: () => discardTerminalOutput(entry.terminal)
+  })
+  try {
+    queuedWrite.beforeWrite?.(queuedWrite.data)
+    const writeAccepted = queuedWrite.foreground
+      ? writeForegroundTerminalChunk(
+          entry.terminal,
+          queuedWrite.stripTransientCursorShows
+            ? removeTransientCursorShowSequences(queuedWrite.data)
+            : queuedWrite.data,
+          {
+            forceViewportRefresh: queuedWrite.forceForegroundRefresh,
+            followupViewportRefresh: queuedWrite.followupForegroundRefresh,
+            shouldRefreshViewportSynchronously: queuedWrite.shouldRefreshForegroundSynchronously,
+            onParsed: composeParsedCallback(
+              entry.terminal,
+              queuedWrite.onParsed,
+              ackCreditsParsed,
+              pacer
+            ),
+            onWriteFailure: composeWriteFailureCallback(entry.terminal, ackCreditsParsed)
+          }
+        )
+      : writeBackgroundTerminalChunk(
+          entry.terminal,
+          queuedWrite.data,
+          composeParsedCallback(entry.terminal, queuedWrite.onParsed, ackCreditsParsed, pacer),
+          composeWriteFailureCallback(entry.terminal, ackCreditsParsed)
+        )
+    if (!writeAccepted) {
+      // Why: the failure callback credited the submitted chunk; credit and abandon the detached tail so the drain can't retry a certified-dead xterm.
+      fireQueuedAckCredits(entry)
+      entry.chunks.length = 0
+      entry.chunkIndex = 0
+      entry.queuedChars = 0
+      clearForegroundRelease(entry)
+      recordQueueDebugPressure()
+      return null
+    }
+  } catch {
+    // Why: beforeWrite or write setup can fail before xterm owns the bytes; cancel the armed watch without claiming parser failure.
+    cancelTerminalWriteStallWatch(entry.terminal)
+    ackCreditsParsed?.()
+    fireQueuedAckCredits(entry)
+    entry.chunks.length = 0
+    entry.chunkIndex = 0
+    entry.queuedChars = 0
+    clearForegroundRelease(entry)
+    recordQueueDebugPressure()
+    return null
+  }
+  return queuedWrite.foreground ? 'foreground' : 'background'
+}
diff --git a/src/renderer/src/lib/pane-manager/pane-terminal-output-queue-backlog.ts b/src/renderer/src/lib/pane-manager/pane-terminal-output-queue-backlog.ts
new file mode 100644
index 00000000000..4bc1bcfb970
--- /dev/null
+++ b/src/renderer/src/lib/pane-manager/pane-terminal-output-queue-backlog.ts
@@ -0,0 +1,104 @@
+import { recordRendererCrashBreadcrumb } from '@/lib/crash-breadcrumb-recorder'
+import {
+  recordTerminalOutputQueueDebugPressure as recordQueueDebugPressure,
+  terminalOutputSchedulerDebugEnabled as debugEnabled,
+  terminalOutputSchedulerDebugState as debugState
+} from './pane-terminal-output-scheduler-debug'
+import {
+  clearForegroundHoldSafety,
+  clearForegroundRelease,
+  isEntryDrainable
+} from './pane-terminal-foreground-queue-state'
+import {
+  ALWAYS_REFRESH_FOREGROUND_SYNCHRONOUSLY,
+  BACKGROUND_BACKLOG_WARNING,
+  FOREGROUND_BACKLOG_WARNING,
+  LARGE_BACKLOG_CHARS,
+  MAX_BACKGROUND_QUEUE_CHUNKS,
+  fireQueuedAckCredits,
+  getTerminalOutputMaxQueueChars,
+  queuedByTerminal,
+  type QueueEntry,
+  type TerminalOutputBeforeWrite
+} from './pane-terminal-output-queue-registry'
+
+export function discardDetachedQueueEntry(entry: QueueEntry): void {
+  fireQueuedAckCredits(entry)
+  entry.chunks.length = 0
+  entry.chunkIndex = 0
+  entry.queuedChars = 0
+  entry.highPriority = false
+  clearForegroundRelease(entry)
+}
+
+export function queueCapExceeded(entry: QueueEntry): boolean {
+  return (
+    entry.queuedChars > getTerminalOutputMaxQueueChars() ||
+    entry.chunks.length - entry.chunkIndex > MAX_BACKGROUND_QUEUE_CHUNKS
+  )
+}
+
+export function replaceBacklogWithWarning(
+  entry: QueueEntry,
+  warning: string = BACKGROUND_BACKLOG_WARNING
+): void {
+  const shouldNotify = !entry.backgroundBacklogDropped
+  if (shouldNotify) {
+    // Why: field visibility for cap tuning — drop frequency and size decide whether the cap is too small (issue #2836 / #7017).
+    recordRendererCrashBreadcrumb('terminal_output_backlog_dropped', {
+      foreground: warning === FOREGROUND_BACKLOG_WARNING,
+      droppedChars: entry.queuedChars,
+      capChars: getTerminalOutputMaxQueueChars()
+    })
+  }
+  let beforeWrite: TerminalOutputBeforeWrite | undefined
+  for (let index = entry.chunks.length - 1; index >= entry.chunkIndex; index--) {
+    if (entry.chunks[index]?.beforeWrite) {
+      beforeWrite = entry.chunks[index].beforeWrite
+      break
+    }
+  }
+  clearForegroundHoldSafety(entry)
+  fireQueuedAckCredits(entry)
+  entry.chunks = [
+    {
+      data: warning,
+      retainedChars: warning.length,
+      foreground: false,
+      forceForegroundRefresh: false,
+      followupForegroundRefresh: false,
+      shouldRefreshForegroundSynchronously: ALWAYS_REFRESH_FOREGROUND_SYNCHRONOUSLY,
+      stripTransientCursorShows: false,
+      beforeWrite
+    }
+  ]
+  entry.chunkIndex = 0
+  entry.queuedChars = warning.length
+  entry.backgroundBacklogDropped = true
+  entry.highPriority = true
+  entry.foregroundHold = false
+  if (debugEnabled && shouldNotify) {
+    debugState.droppedBacklogCount++
+  }
+  clearForegroundRelease(entry)
+  recordQueueDebugPressure()
+  if (shouldNotify) {
+    entry.onBackgroundBacklogDropped?.()
+  }
+}
+
+export function hasQueuedChunks(entry: QueueEntry): boolean {
+  return entry.chunkIndex < entry.chunks.length
+}
+
+export function hasHighPriorityBacklog(): boolean {
+  for (const entry of queuedByTerminal.values()) {
+    if (
+      isEntryDrainable(entry) &&
+      (entry.highPriority || entry.queuedChars > LARGE_BACKLOG_CHARS)
+    ) {
+      return true
+    }
+  }
+  return false
+}
diff --git a/src/renderer/src/lib/pane-manager/pane-terminal-output-queue-chunks.ts b/src/renderer/src/lib/pane-manager/pane-terminal-output-queue-chunks.ts
index 0142c3528be..bdf7251df84 100644
--- a/src/renderer/src/lib/pane-manager/pane-terminal-output-queue-chunks.ts
+++ b/src/renderer/src/lib/pane-manager/pane-terminal-output-queue-chunks.ts
@@ -4,7 +4,7 @@ import type {
   QueuedWrite,
   TerminalOutputBeforeWrite,
   TerminalOutputParsedCallback
-} from './pane-terminal-output-scheduler'
+} from './pane-terminal-output-queue-registry'
 import { recordTerminalOutputQueueDebugPressure as recordQueueDebugPressure } from './pane-terminal-output-scheduler-debug'
 
 type ForegroundRefreshSyncResolver = () => boolean
diff --git a/src/renderer/src/lib/pane-manager/pane-terminal-output-queue-registry.ts b/src/renderer/src/lib/pane-manager/pane-terminal-output-queue-registry.ts
new file mode 100644
index 00000000000..a7e87f380de
--- /dev/null
+++ b/src/renderer/src/lib/pane-manager/pane-terminal-output-queue-registry.ts
@@ -0,0 +1,246 @@
+import {
+  discardForegroundRenderSettle,
+  type ForegroundTerminalOutputTarget
+} from './pane-terminal-foreground-render-settle'
+import { discardInFlightTerminalOutputAckCredits } from './pane-terminal-output-ack-credit'
+import { cancelTerminalWriteStallWatch } from './terminal-write-pipeline-health'
+import {
+  TERMINAL_OUTPUT_BACKLOG_MIN_CAP_CHARS,
+  terminalOutputBacklogCapChars
+} from '../../../../shared/terminal-scrollback-policy'
+import {
+  exposeTerminalOutputSchedulerDebugApi as exposeDebugApi,
+  recordTerminalOutputQueueDebugPressure as recordQueueDebugPressure,
+  setTerminalOutputDebugQueueReader,
+  terminalOutputSchedulerDebugEnabled as debugEnabled,
+  terminalOutputSchedulerDebugState as debugState
+} from './pane-terminal-output-scheduler-debug'
+
+export type TerminalOutputTarget = ForegroundTerminalOutputTarget
+
+export type TerminalOutputBeforeWrite = (data: string) => void
+type TerminalBacklogRecoveryRequest = () => boolean
+export type TerminalOutputParsedCallback = () => void
+type ForegroundRefreshSyncResolver = () => boolean
+
+export type WriteTerminalOutputOptions = {
+  foreground: boolean
+  beforeWrite?: TerminalOutputBeforeWrite
+  onParsed?: TerminalOutputParsedCallback
+  /** Parse-deferred delivery ACK (terminal-pty-ack-gate). MUST be invoked when the chunk is parsed OR discarded by any drop path; fire-once, so double invocation is safe but omission permanently shrinks main's in-flight window. */
+  ackCredit?: () => void
+  onBackgroundBacklogDropped?: () => void
+  latencySensitive?: boolean
+  forceForegroundRefresh?: boolean
+  followupForegroundRefresh?: boolean
+  shouldRefreshForegroundSynchronously?: ForegroundRefreshSyncResolver
+  stripTransientCursorShows?: boolean
+  coalesceForeground?: boolean
+  holdForeground?: boolean
+}
+
+type QueueChunk = {
+  data: string
+  // Tracks the backing data still reachable through this queue slot.
+  retainedChars: number
+  foreground: boolean
+  forceForegroundRefresh: boolean
+  followupForegroundRefresh: boolean
+  shouldRefreshForegroundSynchronously: ForegroundRefreshSyncResolver
+  stripTransientCursorShows: boolean
+  beforeWrite?: TerminalOutputBeforeWrite
+  onParsed?: TerminalOutputParsedCallback
+  ackCredit?: () => void
+}
+
+export type QueuedWrite = {
+  data: string
+  foreground: boolean
+  forceForegroundRefresh: boolean
+  followupForegroundRefresh: boolean
+  shouldRefreshForegroundSynchronously: ForegroundRefreshSyncResolver
+  stripTransientCursorShows: boolean
+  beforeWrite?: TerminalOutputBeforeWrite
+  onParsed?: TerminalOutputParsedCallback
+  ackCredits: (() => void)[]
+}
+
+export type QueueEntry = {
+  terminal: TerminalOutputTarget
+  chunks: QueueChunk[]
+  chunkIndex: number
+  queuedChars: number
+  onBackgroundBacklogDropped?: () => void
+  backgroundBacklogDropped: boolean
+  highPriority: boolean
+  foregroundHold: boolean
+  foregroundHoldSafetyDelayMs: number
+  foregroundCoalesce: boolean
+  foregroundCoalesceDelayMs: number
+  foregroundHoldSafetyTimer: ReturnType<typeof setTimeout> | null
+  foregroundCoalesceTimer: ReturnType<typeof setTimeout> | null
+  // Why: hold and coalesce cancel each other's fallback timer, so an alternating DEC 2026 stream could re-arm both forever and freeze a visible pane (#8754). This caps one non-drainable episode.
+  foregroundReleaseDeadlineAt: number | null
+  // Why: an open frame's own hold chunks may still push the deadline out, but once coalesce has taken the entry over the deadline stops moving so the two mechanisms can't re-arm each other.
+  foregroundReleaseDeadlineFixed: boolean
+}
+
+export const BACKGROUND_FLUSH_DELAY_MS = 50
+export const BACKGROUND_DRAIN_INTERVAL_MS = 16
+export const HIGH_PRIORITY_DRAIN_INTERVAL_MS = 4
+export const BACKGROUND_CHUNK_CHARS = 16 * 1024
+export const MAX_WRITES_PER_DRAIN = 2
+// Why 8: per-tick volume (8 x 16KB = 128KB ≈ 1.3ms parse) sets the sustained ceiling (~30MB/s) within DRAIN_TIME_BUDGET_MS; at 2 it was only 8MB/s against a ~100MB/s parser (see throughput bench).
+export const HIGH_PRIORITY_MAX_WRITES_PER_DRAIN = 8
+export const DRAIN_TIME_BUDGET_MS = 8
+export const LARGE_BACKLOG_CHARS = 512 * 1024
+// Why mutable: the cap scales with the user's scrollback setting (terminalOutputBacklogCapChars), configured when settings apply; the chunk-count cap stays fixed.
+let maxQueueChars = TERMINAL_OUTPUT_BACKLOG_MIN_CAP_CHARS
+export const MAX_BACKGROUND_QUEUE_CHUNKS = 4096
+
+export function configureTerminalOutputBacklogCap(scrollbackRows: unknown): void {
+  maxQueueChars = terminalOutputBacklogCapChars(scrollbackRows)
+}
+
+export function getTerminalOutputMaxQueueChars(): number {
+  return maxQueueChars
+}
+// Why: leading CAN aborts any partial escape sequence before the style reset so the backlog warning renders cleanly.
+export const BACKGROUND_BACKLOG_WARNING =
+  '\x18\x1b[0m\r\n[Orca skipped hidden terminal output because the backlog grew too large.]\r\n'
+// Why a separate foreground message: a visible pane hitting the cap means the drain couldn't keep up with a flood (starved renderer), not merely output produced while hidden.
+export const FOREGROUND_BACKLOG_WARNING =
+  '\x18\x1b[0m\r\n[Orca skipped a burst of terminal output because the backlog grew too large.]\r\n'
+export const ALWAYS_REFRESH_FOREGROUND_SYNCHRONOUSLY = (): boolean => true
+
+export const queuedByTerminal = new Map<TerminalOutputTarget, QueueEntry>()
+setTerminalOutputDebugQueueReader(() => queuedByTerminal.values())
+const backlogRecoveryByTerminal = new WeakMap<
+  TerminalOutputTarget,
+  TerminalBacklogRecoveryRequest
+>()
+let drainTimer: ReturnType<typeof setTimeout> | null = null
+let drainTimerDelayMs: number | null = null
+// Why a MessageChannel for zero-delay drains: Chromium clamps nested setTimeout(0) to ~4ms; a posted macrotask isn't clamped yet still yields to input/paint. Cancellation is by generation.
+let drainImmediatePending = false
+let drainImmediateGeneration = 0
+let useMessageChannelDrain = typeof MessageChannel !== 'undefined' && !isVitestEnv()
+let drainChannel: MessageChannel | null = null
+// Why indirect: the drain loop lives downstream of this module, so it registers itself here rather than being imported back into the queue state it operates on.
+let runDrain: (() => void) | null = null
+
+export function setTerminalOutputDrainRunner(runner: () => void): void {
+  runDrain = runner
+}
+
+function runDrainTick(): void {
+  runDrain?.()
+}
+
+function isVitestEnv(): boolean {
+  // Why: vitest fake timers can't advance MessageChannel macrotasks; the timer path keeps the suites' virtual clock authoritative.
+  return typeof process !== 'undefined' && process.env?.VITEST === 'true'
+}
+
+function getDrainChannel(): MessageChannel {
+  if (drainChannel === null) {
+    drainChannel = new MessageChannel()
+    drainChannel.port1.onmessage = (event: MessageEvent) => {
+      if (event.data !== drainImmediateGeneration || !drainImmediatePending) {
+        return
+      }
+      drainImmediatePending = false
+      runDrainTick()
+    }
+  }
+  return drainChannel
+}
+
+function cancelImmediateDrain(): void {
+  drainImmediateGeneration++
+  drainImmediatePending = false
+}
+
+export function setUseMessageChannelDrainForTesting(value: boolean | null): void {
+  cancelImmediateDrain()
+  useMessageChannelDrain = value ?? (typeof MessageChannel !== 'undefined' && !isVitestEnv())
+}
+
+export function isMessageChannelDrainEnabled(): boolean {
+  return useMessageChannelDrain
+}
+
+export function markTerminalOutputDrainStarted(): void {
+  drainTimer = null
+  drainTimerDelayMs = null
+}
+
+export function scheduleDrain(delayMs: number): void {
+  if (drainImmediatePending) {
+    // An immediate drain is already armed — nothing can beat zero delay.
+    return
+  }
+  if (drainTimer !== null) {
+    if (drainTimerDelayMs !== null && drainTimerDelayMs <= delayMs) {
+      return
+    }
+    clearTimeout(drainTimer)
+    drainTimer = null
+    drainTimerDelayMs = null
+  }
+  if (queuedByTerminal.size === 0) {
+    return
+  }
+  if (debugEnabled) {
+    debugState.scheduledDrainCount++
+  }
+  if (delayMs === 0 && useMessageChannelDrain) {
+    drainImmediatePending = true
+    getDrainChannel().port2.postMessage(drainImmediateGeneration)
+    return
+  }
+  drainTimer = setTimeout(runDrainTick, delayMs)
+  drainTimerDelayMs = delayMs
+}
+
+// Why: every discard path MUST fire these before clearing/replacing the queue — a dropped chunk still counts as consumed, or main's in-flight window shrinks permanently and the PTY wedges.
+export function fireQueuedAckCredits(entry: QueueEntry): void {
+  for (let index = entry.chunkIndex; index < entry.chunks.length; index += 1) {
+    entry.chunks[index].ackCredit?.()
+  }
+}
+
+export function requestRegisteredTerminalBacklogRecovery(terminal: TerminalOutputTarget): boolean {
+  const requestRecovery = backlogRecoveryByTerminal.get(terminal)
+  if (!requestRecovery) {
+    return false
+  }
+  return requestRecovery()
+}
+
+export function registerTerminalBacklogRecovery(
+  terminal: TerminalOutputTarget,
+  requestRecovery: TerminalBacklogRecoveryRequest
+): () => void {
+  backlogRecoveryByTerminal.set(terminal, requestRecovery)
+  return () => {
+    if (backlogRecoveryByTerminal.get(terminal) === requestRecovery) {
+      backlogRecoveryByTerminal.delete(terminal)
+    }
+  }
+}
+
+export function discardTerminalOutput(terminal: TerminalOutputTarget): void {
+  exposeDebugApi()
+  const entry = queuedByTerminal.get(terminal)
+  if (entry) {
+    // Why: discarded chunks still consumed their deliveries — credit them or main's in-flight window leaks (fireQueuedAckCredits).
+    fireQueuedAckCredits(entry)
+  }
+  discardInFlightTerminalOutputAckCredits(terminal)
+  queuedByTerminal.delete(terminal)
+  discardForegroundRenderSettle(terminal)
+  // Why: cancel the watch without masquerading as parse progress; replay guards use real completions to tell slow from wedged.
+  cancelTerminalWriteStallWatch(terminal)
+  recordQueueDebugPressure()
+}
diff --git a/src/renderer/src/lib/pane-manager/pane-terminal-output-scheduler.ts b/src/renderer/src/lib/pane-manager/pane-terminal-output-scheduler.ts
index 402b847d421..a181de7416e 100644
--- a/src/renderer/src/lib/pane-manager/pane-terminal-output-scheduler.ts
+++ b/src/renderer/src/lib/pane-manager/pane-terminal-output-scheduler.ts
@@ -1,962 +1,66 @@
-/* oxlint-disable max-lines -- Why: output ordering, foreground settle, queue state, and e2e diagnostics form one state machine; splitting it would make backlog/resume guarantees harder to audit. */
 import {
-  discardForegroundRenderSettle,
-  writeForegroundTerminalChunk,
-  type ForegroundTerminalOutputTarget
-} from './pane-terminal-foreground-render-settle'
-import { runGuardedWriteCompletionStep } from './xterm-write-callback-guard'
-import { recordRendererCrashBreadcrumb } from '@/lib/crash-breadcrumb-recorder'
-import {
-  discardInFlightTerminalOutputAckCredits,
-  registerTerminalOutputAckCredits
-} from './pane-terminal-output-ack-credit'
-import {
-  armTerminalWriteStallWatch,
-  cancelTerminalWriteStallWatch,
   failTerminalWriteStallWatch,
   isTerminalWritePipelineCertifiedDead,
-  recordTerminalParseProgress,
-  settleTerminalWriteStallWatch
+  recordTerminalParseProgress
 } from './terminal-write-pipeline-health'
+import { exposeTerminalOutputSchedulerDebugApi as exposeDebugApi } from './pane-terminal-output-scheduler-debug'
+import { flushTerminalOutputImpl } from './pane-terminal-output-flusher'
+import { writeTerminalOutputImpl } from './pane-terminal-output-writer'
 import {
-  TERMINAL_OUTPUT_BACKLOG_MIN_CAP_CHARS,
-  terminalOutputBacklogCapChars
-} from '../../../../shared/terminal-scrollback-policy'
-import {
-  coalescedQueuedDataNeedsCursorRestore,
-  containsDrainableCursorRestore,
-  removeTransientCursorShowSequences,
-  SYNC_FOREGROUND_FLUSH_CHARS
-} from './pane-terminal-cursor-sequencing'
-import {
-  exposeTerminalOutputSchedulerDebugApi as exposeDebugApi,
-  recordTerminalOutputQueueDebugPressure as recordQueueDebugPressure,
-  setTerminalOutputDebugQueueReader,
-  terminalOutputSchedulerDebugEnabled as debugEnabled,
-  terminalOutputSchedulerDebugState as debugState
-} from './pane-terminal-output-scheduler-debug'
-import { enqueueChunk, takeQueuedChunk } from './pane-terminal-output-queue-chunks'
+  requestRegisteredTerminalBacklogRecovery,
+  type TerminalOutputTarget,
+  type WriteTerminalOutputOptions
+} from './pane-terminal-output-queue-registry'
+// Why this bare import: pane-terminal-output-drain registers the drain runner that the registry's
+// scheduleDrain invokes, and this facade is every consumer's entry point into the scheduler graph.
+import './pane-terminal-output-drain'
 
-type TerminalOutputTarget = ForegroundTerminalOutputTarget
+export {
+  ALWAYS_REFRESH_FOREGROUND_SYNCHRONOUSLY,
+  BACKGROUND_BACKLOG_WARNING,
+  BACKGROUND_CHUNK_CHARS,
+  BACKGROUND_DRAIN_INTERVAL_MS,
+  BACKGROUND_FLUSH_DELAY_MS,
+  DRAIN_TIME_BUDGET_MS,
+  FOREGROUND_BACKLOG_WARNING,
+  HIGH_PRIORITY_DRAIN_INTERVAL_MS,
+  HIGH_PRIORITY_MAX_WRITES_PER_DRAIN,
+  LARGE_BACKLOG_CHARS,
+  MAX_BACKGROUND_QUEUE_CHUNKS,
+  MAX_WRITES_PER_DRAIN,
+  configureTerminalOutputBacklogCap,
+  discardTerminalOutput,
+  getTerminalOutputMaxQueueChars,
+  isMessageChannelDrainEnabled,
+  markTerminalOutputDrainStarted,
+  queuedByTerminal,
+  registerTerminalBacklogRecovery,
+  requestRegisteredTerminalBacklogRecovery,
+  scheduleDrain,
+  setUseMessageChannelDrainForTesting,
+  type QueueEntry,
+  type QueuedWrite,
+  type TerminalOutputBeforeWrite,
+  type TerminalOutputParsedCallback,
+  type TerminalOutputTarget,
+  type WriteTerminalOutputOptions
+} from './pane-terminal-output-queue-registry'
 
-export type TerminalOutputBeforeWrite = (data: string) => void
-type TerminalBacklogRecoveryRequest = () => boolean
-export type TerminalOutputParsedCallback = () => void
-type ForegroundRefreshSyncResolver = () => boolean
-
-type WriteTerminalOutputOptions = {
-  foreground: boolean
-  beforeWrite?: TerminalOutputBeforeWrite
-  onParsed?: TerminalOutputParsedCallback
-  /** Parse-deferred delivery ACK (terminal-pty-ack-gate). MUST be invoked when the chunk is parsed OR discarded by any drop path; fire-once, so double invocation is safe but omission permanently shrinks main's in-flight window. */
-  ackCredit?: () => void
-  onBackgroundBacklogDropped?: () => void
-  latencySensitive?: boolean
-  forceForegroundRefresh?: boolean
-  followupForegroundRefresh?: boolean
-  shouldRefreshForegroundSynchronously?: ForegroundRefreshSyncResolver
-  stripTransientCursorShows?: boolean
-  coalesceForeground?: boolean
-  holdForeground?: boolean
-}
-
-type QueueChunk = {
-  data: string
-  // Tracks the backing data still reachable through this queue slot.
-  retainedChars: number
-  foreground: boolean
-  forceForegroundRefresh: boolean
-  followupForegroundRefresh: boolean
-  shouldRefreshForegroundSynchronously: ForegroundRefreshSyncResolver
-  stripTransientCursorShows: boolean
-  beforeWrite?: TerminalOutputBeforeWrite
-  onParsed?: TerminalOutputParsedCallback
-  ackCredit?: () => void
-}
-
-export type QueuedWrite = {
-  data: string
-  foreground: boolean
-  forceForegroundRefresh: boolean
-  followupForegroundRefresh: boolean
-  shouldRefreshForegroundSynchronously: ForegroundRefreshSyncResolver
-  stripTransientCursorShows: boolean
-  beforeWrite?: TerminalOutputBeforeWrite
-  onParsed?: TerminalOutputParsedCallback
-  ackCredits: (() => void)[]
-}
-
-export type QueueEntry = {
-  terminal: TerminalOutputTarget
-  chunks: QueueChunk[]
-  chunkIndex: number
-  queuedChars: number
-  onBackgroundBacklogDropped?: () => void
-  backgroundBacklogDropped: boolean
-  highPriority: boolean
-  foregroundHold: boolean
-  foregroundHoldSafetyDelayMs: number
-  foregroundCoalesce: boolean
-  foregroundCoalesceDelayMs: number
-  foregroundHoldSafetyTimer: ReturnType<typeof setTimeout> | null
-  foregroundCoalesceTimer: ReturnType<typeof setTimeout> | null
-  // Why: hold and coalesce cancel each other's fallback timer, so an alternating DEC 2026 stream could re-arm both forever and freeze a visible pane (#8754). This caps one non-drainable episode.
-  foregroundReleaseDeadlineAt: number | null
-  // Why: an open frame's own hold chunks may still push the deadline out, but once coalesce has taken the entry over the deadline stops moving so the two mechanisms can't re-arm each other.
-  foregroundReleaseDeadlineFixed: boolean
-}
-
-const BACKGROUND_FLUSH_DELAY_MS = 50
-const BACKGROUND_DRAIN_INTERVAL_MS = 16
-const HIGH_PRIORITY_DRAIN_INTERVAL_MS = 4
-const BACKGROUND_CHUNK_CHARS = 16 * 1024
-const MAX_WRITES_PER_DRAIN = 2
-// Why 8: per-tick volume (8 x 16KB = 128KB ≈ 1.3ms parse) sets the sustained ceiling (~30MB/s) within DRAIN_TIME_BUDGET_MS; at 2 it was only 8MB/s against a ~100MB/s parser (see throughput bench).
-const HIGH_PRIORITY_MAX_WRITES_PER_DRAIN = 8
-const DRAIN_TIME_BUDGET_MS = 8
-const LARGE_BACKLOG_CHARS = 512 * 1024
-// Why mutable: the cap scales with the user's scrollback setting (terminalOutputBacklogCapChars), configured when settings apply; the chunk-count cap stays fixed.
-let maxQueueChars = TERMINAL_OUTPUT_BACKLOG_MIN_CAP_CHARS
-const MAX_BACKGROUND_QUEUE_CHUNKS = 4096
-
-export function configureTerminalOutputBacklogCap(scrollbackRows: unknown): void {
-  maxQueueChars = terminalOutputBacklogCapChars(scrollbackRows)
-}
 const PARSE_SETTLE_TIMEOUT_MS = 250
-const FOREGROUND_COALESCE_DELAY_MS = 1000
-const FOREGROUND_HOLD_SAFETY_DELAY_MS = 250
-// Why: key repeat can tick every 30-50ms; one frame catches split restores without batching multiple typed-character redraws behind the fallback.
-const LATENCY_SENSITIVE_FOREGROUND_COALESCE_DELAY_MS = 16
-const LATENCY_SENSITIVE_FOREGROUND_HOLD_SAFETY_DELAY_MS = 32
-// Why: leading CAN aborts any partial escape sequence before the style reset so the backlog warning renders cleanly.
-const BACKGROUND_BACKLOG_WARNING =
-  '\x18\x1b[0m\r\n[Orca skipped hidden terminal output because the backlog grew too large.]\r\n'
-// Why a separate foreground message: a visible pane hitting the cap means the drain couldn't keep up with a flood (starved renderer), not merely output produced while hidden.
-const FOREGROUND_BACKLOG_WARNING =
-  '\x18\x1b[0m\r\n[Orca skipped a burst of terminal output because the backlog grew too large.]\r\n'
-const ALWAYS_REFRESH_FOREGROUND_SYNCHRONOUSLY = (): boolean => true
-
-const queuedByTerminal = new Map<TerminalOutputTarget, QueueEntry>()
-setTerminalOutputDebugQueueReader(() => queuedByTerminal.values())
-const backlogRecoveryByTerminal = new WeakMap<
-  TerminalOutputTarget,
-  TerminalBacklogRecoveryRequest
->()
-let drainTimer: ReturnType<typeof setTimeout> | null = null
-let drainTimerDelayMs: number | null = null
-// Why a MessageChannel for zero-delay drains: Chromium clamps nested setTimeout(0) to ~4ms; a posted macrotask isn't clamped yet still yields to input/paint. Cancellation is by generation.
-let drainImmediatePending = false
-let drainImmediateGeneration = 0
-let useMessageChannelDrain = typeof MessageChannel !== 'undefined' && !isVitestEnv()
-let drainChannel: MessageChannel | null = null
-
-function isVitestEnv(): boolean {
-  // Why: vitest fake timers can't advance MessageChannel macrotasks; the timer path keeps the suites' virtual clock authoritative.
-  return typeof process !== 'undefined' && process.env?.VITEST === 'true'
-}
-
-function getDrainChannel(): MessageChannel {
-  if (drainChannel === null) {
-    drainChannel = new MessageChannel()
-    drainChannel.port1.onmessage = (event: MessageEvent) => {
-      if (event.data !== drainImmediateGeneration || !drainImmediatePending) {
-        return
-      }
-      drainImmediatePending = false
-      drainQueuedOutput()
-    }
-  }
-  return drainChannel
-}
-
-function cancelImmediateDrain(): void {
-  drainImmediateGeneration++
-  drainImmediatePending = false
-}
-
-export function setUseMessageChannelDrainForTesting(value: boolean | null): void {
-  cancelImmediateDrain()
-  useMessageChannelDrain = value ?? (typeof MessageChannel !== 'undefined' && !isVitestEnv())
-}
-
-function scheduleDrain(delayMs: number): void {
-  if (drainImmediatePending) {
-    // An immediate drain is already armed — nothing can beat zero delay.
-    return
-  }
-  if (drainTimer !== null) {
-    if (drainTimerDelayMs !== null && drainTimerDelayMs <= delayMs) {
-      return
-    }
-    clearTimeout(drainTimer)
-    drainTimer = null
-    drainTimerDelayMs = null
-  }
-  if (queuedByTerminal.size === 0) {
-    return
-  }
-  if (debugEnabled) {
-    debugState.scheduledDrainCount++
-  }
-  if (delayMs === 0 && useMessageChannelDrain) {
-    drainImmediatePending = true
-    getDrainChannel().port2.postMessage(drainImmediateGeneration)
-    return
-  }
-  drainTimer = setTimeout(drainQueuedOutput, delayMs)
-  drainTimerDelayMs = delayMs
-}
-
-function createQueueEntry(
-  terminal: TerminalOutputTarget,
-  options: WriteTerminalOutputOptions
-): QueueEntry {
-  return {
-    terminal,
-    chunks: [],
-    chunkIndex: 0,
-    queuedChars: 0,
-    onBackgroundBacklogDropped: options.onBackgroundBacklogDropped,
-    backgroundBacklogDropped: false,
-    highPriority: true,
-    foregroundHold: false,
-    foregroundHoldSafetyDelayMs: FOREGROUND_HOLD_SAFETY_DELAY_MS,
-    foregroundCoalesce: false,
-    foregroundCoalesceDelayMs: FOREGROUND_COALESCE_DELAY_MS,
-    foregroundHoldSafetyTimer: null,
-    foregroundCoalesceTimer: null,
-    foregroundReleaseDeadlineAt: null,
-    foregroundReleaseDeadlineFixed: false
-  }
-}
-
-// Returns the delay the caller's timer must use so it never outlives the episode deadline.
-function armForegroundReleaseDeadline(
-  entry: QueueEntry,
-  delayMs: number,
-  mayExtend: boolean
-): number {
-  const now = getDrainNow()
-  const requested = now + delayMs
-  entry.foregroundReleaseDeadlineAt =
-    entry.foregroundReleaseDeadlineAt === null ||
-    (mayExtend && !entry.foregroundReleaseDeadlineFixed)
-      ? requested
-      : Math.min(entry.foregroundReleaseDeadlineAt, requested)
-  return Math.max(0, entry.foregroundReleaseDeadlineAt - now)
-}
-
-// Why: reopen the gate only once the entry is drainable again, so the next synchronized frame gets a full budget.
-function resetForegroundReleaseGate(entry: QueueEntry): void {
-  entry.foregroundReleaseDeadlineAt = null
-  entry.foregroundReleaseDeadlineFixed = false
-}
-
-function clearForegroundRelease(entry: QueueEntry): void {
-  clearForegroundHoldSafety(entry)
-  clearForegroundCoalesce(entry)
-  resetForegroundReleaseGate(entry)
-}
-
-function clearForegroundHoldSafety(entry: QueueEntry): void {
-  if (entry.foregroundHoldSafetyTimer === null) {
-    return
-  }
-  clearTimeout(entry.foregroundHoldSafetyTimer)
-  entry.foregroundHoldSafetyTimer = null
-  entry.foregroundHoldSafetyDelayMs = FOREGROUND_HOLD_SAFETY_DELAY_MS
-}
-
-function clearForegroundCoalesce(entry: QueueEntry): void {
-  if (entry.foregroundCoalesceTimer !== null) {
-    clearTimeout(entry.foregroundCoalesceTimer)
-    entry.foregroundCoalesceTimer = null
-  }
-  entry.foregroundCoalesce = false
-  entry.foregroundCoalesceDelayMs = FOREGROUND_COALESCE_DELAY_MS
-}
-
-function scheduleForegroundHoldSafety(entry: QueueEntry): void {
-  clearForegroundHoldSafety(entry)
-  const delayMs = armForegroundReleaseDeadline(entry, entry.foregroundHoldSafetyDelayMs, true)
-  entry.foregroundHoldSafetyTimer = setTimeout(() => {
-    entry.foregroundHoldSafetyTimer = null
-    entry.foregroundHold = false
-    clearForegroundCoalesce(entry)
-    resetForegroundReleaseGate(entry)
-    if (queuedByTerminal.has(entry.terminal)) {
-      scheduleDrain(0)
-    }
-  }, delayMs)
-}
-
-function scheduleForegroundCoalesceRelease(
-  entry: QueueEntry,
-  options?: { rescheduleEarlier?: boolean }
-): void {
-  if (entry.foregroundCoalesceTimer !== null) {
-    if (options?.rescheduleEarlier !== true) {
-      entry.foregroundCoalesce = true
-      return
-    }
-    clearTimeout(entry.foregroundCoalesceTimer)
-    entry.foregroundCoalesceTimer = null
-  }
-  entry.foregroundCoalesce = true
-  // Why fixed from here: a later hold chunk must clamp to this deadline instead of restarting the pair's mutual re-arm (#8754).
-  entry.foregroundReleaseDeadlineFixed = true
-  const delayMs = armForegroundReleaseDeadline(entry, entry.foregroundCoalesceDelayMs, false)
-  entry.foregroundCoalesceTimer = setTimeout(() => {
-    entry.foregroundCoalesceTimer = null
-    entry.foregroundCoalesce = false
-    resetForegroundReleaseGate(entry)
-    if (queuedByTerminal.has(entry.terminal)) {
-      scheduleDrain(0)
-    }
-  }, delayMs)
-}
-
-function isEntryDrainable(entry: QueueEntry): boolean {
-  return !entry.foregroundHold && !entry.foregroundCoalesce
-}
-
-// Why: every discard path MUST fire these before clearing/replacing the queue — a dropped chunk still counts as consumed, or main's in-flight window shrinks permanently and the PTY wedges.
-function fireQueuedAckCredits(entry: QueueEntry): void {
-  for (let index = entry.chunkIndex; index < entry.chunks.length; index += 1) {
-    entry.chunks[index].ackCredit?.()
-  }
-}
-
-function discardDetachedQueueEntry(entry: QueueEntry): void {
-  fireQueuedAckCredits(entry)
-  entry.chunks.length = 0
-  entry.chunkIndex = 0
-  entry.queuedChars = 0
-  entry.highPriority = false
-  clearForegroundRelease(entry)
-}
-
-function queueCapExceeded(entry: QueueEntry): boolean {
-  return (
-    entry.queuedChars > maxQueueChars ||
-    entry.chunks.length - entry.chunkIndex > MAX_BACKGROUND_QUEUE_CHUNKS
-  )
-}
-
-function replaceBacklogWithWarning(
-  entry: QueueEntry,
-  warning: string = BACKGROUND_BACKLOG_WARNING
-): void {
-  const shouldNotify = !entry.backgroundBacklogDropped
-  if (shouldNotify) {
-    // Why: field visibility for cap tuning — drop frequency and size decide whether the cap is too small (issue #2836 / #7017).
-    recordRendererCrashBreadcrumb('terminal_output_backlog_dropped', {
-      foreground: warning === FOREGROUND_BACKLOG_WARNING,
-      droppedChars: entry.queuedChars,
-      capChars: maxQueueChars
-    })
-  }
-  let beforeWrite: TerminalOutputBeforeWrite | undefined
-  for (let index = entry.chunks.length - 1; index >= entry.chunkIndex; index--) {
-    if (entry.chunks[index]?.beforeWrite) {
-      beforeWrite = entry.chunks[index].beforeWrite
-      break
-    }
-  }
-  clearForegroundHoldSafety(entry)
-  fireQueuedAckCredits(entry)
-  entry.chunks = [
-    {
-      data: warning,
-      retainedChars: warning.length,
-      foreground: false,
-      forceForegroundRefresh: false,
-      followupForegroundRefresh: false,
-      shouldRefreshForegroundSynchronously: ALWAYS_REFRESH_FOREGROUND_SYNCHRONOUSLY,
-      stripTransientCursorShows: false,
-      beforeWrite
-    }
-  ]
-  entry.chunkIndex = 0
-  entry.queuedChars = warning.length
-  entry.backgroundBacklogDropped = true
-  entry.highPriority = true
-  entry.foregroundHold = false
-  if (debugEnabled && shouldNotify) {
-    debugState.droppedBacklogCount++
-  }
-  clearForegroundRelease(entry)
-  recordQueueDebugPressure()
-  if (shouldNotify) {
-    entry.onBackgroundBacklogDropped?.()
-  }
-}
-
-function hasQueuedChunks(entry: QueueEntry): boolean {
-  return entry.chunkIndex < entry.chunks.length
-}
-
-function hasHighPriorityBacklog(): boolean {
-  for (const entry of queuedByTerminal.values()) {
-    if (
-      isEntryDrainable(entry) &&
-      (entry.highPriority || entry.queuedChars > LARGE_BACKLOG_CHARS)
-    ) {
-      return true
-    }
-  }
-  return false
-}
-
-function hasDrainableBacklog(): boolean {
-  for (const entry of queuedByTerminal.values()) {
-    if (isEntryDrainable(entry)) {
-      return true
-    }
-  }
-  return false
-}
-
-// Why no per-write scroll enforcement: xterm's BufferService.isUserScrolling owns live follow/pin; app-side enforcement is limited to structural ops xterm can't identify, like replay.
-function writeBackgroundTerminalChunk(
-  terminal: TerminalOutputTarget,
-  data: string,
-  onParsed?: TerminalOutputParsedCallback,
-  onWriteFailure?: () => void
-): boolean {
-  // Why guarded: these callbacks run inside xterm's WriteBuffer loop, where an escaping throw permanently wedges the terminal (see xterm-write-callback-guard.ts).
-  const runOnParsed = onParsed
-    ? (): void => runGuardedWriteCompletionStep('background-on-parsed', onParsed)
-    : undefined
-  const runOnWriteFailure = onWriteFailure
-    ? (): void => runGuardedWriteCompletionStep('background-on-write-failure', onWriteFailure)
-    : undefined
-  try {
-    if (!runOnParsed || terminal.write.length < 2) {
-      terminal.write(data)
-      runOnParsed?.()
-      return true
-    }
-    terminal.write(data, runOnParsed)
-    return true
-  } catch {
-    runOnWriteFailure?.()
-    return false
-  }
-}
-
-function takeNextDrainableEntry(): QueueEntry | null {
-  let largeBacklogEntry: QueueEntry | null = null
-  for (const entry of queuedByTerminal.values()) {
-    if (!isEntryDrainable(entry)) {
-      continue
-    }
-    // Why: active/foreground output should be chosen first, not left in insertion order behind older background terminals.
-    if (entry.highPriority) {
-      queuedByTerminal.delete(entry.terminal)
-      return entry
-    }
-    if (!largeBacklogEntry && entry.queuedChars > LARGE_BACKLOG_CHARS) {
-      largeBacklogEntry = entry
-    }
-  }
-  if (largeBacklogEntry) {
-    queuedByTerminal.delete(largeBacklogEntry.terminal)
-    return largeBacklogEntry
-  }
-  for (const entry of queuedByTerminal.values()) {
-    if (!isEntryDrainable(entry)) {
-      continue
-    }
-    queuedByTerminal.delete(entry.terminal)
-    return entry
-  }
-  return null
-}
-
-// Why: re-arm a zero-delay drain once xterm confirms the previous high-priority batch parsed; the fixed 4/16ms cadence otherwise drips far below xterm's ~100 MB/s parse. Only visible panes are pacer-clocked; background keeps the fixed cadence to protect the focused terminal.
-function makeParseClockPacer(): () => void {
-  return () => {
-    try {
-      if (queuedByTerminal.size > 0 && hasHighPriorityBacklog()) {
-        scheduleDrain(0)
-      }
-    } catch {
-      // Why: runs inside xterm's write-callback chain; a throw here would wedge the terminal (see xterm-write-callback-guard.ts).
-    }
-  }
-}
-
-function composeParsedCallback(
-  terminal: TerminalOutputTarget,
-  onParsed: TerminalOutputParsedCallback | undefined,
-  ackCreditsParsed: (() => void) | undefined,
-  pacer: (() => void) | undefined
-): TerminalOutputParsedCallback {
-  // Why always non-undefined: the callback doubles as the pipeline-health settle signal — with none, the stall watch could never settle, forcing a probe round-trip per healthy idle pane.
-  return () => {
-    try {
-      onParsed?.()
-    } finally {
-      ackCreditsParsed?.()
-      pacer?.()
-      settleTerminalWriteStallWatch(terminal)
-    }
-  }
-}
-
-function composeWriteFailureCallback(
-  terminal: TerminalOutputTarget,
-  ackCreditsParsed: (() => void) | undefined
-): () => void {
-  return () => {
-    try {
-      // A rejected write still consumed the main-owned delivery window.
-      ackCreditsParsed?.()
-    } finally {
-      // Why: a synchronous rejection proves undeliverability but nothing about parse progress; recover without extending replay guards.
-      failTerminalWriteStallWatch(terminal)
-    }
-  }
-}
-
-function writeQueuedChunk(entry: QueueEntry): 'foreground' | 'background' | null {
-  if (isTerminalWritePipelineCertifiedDead(entry.terminal)) {
-    // The drain owns this detached entry, so map-based discard cannot see it.
-    discardDetachedQueueEntry(entry)
-    discardTerminalOutput(entry.terminal)
-    return null
-  }
-  const queuedWrite = takeQueuedChunk(entry, BACKGROUND_CHUNK_CHARS)
-  if (!queuedWrite) {
-    return null
-  }
-  const pacer = entry.highPriority ? makeParseClockPacer() : undefined
-  const ackCreditsParsed = registerTerminalOutputAckCredits(entry.terminal, queuedWrite.ackCredits)
-  // Why armed BEFORE the write: a wedged WriteBuffer (issue #2836) or disposed xterm (6.1.0-beta.287) never runs the parsed callback, so the watch must be live first to catch it.
-  armTerminalWriteStallWatch(entry.terminal, {
-    onCertifiedDead: () => discardTerminalOutput(entry.terminal)
-  })
-  try {
-    queuedWrite.beforeWrite?.(queuedWrite.data)
-    const writeAccepted = queuedWrite.foreground
-      ? writeForegroundTerminalChunk(
-          entry.terminal,
-          queuedWrite.stripTransientCursorShows
-            ? removeTransientCursorShowSequences(queuedWrite.data)
-            : queuedWrite.data,
-          {
-            forceViewportRefresh: queuedWrite.forceForegroundRefresh,
-            followupViewportRefresh: queuedWrite.followupForegroundRefresh,
-            shouldRefreshViewportSynchronously: queuedWrite.shouldRefreshForegroundSynchronously,
-            onParsed: composeParsedCallback(
-              entry.terminal,
-              queuedWrite.onParsed,
-              ackCreditsParsed,
-              pacer
-            ),
-            onWriteFailure: composeWriteFailureCallback(entry.terminal, ackCreditsParsed)
-          }
-        )
-      : writeBackgroundTerminalChunk(
-          entry.terminal,
-          queuedWrite.data,
-          composeParsedCallback(entry.terminal, queuedWrite.onParsed, ackCreditsParsed, pacer),
-          composeWriteFailureCallback(entry.terminal, ackCreditsParsed)
-        )
-    if (!writeAccepted) {
-      // Why: the failure callback credited the submitted chunk; credit and abandon the detached tail so the drain can't retry a certified-dead xterm.
-      fireQueuedAckCredits(entry)
-      entry.chunks.length = 0
-      entry.chunkIndex = 0
-      entry.queuedChars = 0
-      clearForegroundRelease(entry)
-      recordQueueDebugPressure()
-      return null
-    }
-  } catch {
-    // Why: beforeWrite or write setup can fail before xterm owns the bytes; cancel the armed watch without claiming parser failure.
-    cancelTerminalWriteStallWatch(entry.terminal)
-    ackCreditsParsed?.()
-    fireQueuedAckCredits(entry)
-    entry.chunks.length = 0
-    entry.chunkIndex = 0
-    entry.queuedChars = 0
-    clearForegroundRelease(entry)
-    recordQueueDebugPressure()
-    return null
-  }
-  return queuedWrite.foreground ? 'foreground' : 'background'
-}
-
-function getDrainNow(): number {
-  if (typeof performance !== 'undefined') {
-    return performance.now()
-  }
-  return Date.now()
-}
-
-function drainQueuedOutput(): void {
-  drainTimer = null
-  drainTimerDelayMs = null
-  let writes = 0
-  const startedAt = getDrainNow()
-  const highPriority = hasHighPriorityBacklog()
-  const maxWrites = highPriority ? HIGH_PRIORITY_MAX_WRITES_PER_DRAIN : MAX_WRITES_PER_DRAIN
-
-  while (queuedByTerminal.size > 0 && writes < maxWrites) {
-    const entry = takeNextDrainableEntry()
-    if (!entry) {
-      break
-    }
-
-    const writeKind = writeQueuedChunk(entry)
-    if (writeKind) {
-      writes++
-      if (debugEnabled) {
-        if (writeKind === 'foreground') {
-          debugState.deferredForegroundWriteCount++
-        } else {
-          debugState.backgroundWriteCount++
-        }
-      }
-    }
-    if (hasQueuedChunks(entry)) {
-      queuedByTerminal.set(entry.terminal, entry)
-    } else {
-      entry.highPriority = false
-      clearForegroundRelease(entry)
-    }
-    // Why: xterm parsing and DOM work share the renderer thread with input; keep draining cooperative so WSL/agent output can't pin the UI.
-    if (writes > 0 && getDrainNow() - startedAt >= DRAIN_TIME_BUDGET_MS) {
-      break
-    }
-  }
-
-  if (debugEnabled && writes > 0) {
-    debugState.drainWrites.push(writes)
-    debugState.drainHighPriority.push(highPriority)
-  }
-  recordQueueDebugPressure()
-  if (queuedByTerminal.size > 0 && hasDrainableBacklog()) {
-    // Why 0 on the channel path: a posted message already yields (input/paint serviced between macrotasks), so the 4ms interval only deepened the queue; timer path keeps it for fake-timer tests.
-    scheduleDrain(
-      hasHighPriorityBacklog()
-        ? useMessageChannelDrain
-          ? 0
-          : HIGH_PRIORITY_DRAIN_INTERVAL_MS
-        : BACKGROUND_DRAIN_INTERVAL_MS
-    )
-  }
-}
 
 export function writeTerminalOutput(
   terminal: TerminalOutputTarget,
   data: string,
   options: WriteTerminalOutputOptions
 ): void {
-  exposeDebugApi()
-  // Why: recovery may be budget-delayed while PTY output keeps flowing; main owns the authoritative buffer, so credit delivery without waking dead xterm.
-  if (isTerminalWritePipelineCertifiedDead(terminal)) {
-    options.ackCredit?.()
-    return
-  }
-  if (!data) {
-    // Why: an empty write still consumed its delivery — credit or main's in-flight window leaks.
-    options.ackCredit?.()
-    return
-  }
-
-  if (options.foreground) {
-    const entry = queuedByTerminal.get(terminal)
-    if (entry?.highPriority || options.coalesceForeground || options.holdForeground) {
-      const queued = entry ?? createQueueEntry(terminal, options)
-      queued.onBackgroundBacklogDropped = options.onBackgroundBacklogDropped
-      queued.highPriority = true
-      queuedByTerminal.set(terminal, queued)
-      enqueueChunk(queued, data, {
-        foreground: true,
-        forceForegroundRefresh: options.forceForegroundRefresh,
-        followupForegroundRefresh: options.followupForegroundRefresh,
-        shouldRefreshForegroundSynchronously: options.shouldRefreshForegroundSynchronously,
-        stripTransientCursorShows: options.stripTransientCursorShows,
-        beforeWrite: options.beforeWrite,
-        onParsed: options.onParsed,
-        ackCredit: options.ackCredit
-      })
-      if (debugEnabled) {
-        debugState.foregroundWriteCount++
-        debugState.deferredForegroundEnqueueCount++
-      }
-      // Why: a visible pane's queue was previously uncapped — a flood the drain couldn't keep up with ballooned renderer memory without bound.
-      if (queueCapExceeded(queued)) {
-        replaceBacklogWithWarning(queued, FOREGROUND_BACKLOG_WARNING)
-        scheduleDrain(0)
-        return
-      }
-      if (options.holdForeground) {
-        // Why: synchronized-output start/body chunks contain transient cursor moves; holding them prevents Chromium from rasterizing those states.
-        if (options.latencySensitive === true) {
-          // Why: Codex composer redraws can split the end marker from the input-triggered frame; keep cursor protection without a human-visible fallback delay on typed chars.
-          queued.foregroundHoldSafetyDelayMs = Math.min(
-            queued.foregroundHoldSafetyDelayMs,
-            LATENCY_SENSITIVE_FOREGROUND_HOLD_SAFETY_DELAY_MS
-          )
-        } else if (!queued.foregroundHold) {
-          queued.foregroundHoldSafetyDelayMs = FOREGROUND_HOLD_SAFETY_DELAY_MS
-        }
-        queued.foregroundHold = true
-        clearForegroundCoalesce(queued)
-        scheduleForegroundHoldSafety(queued)
-        return
-      }
-      if (options.coalesceForeground || queued.foregroundCoalesce) {
-        queued.foregroundHold = false
-        clearForegroundHoldSafety(queued)
-        const shouldShortenCoalesceForLatencySensitiveForeground = options.latencySensitive === true
-        if (shouldShortenCoalesceForLatencySensitiveForeground) {
-          // Why: user input echo must not inherit the normal synchronized-frame restore fallback; wait briefly for the restore, then paint.
-          queued.foregroundCoalesceDelayMs = Math.min(
-            queued.foregroundCoalesceDelayMs,
-            LATENCY_SENSITIVE_FOREGROUND_COALESCE_DELAY_MS
-          )
-        }
-        const shouldDrainForLatencySensitiveForeground =
-          shouldShortenCoalesceForLatencySensitiveForeground &&
-          !coalescedQueuedDataNeedsCursorRestore(queued)
-        if (containsDrainableCursorRestore(data) || shouldDrainForLatencySensitiveForeground) {
-          clearForegroundRelease(queued)
-          scheduleDrain(0)
-          return
-        }
-        // Why: the PTY transport can split TUI synchronized-output end markers from the cursor-restoring bytes; wait for the restore, with the timer as bounded fallback.
-        scheduleForegroundCoalesceRelease(queued, {
-          rescheduleEarlier: shouldShortenCoalesceForLatencySensitiveForeground
-        })
-        return
-      }
-      queued.foregroundHold = false
-      clearForegroundRelease(queued)
-      scheduleDrain(0)
-      return
-    }
-    if (entry && entry.queuedChars > SYNC_FOREGROUND_FLUSH_CHARS) {
-      entry.highPriority = true
-      enqueueChunk(entry, data, {
-        foreground: true,
-        forceForegroundRefresh: options.forceForegroundRefresh,
-        followupForegroundRefresh: options.followupForegroundRefresh,
-        shouldRefreshForegroundSynchronously: options.shouldRefreshForegroundSynchronously,
-        stripTransientCursorShows: options.stripTransientCursorShows,
-        beforeWrite: options.beforeWrite,
-        onParsed: options.onParsed,
-        ackCredit: options.ackCredit
-      })
-      if (debugEnabled) {
-        debugState.foregroundWriteCount++
-        debugState.deferredForegroundEnqueueCount++
-      }
-      if (queueCapExceeded(entry)) {
-        replaceBacklogWithWarning(entry, FOREGROUND_BACKLOG_WARNING)
-      }
-      // Why: returning from a hidden window can have megabytes queued — keep byte order but drain async so the first foreground frame isn't pinned behind the whole backlog.
-      scheduleDrain(0)
-      return
-    }
-    if (options.latencySensitive === false) {
-      let queued = entry
-      if (!queued) {
-        queued = createQueueEntry(terminal, options)
-        queuedByTerminal.set(terminal, queued)
-      } else {
-        queued.onBackgroundBacklogDropped = options.onBackgroundBacklogDropped
-        queued.highPriority = true
-      }
-      enqueueChunk(queued, data, {
-        foreground: true,
-        forceForegroundRefresh: options.forceForegroundRefresh,
-        followupForegroundRefresh: options.followupForegroundRefresh,
-        shouldRefreshForegroundSynchronously: options.shouldRefreshForegroundSynchronously,
-        stripTransientCursorShows: options.stripTransientCursorShows,
-        beforeWrite: options.beforeWrite,
-        onParsed: options.onParsed,
-        ackCredit: options.ackCredit
-      })
-      if (debugEnabled) {
-        debugState.foregroundWriteCount++
-        debugState.deferredForegroundEnqueueCount++
-      }
-      if (queueCapExceeded(queued)) {
-        replaceBacklogWithWarning(queued, FOREGROUND_BACKLOG_WARNING)
-      }
-      // Why: visible command floods are throughput work, not keystroke echo — queue behind a zero-delay drain so one IPC callback can't pin the renderer while input/paint wait.
-      scheduleDrain(0)
-      return
-    }
-    flushTerminalOutput(terminal)
-    if (debugEnabled) {
-      debugState.foregroundWriteCount++
-    }
-    const ackCreditsParsed = registerTerminalOutputAckCredits(
-      terminal,
-      options.ackCredit ? [options.ackCredit] : []
-    )
-    armTerminalWriteStallWatch(terminal, {
-      onCertifiedDead: () => discardTerminalOutput(terminal)
-    })
-    try {
-      options.beforeWrite?.(data)
-      writeForegroundTerminalChunk(
-        terminal,
-        options.stripTransientCursorShows ? removeTransientCursorShowSequences(data) : data,
-        {
-          forceViewportRefresh: options.forceForegroundRefresh === true,
-          followupViewportRefresh: options.followupForegroundRefresh === true,
-          shouldRefreshViewportSynchronously:
-            options.shouldRefreshForegroundSynchronously ?? ALWAYS_REFRESH_FOREGROUND_SYNCHRONOUSLY,
-          onParsed: composeParsedCallback(terminal, options.onParsed, ackCreditsParsed, undefined),
-          onWriteFailure: composeWriteFailureCallback(terminal, ackCreditsParsed)
-        }
-      )
-    } catch (error) {
-      // Why: beforeWrite can throw before xterm owns the callback, so consume the delivery here (xterm write throws are caught by the foreground writer).
-      ackCreditsParsed?.()
-      cancelTerminalWriteStallWatch(terminal)
-      throw error
-    }
-    return
-  }
-
-  let entry = queuedByTerminal.get(terminal)
-  if (!entry) {
-    entry = createQueueEntry(terminal, options)
-    entry.highPriority = false
-    queuedByTerminal.set(terminal, entry)
-  } else {
-    entry.onBackgroundBacklogDropped = options.onBackgroundBacklogDropped
-  }
-  enqueueChunk(entry, data, {
-    beforeWrite: options.beforeWrite,
-    onParsed: options.onParsed,
-    ackCredit: options.ackCredit
-  })
-  if (queueCapExceeded(entry)) {
-    replaceBacklogWithWarning(entry)
-  }
-  if (debugEnabled) {
-    debugState.backgroundEnqueueCount++
-  }
-  // Why: letting every non-focused pane call xterm.write immediately spawns a WriteBuffer timer per pane, starving the focused terminal on the shared renderer thread.
-  scheduleDrain(
-    entry.highPriority || entry.queuedChars > LARGE_BACKLOG_CHARS ? 0 : BACKGROUND_FLUSH_DELAY_MS
-  )
+  writeTerminalOutputImpl(terminal, data, options)
 }
 
 export function flushTerminalOutput(
   terminal: TerminalOutputTarget,
   options?: { maxChars?: number }
 ): void {
-  exposeDebugApi()
-  const entry = queuedByTerminal.get(terminal)
-  if (!entry) {
-    return
-  }
-  queuedByTerminal.delete(terminal)
-  if (isTerminalWritePipelineCertifiedDead(terminal)) {
-    discardDetachedQueueEntry(entry)
-    discardTerminalOutput(terminal)
-    return
-  }
-  if (!isEntryDrainable(entry)) {
-    queuedByTerminal.set(terminal, entry)
-    return
-  }
-  if (entry.backgroundBacklogDropped && requestRegisteredTerminalBacklogRecovery(terminal)) {
-    fireQueuedAckCredits(entry)
-    entry.chunks.length = 0
-    entry.chunkIndex = 0
-    entry.queuedChars = 0
-    entry.highPriority = false
-    clearForegroundRelease(entry)
-    recordQueueDebugPressure()
-    return
-  }
-
-  let flushedChars = 0
-  let queuedWrite = takeQueuedChunk(entry, BACKGROUND_CHUNK_CHARS)
-  while (queuedWrite) {
-    flushedChars += queuedWrite.data.length
-    if (debugEnabled) {
-      debugState.flushWriteCount++
-    }
-    const ackCreditsParsed = registerTerminalOutputAckCredits(terminal, queuedWrite.ackCredits)
-    armTerminalWriteStallWatch(terminal, {
-      onCertifiedDead: () => discardTerminalOutput(terminal)
-    })
-    try {
-      queuedWrite.beforeWrite?.(queuedWrite.data)
-      const writeAccepted = queuedWrite.foreground
-        ? writeForegroundTerminalChunk(
-            terminal,
-            queuedWrite.stripTransientCursorShows
-              ? removeTransientCursorShowSequences(queuedWrite.data)
-              : queuedWrite.data,
-            {
-              forceViewportRefresh: queuedWrite.forceForegroundRefresh,
-              followupViewportRefresh: queuedWrite.followupForegroundRefresh,
-              shouldRefreshViewportSynchronously: queuedWrite.shouldRefreshForegroundSynchronously,
-              onParsed: composeParsedCallback(
-                terminal,
-                queuedWrite.onParsed,
-                ackCreditsParsed,
-                undefined
-              ),
-              onWriteFailure: composeWriteFailureCallback(terminal, ackCreditsParsed)
-            }
-          )
-        : writeBackgroundTerminalChunk(
-            terminal,
-            queuedWrite.data,
-            composeParsedCallback(terminal, queuedWrite.onParsed, ackCreditsParsed, undefined),
-            composeWriteFailureCallback(terminal, ackCreditsParsed)
-          )
-      if (!writeAccepted) {
-        fireQueuedAckCredits(entry)
-        clearForegroundRelease(entry)
-        recordQueueDebugPressure()
-        return
-      }
-    } catch {
-      // Why: pre-write hooks/setup failed before xterm owned these bytes; cancel the watch, but consumed + abandoned chunks still credit delivery.
-      cancelTerminalWriteStallWatch(terminal)
-      ackCreditsParsed?.()
-      fireQueuedAckCredits(entry)
-      clearForegroundRelease(entry)
-      recordQueueDebugPressure()
-      return
-    }
-    if (options?.maxChars !== undefined && flushedChars >= options.maxChars) {
-      break
-    }
-    queuedWrite = takeQueuedChunk(entry, BACKGROUND_CHUNK_CHARS)
-  }
-  if (hasQueuedChunks(entry)) {
-    entry.highPriority = true
-    queuedByTerminal.set(terminal, entry)
-    scheduleDrain(0)
-  } else {
-    entry.highPriority = false
-    clearForegroundRelease(entry)
-  }
-  recordQueueDebugPressure()
-}
-
-function requestRegisteredTerminalBacklogRecovery(terminal: TerminalOutputTarget): boolean {
-  const requestRecovery = backlogRecoveryByTerminal.get(terminal)
-  if (!requestRecovery) {
-    return false
-  }
-  return requestRecovery()
+  flushTerminalOutputImpl(terminal, options)
 }
 
 export function requestTerminalBacklogRecovery(terminal: TerminalOutputTarget): void {
@@ -964,18 +68,6 @@ export function requestTerminalBacklogRecovery(terminal: TerminalOutputTarget):
   requestRegisteredTerminalBacklogRecovery(terminal)
 }
 
-export function registerTerminalBacklogRecovery(
-  terminal: TerminalOutputTarget,
-  requestRecovery: TerminalBacklogRecoveryRequest
-): () => void {
-  backlogRecoveryByTerminal.set(terminal, requestRecovery)
-  return () => {
-    if (backlogRecoveryByTerminal.get(terminal) === requestRecovery) {
-      backlogRecoveryByTerminal.delete(terminal)
-    }
-  }
-}
-
 export function waitForTerminalOutputParsed(terminal: TerminalOutputTarget): Promise<void> {
   flushTerminalOutput(terminal)
   if (isTerminalWritePipelineCertifiedDead(terminal)) {
@@ -1012,19 +104,4 @@ export function waitForTerminalOutputParsed(terminal: TerminalOutputTarget): Pro
   })
 }
 
-export function discardTerminalOutput(terminal: TerminalOutputTarget): void {
-  exposeDebugApi()
-  const entry = queuedByTerminal.get(terminal)
-  if (entry) {
-    // Why: discarded chunks still consumed their deliveries — credit them or main's in-flight window leaks (fireQueuedAckCredits).
-    fireQueuedAckCredits(entry)
-  }
-  discardInFlightTerminalOutputAckCredits(terminal)
-  queuedByTerminal.delete(terminal)
-  discardForegroundRenderSettle(terminal)
-  // Why: cancel the watch without masquerading as parse progress; replay guards use real completions to tell slow from wedged.
-  cancelTerminalWriteStallWatch(terminal)
-  recordQueueDebugPressure()
-}
-
 exposeDebugApi()
diff --git a/src/renderer/src/lib/pane-manager/pane-terminal-output-writer.ts b/src/renderer/src/lib/pane-manager/pane-terminal-output-writer.ts
new file mode 100644
index 00000000000..89c3ba13364
--- /dev/null
+++ b/src/renderer/src/lib/pane-manager/pane-terminal-output-writer.ts
@@ -0,0 +1,246 @@
+import { writeForegroundTerminalChunk } from './pane-terminal-foreground-render-settle'
+import { registerTerminalOutputAckCredits } from './pane-terminal-output-ack-credit'
+import {
+  armTerminalWriteStallWatch,
+  cancelTerminalWriteStallWatch,
+  isTerminalWritePipelineCertifiedDead
+} from './terminal-write-pipeline-health'
+import {
+  coalescedQueuedDataNeedsCursorRestore,
+  containsDrainableCursorRestore,
+  removeTransientCursorShowSequences,
+  SYNC_FOREGROUND_FLUSH_CHARS
+} from './pane-terminal-cursor-sequencing'
+import { enqueueChunk } from './pane-terminal-output-queue-chunks'
+import {
+  exposeTerminalOutputSchedulerDebugApi as exposeDebugApi,
+  terminalOutputSchedulerDebugEnabled as debugEnabled,
+  terminalOutputSchedulerDebugState as debugState
+} from './pane-terminal-output-scheduler-debug'
+import { flushTerminalOutputImpl } from './pane-terminal-output-flusher'
+import { composeParsedCallback, composeWriteFailureCallback } from './pane-terminal-output-pipeline'
+import { queueCapExceeded, replaceBacklogWithWarning } from './pane-terminal-output-queue-backlog'
+import {
+  FOREGROUND_HOLD_SAFETY_DELAY_MS,
+  LATENCY_SENSITIVE_FOREGROUND_COALESCE_DELAY_MS,
+  LATENCY_SENSITIVE_FOREGROUND_HOLD_SAFETY_DELAY_MS,
+  clearForegroundCoalesce,
+  clearForegroundHoldSafety,
+  clearForegroundRelease,
+  createQueueEntry,
+  scheduleForegroundCoalesceRelease,
+  scheduleForegroundHoldSafety
+} from './pane-terminal-foreground-queue-state'
+import {
+  ALWAYS_REFRESH_FOREGROUND_SYNCHRONOUSLY,
+  BACKGROUND_FLUSH_DELAY_MS,
+  FOREGROUND_BACKLOG_WARNING,
+  LARGE_BACKLOG_CHARS,
+  discardTerminalOutput,
+  queuedByTerminal,
+  scheduleDrain,
+  type TerminalOutputTarget,
+  type WriteTerminalOutputOptions
+} from './pane-terminal-output-queue-registry'
+
+export function writeTerminalOutputImpl(
+  terminal: TerminalOutputTarget,
+  data: string,
+  options: WriteTerminalOutputOptions
+): void {
+  exposeDebugApi()
+  // Why: recovery may be budget-delayed while PTY output keeps flowing; main owns the authoritative buffer, so credit delivery without waking dead xterm.
+  if (isTerminalWritePipelineCertifiedDead(terminal)) {
+    options.ackCredit?.()
+    return
+  }
+  if (!data) {
+    // Why: an empty write still consumed its delivery — credit or main's in-flight window leaks.
+    options.ackCredit?.()
+    return
+  }
+
+  if (options.foreground) {
+    const entry = queuedByTerminal.get(terminal)
+    if (entry?.highPriority || options.coalesceForeground || options.holdForeground) {
+      const queued = entry ?? createQueueEntry(terminal, options)
+      queued.onBackgroundBacklogDropped = options.onBackgroundBacklogDropped
+      queued.highPriority = true
+      queuedByTerminal.set(terminal, queued)
+      enqueueChunk(queued, data, {
+        foreground: true,
+        forceForegroundRefresh: options.forceForegroundRefresh,
+        followupForegroundRefresh: options.followupForegroundRefresh,
+        shouldRefreshForegroundSynchronously: options.shouldRefreshForegroundSynchronously,
+        stripTransientCursorShows: options.stripTransientCursorShows,
+        beforeWrite: options.beforeWrite,
+        onParsed: options.onParsed,
+        ackCredit: options.ackCredit
+      })
+      if (debugEnabled) {
+        debugState.foregroundWriteCount++
+        debugState.deferredForegroundEnqueueCount++
+      }
+      // Why: a visible pane's queue was previously uncapped — a flood the drain couldn't keep up with ballooned renderer memory without bound.
+      if (queueCapExceeded(queued)) {
+        replaceBacklogWithWarning(queued, FOREGROUND_BACKLOG_WARNING)
+        scheduleDrain(0)
+        return
+      }
+      if (options.holdForeground) {
+        // Why: synchronized-output start/body chunks contain transient cursor moves; holding them prevents Chromium from rasterizing those states.
+        if (options.latencySensitive === true) {
+          // Why: Codex composer redraws can split the end marker from the input-triggered frame; keep cursor protection without a human-visible fallback delay on typed chars.
+          queued.foregroundHoldSafetyDelayMs = Math.min(
+            queued.foregroundHoldSafetyDelayMs,
+            LATENCY_SENSITIVE_FOREGROUND_HOLD_SAFETY_DELAY_MS
+          )
+        } else if (!queued.foregroundHold) {
+          queued.foregroundHoldSafetyDelayMs = FOREGROUND_HOLD_SAFETY_DELAY_MS
+        }
+        queued.foregroundHold = true
+        clearForegroundCoalesce(queued)
+        scheduleForegroundHoldSafety(queued)
+        return
+      }
+      if (options.coalesceForeground || queued.foregroundCoalesce) {
+        queued.foregroundHold = false
+        clearForegroundHoldSafety(queued)
+        const shouldShortenCoalesceForLatencySensitiveForeground = options.latencySensitive === true
+        if (shouldShortenCoalesceForLatencySensitiveForeground) {
+          // Why: user input echo must not inherit the normal synchronized-frame restore fallback; wait briefly for the restore, then paint.
+          queued.foregroundCoalesceDelayMs = Math.min(
+            queued.foregroundCoalesceDelayMs,
+            LATENCY_SENSITIVE_FOREGROUND_COALESCE_DELAY_MS
+          )
+        }
+        const shouldDrainForLatencySensitiveForeground =
+          shouldShortenCoalesceForLatencySensitiveForeground &&
+          !coalescedQueuedDataNeedsCursorRestore(queued)
+        if (containsDrainableCursorRestore(data) || shouldDrainForLatencySensitiveForeground) {
+          clearForegroundRelease(queued)
+          scheduleDrain(0)
+          return
+        }
+        // Why: the PTY transport can split TUI synchronized-output end markers from the cursor-restoring bytes; wait for the restore, with the timer as bounded fallback.
+        scheduleForegroundCoalesceRelease(queued, {
+          rescheduleEarlier: shouldShortenCoalesceForLatencySensitiveForeground
+        })
+        return
+      }
+      queued.foregroundHold = false
+      clearForegroundRelease(queued)
+      scheduleDrain(0)
+      return
+    }
+    if (entry && entry.queuedChars > SYNC_FOREGROUND_FLUSH_CHARS) {
+      entry.highPriority = true
+      enqueueChunk(entry, data, {
+        foreground: true,
+        forceForegroundRefresh: options.forceForegroundRefresh,
+        followupForegroundRefresh: options.followupForegroundRefresh,
+        shouldRefreshForegroundSynchronously: options.shouldRefreshForegroundSynchronously,
+        stripTransientCursorShows: options.stripTransientCursorShows,
+        beforeWrite: options.beforeWrite,
+        onParsed: options.onParsed,
+        ackCredit: options.ackCredit
+      })
+      if (debugEnabled) {
+        debugState.foregroundWriteCount++
+        debugState.deferredForegroundEnqueueCount++
+      }
+      if (queueCapExceeded(entry)) {
+        replaceBacklogWithWarning(entry, FOREGROUND_BACKLOG_WARNING)
+      }
+      // Why: returning from a hidden window can have megabytes queued — keep byte order but drain async so the first foreground frame isn't pinned behind the whole backlog.
+      scheduleDrain(0)
+      return
+    }
+    if (options.latencySensitive === false) {
+      let queued = entry
+      if (!queued) {
+        queued = createQueueEntry(terminal, options)
+        queuedByTerminal.set(terminal, queued)
+      } else {
+        queued.onBackgroundBacklogDropped = options.onBackgroundBacklogDropped
+        queued.highPriority = true
+      }
+      enqueueChunk(queued, data, {
+        foreground: true,
+        forceForegroundRefresh: options.forceForegroundRefresh,
+        followupForegroundRefresh: options.followupForegroundRefresh,
+        shouldRefreshForegroundSynchronously: options.shouldRefreshForegroundSynchronously,
+        stripTransientCursorShows: options.stripTransientCursorShows,
+        beforeWrite: options.beforeWrite,
+        onParsed: options.onParsed,
+        ackCredit: options.ackCredit
+      })
+      if (debugEnabled) {
+        debugState.foregroundWriteCount++
+        debugState.deferredForegroundEnqueueCount++
+      }
+      if (queueCapExceeded(queued)) {
+        replaceBacklogWithWarning(queued, FOREGROUND_BACKLOG_WARNING)
+      }
+      // Why: visible command floods are throughput work, not keystroke echo — queue behind a zero-delay drain so one IPC callback can't pin the renderer while input/paint wait.
+      scheduleDrain(0)
+      return
+    }
+    flushTerminalOutputImpl(terminal)
+    if (debugEnabled) {
+      debugState.foregroundWriteCount++
+    }
+    const ackCreditsParsed = registerTerminalOutputAckCredits(
+      terminal,
+      options.ackCredit ? [options.ackCredit] : []
+    )
+    armTerminalWriteStallWatch(terminal, {
+      onCertifiedDead: () => discardTerminalOutput(terminal)
+    })
+    try {
+      options.beforeWrite?.(data)
+      writeForegroundTerminalChunk(
+        terminal,
+        options.stripTransientCursorShows ? removeTransientCursorShowSequences(data) : data,
+        {
+          forceViewportRefresh: options.forceForegroundRefresh === true,
+          followupViewportRefresh: options.followupForegroundRefresh === true,
+          shouldRefreshViewportSynchronously:
+            options.shouldRefreshForegroundSynchronously ?? ALWAYS_REFRESH_FOREGROUND_SYNCHRONOUSLY,
+          onParsed: composeParsedCallback(terminal, options.onParsed, ackCreditsParsed, undefined),
+          onWriteFailure: composeWriteFailureCallback(terminal, ackCreditsParsed)
+        }
+      )
+    } catch (error) {
+      // Why: beforeWrite can throw before xterm owns the callback, so consume the delivery here (xterm write throws are caught by the foreground writer).
+      ackCreditsParsed?.()
+      cancelTerminalWriteStallWatch(terminal)
+      throw error
+    }
+    return
+  }
+
+  let entry = queuedByTerminal.get(terminal)
+  if (!entry) {
+    entry = createQueueEntry(terminal, options)
+    entry.highPriority = false
+    queuedByTerminal.set(terminal, entry)
+  } else {
+    entry.onBackgroundBacklogDropped = options.onBackgroundBacklogDropped
+  }
+  enqueueChunk(entry, data, {
+    beforeWrite: options.beforeWrite,
+    onParsed: options.onParsed,
+    ackCredit: options.ackCredit
+  })
+  if (queueCapExceeded(entry)) {
+    replaceBacklogWithWarning(entry)
+  }
+  if (debugEnabled) {
+    debugState.backgroundEnqueueCount++
+  }
+  // Why: letting every non-focused pane call xterm.write immediately spawns a WriteBuffer timer per pane, starving the focused terminal on the shared renderer thread.
+  scheduleDrain(
+    entry.highPriority || entry.queuedChars > LARGE_BACKLOG_CHARS ? 0 : BACKGROUND_FLUSH_DELAY_MS
+  )
+}

From 692ff95dd3322c76fad56e4399e68164850cb3d3 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sat, 29 Aug 2026 20:04:45 -0700
Subject: [PATCH 22/31] Split mobile browser pane modules (#17141)

* Split speech session lifecycle

* Split terminal output scheduler pipeline

* Split mobile browser pane modules

* Fix F3-speech for #17123

* Fix F1-cycle for #17131
---
 config/max-lines-baseline.txt                 |    1 -
 mobile/.oxlintrc.json                         |    6 -
 mobile/src/browser/MobileBrowserPane.tsx      | 1138 ++---------------
 mobile/src/browser/MobileBrowserPaneView.tsx  |  321 +++++
 .../browser/mobile-browser-stream-events.ts   |   77 ++
 .../browser/use-mobile-browser-commands.ts    |  248 ++++
 .../browser/use-mobile-browser-frame-apply.ts |  122 ++
 .../use-mobile-browser-interactions.ts        |  290 +++++
 .../browser/use-mobile-browser-pane-layers.ts |  141 ++
 .../src/browser/use-mobile-browser-request.ts |   67 +
 .../src/browser/use-mobile-browser-stream.ts  |  283 ++++
 11 files changed, 1668 insertions(+), 1026 deletions(-)
 create mode 100644 mobile/src/browser/MobileBrowserPaneView.tsx
 create mode 100644 mobile/src/browser/mobile-browser-stream-events.ts
 create mode 100644 mobile/src/browser/use-mobile-browser-commands.ts
 create mode 100644 mobile/src/browser/use-mobile-browser-frame-apply.ts
 create mode 100644 mobile/src/browser/use-mobile-browser-interactions.ts
 create mode 100644 mobile/src/browser/use-mobile-browser-pane-layers.ts
 create mode 100644 mobile/src/browser/use-mobile-browser-request.ts
 create mode 100644 mobile/src/browser/use-mobile-browser-stream.ts

diff --git a/config/max-lines-baseline.txt b/config/max-lines-baseline.txt
index 2dc0e163346..cd2253dcde7 100644
--- a/config/max-lines-baseline.txt
+++ b/config/max-lines-baseline.txt
@@ -83,7 +83,6 @@ mobile-config app/h/*/tasks.tsx
 mobile-config app/index.tsx
 mobile-config app/troubleshoot.tsx
 mobile-config scripts/mock-server.ts
-mobile-config src/browser/MobileBrowserPane.tsx
 mobile-config src/components/NewWorktreeModal.tsx
 mobile-config src/terminal/terminal-webview-html.ts
 mobile-config src/transport/rpc-client.ts
diff --git a/mobile/.oxlintrc.json b/mobile/.oxlintrc.json
index f3338fc3616..7192820eb16 100644
--- a/mobile/.oxlintrc.json
+++ b/mobile/.oxlintrc.json
@@ -51,12 +51,6 @@
         "max-lines": ["error", { "max": 1603, "skipBlankLines": true, "skipComments": true }]
       }
     },
-    {
-      "files": ["src/browser/MobileBrowserPane.tsx"],
-      "rules": {
-        "max-lines": ["error", { "max": 1594, "skipBlankLines": true, "skipComments": true }]
-      }
-    },
     {
       "files": ["app/index.tsx"],
       "rules": {
diff --git a/mobile/src/browser/MobileBrowserPane.tsx b/mobile/src/browser/MobileBrowserPane.tsx
index f823f309630..2922d2005a4 100644
--- a/mobile/src/browser/MobileBrowserPane.tsx
+++ b/mobile/src/browser/MobileBrowserPane.tsx
@@ -1,77 +1,31 @@
 /* oxlint-disable react-doctor/no-adjust-state-on-prop-change -- Why: mobile browser state mirrors a remote desktop screencast session and CDP dialogs, which are external systems that cannot be derived during render. */
-import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react'
-import {
-  ActivityIndicator,
-  AppState,
-  Image,
-  PanResponder,
-  PixelRatio,
-  Pressable,
-  Text,
-  TextInput,
-  View,
-  type GestureResponderEvent,
-  type PanResponderGestureState
-} from 'react-native'
-import { ArrowUp, ChevronLeft, ChevronRight, RefreshCw } from 'lucide-react-native'
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react'
+import { AppState, type Image, type View } from 'react-native'
 import type { RpcClient } from '../transport/rpc-client'
-import type { RpcFailure, RpcSuccess } from '../transport/types'
 import type {
   BrowserScreencastFrame,
   BrowserScreencastFrameMetadata
 } from '../transport/browser-screencast-protocol'
-import { colors } from '../theme/mobile-theme'
-import {
-  MOBILE_BROWSER_FRAME_MIN_INTERVAL_MS,
-  buildMobileBrowserScreencastRequest,
-  type MobileBrowserViewMode
-} from './browser-screencast-request'
-import {
-  MobileBrowserPointerModifiers,
-  type BrowserPointerModifier
-} from './MobileBrowserPointerModifiers'
-import { MobileBrowserKeyRow } from './MobileBrowserKeyRow'
-import { MobileBrowserToolbarIconButton } from './MobileBrowserToolbarIconButton'
-import { MobileBrowserViewModeSwitch } from './MobileBrowserViewModeSwitch'
+import type { MobileBrowserViewMode } from './browser-screencast-request'
+import type { BrowserPointerModifier } from './MobileBrowserPointerModifiers'
 import {
   getInitialMobileBrowserViewMode,
   saveMobileBrowserViewMode
 } from './mobile-browser-view-mode-state'
+import type { BrowserTouchLayout, BrowserZoomState } from './browser-touch-geometry'
 import {
-  clampBrowserZoomState,
-  computeBrowserFrameGeometry,
-  computeBrowserTouchClickRadiusCss,
-  mapScreenToBrowserPoint,
-  readLocalTouchPoint,
-  type BrowserPoint,
-  type BrowserTouchLayout,
-  type BrowserZoomState
-} from './browser-touch-geometry'
-import {
-  MAX_ZOOM,
-  MIN_ZOOM,
-  assertRpcOk,
-  browserErrorMessage,
-  browserFrameMetadataEqual,
-  buttonColor,
-  cacheBrowserFrame,
   clearCachedBrowserFramesForWorktree,
-  createBrowserFrameDataUri,
-  createPinchGesture,
-  getCachedBrowserFrame,
   makeBrowserFrameCacheKey,
   peekCachedBrowserFrame,
-  shouldSurfaceBrowserError,
-  updateBrowserImageSource,
-  updateBrowserLayerVisibility,
-  updatePinchZoom,
   type FrameLayer,
   type PinchGesture
 } from './mobile-browser-frame-state'
-import { mobileBrowserPaneStyles as styles } from './mobile-browser-pane-styles'
 import { displayBrowserUrl, normalizeBrowserUrl } from './browser-url'
-import { MobileBrowserAddressField } from './MobileBrowserAddressField'
 import { resolveMobileBrowserAddressSync } from './mobile-browser-address-sync'
+import { MobileBrowserPaneView } from './MobileBrowserPaneView'
+import { useMobileBrowserInteractions } from './use-mobile-browser-interactions'
+import { useMobileBrowserPaneLayers } from './use-mobile-browser-pane-layers'
+import { useMobileBrowserStream } from './use-mobile-browser-stream'
 
 export type MobileBrowserTab = {
   type: 'browser'
@@ -108,26 +62,8 @@ type BrowserDialogState = {
   message: string
 }
 
-const TAP_SLOP = 16
-const SCROLL_START_SLOP = 22
-const LONG_PRESS_MS = 550
-const WHEEL_INTERVAL_MS = 70
-const TOUCH_CLICK_RADIUS_DIP = 14
 const DEFAULT_ZOOM: BrowserZoomState = { scale: 1, offsetX: 0, offsetY: 0 }
 
-type BrowserPageParams = {
-  worktree: string
-  page: string
-}
-
-type PendingWheelCommand = {
-  base: BrowserPageParams
-  point: BrowserPoint
-  gestureId: number
-  dx: number
-  dy: number
-}
-
 export function MobileBrowserPane({
   client,
   worktreeId,
@@ -180,17 +116,12 @@ export function MobileBrowserPane({
   const frameThrottleTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
   const dialogRef = useRef<BrowserDialogState | null>(null)
   const lastStreamCacheKeyRef = useRef<string | null>(cacheKey)
-  const startPointRef = useRef<{ x: number; y: number; t: number } | null>(null)
   const longPressTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
-  const rightClickSentRef = useRef(false)
-  const lastWheelRef = useRef<{ dx: number; dy: number; at: number }>({ dx: 0, dy: 0, at: 0 })
-  const wheelGestureIdRef = useRef(0)
-  const pendingWheelCommandRef = useRef<PendingWheelCommand | null>(null)
-  const wheelCommandInFlightRef = useRef(false)
+  const startPointRef = useRef<{ x: number; y: number; t: number } | null>(null)
+  const scrollingRef = useRef(false)
   const zoomRef = useRef<BrowserZoomState>(DEFAULT_ZOOM)
   const pinchRef = useRef<PinchGesture | null>(null)
   const panRef = useRef<PanGesture | null>(null)
-  const scrollingRef = useRef(false)
   const lastZoomResetUrlRef = useRef(tab.url || 'about:blank')
 
   const clearLongPressTimer = useCallback(() => {
@@ -265,313 +196,40 @@ export function MobileBrowserPane({
     setBrowserViewMode(getInitialMobileBrowserViewMode(worktreeId, tab.browserPageId, tab.url))
   }, [tab.browserPageId, tab.url, worktreeId])
 
-  const pageParams = useCallback(() => {
-    if (!tab.browserPageId) {
-      return null
-    }
-    return {
-      worktree: `id:${worktreeId}`,
-      page: tab.browserPageId
-    }
-  }, [tab.browserPageId, worktreeId])
-
-  const applyFrame = useCallback((frame: BrowserScreencastFrame, frameCacheKey: string): void => {
-    if (!browserFrameMetadataEqual(frameMetadataRef.current, frame.metadata)) {
-      frameMetadataRef.current = frame.metadata
-      setFrameMetadata(frame.metadata)
-    }
-    const nextFrameUri = createBrowserFrameDataUri(frame)
-    cacheBrowserFrame(frameCacheKey, { uri: nextFrameUri, metadata: frame.metadata })
-    if (!frameMountedRef.current) {
-      frameUriRef.current = nextFrameUri
-      frameMountedRef.current = true
-      setFrameUri(nextFrameUri)
-      updateBrowserImageSource(browserImageRefs.current[0], nextFrameUri)
-    } else if (pendingFrameLayerRef.current === null) {
-      // Why: decode the next frame offscreen and keep the previous layer visible
-      // until onLoad; replacing the visible Image directly flashes black.
-      const nextLayer: FrameLayer = visibleFrameLayerRef.current === 0 ? 1 : 0
-      frameUriRef.current = nextFrameUri
-      pendingFrameLayerRef.current = nextLayer
-      updateBrowserImageSource(browserImageRefs.current[nextLayer], nextFrameUri)
-    } else {
-      // Why: popovers/menus can settle in one final frame while the previous
-      // offscreen frame is still decoding. Keep the hidden layer pointed at
-      // the newest frame instead of dropping the final static state.
-      frameUriRef.current = nextFrameUri
-      updateBrowserImageSource(browserImageRefs.current[pendingFrameLayerRef.current], nextFrameUri)
-    }
-    if (busyRef.current) {
-      busyRef.current = false
-      setBusy(false)
-    }
-  }, [])
-
-  const clearFrameThrottle = useCallback(() => {
-    pendingThrottledFrameRef.current = null
-    if (frameThrottleTimerRef.current) {
-      clearTimeout(frameThrottleTimerRef.current)
-      frameThrottleTimerRef.current = null
-    }
-  }, [])
-
-  const applyFrameThrottled = useCallback(
-    (frame: BrowserScreencastFrame, frameCacheKey: string): void => {
-      const now = Date.now()
-      const elapsed = now - lastAppliedFrameAtRef.current
-      if (lastAppliedFrameAtRef.current === 0 || elapsed >= MOBILE_BROWSER_FRAME_MIN_INTERVAL_MS) {
-        clearFrameThrottle()
-        lastAppliedFrameAtRef.current = now
-        applyFrame(frame, frameCacheKey)
-        return
-      }
-
-      // Why: static UI changes can be the last frame Chromium emits. Coalesce
-      // throttled frames so the final visible state is applied after the delay.
-      pendingThrottledFrameRef.current = { frame, cacheKey: frameCacheKey }
-      if (frameThrottleTimerRef.current) {
-        return
-      }
-      frameThrottleTimerRef.current = setTimeout(
-        () => {
-          frameThrottleTimerRef.current = null
-          const pending = pendingThrottledFrameRef.current
-          pendingThrottledFrameRef.current = null
-          if (!pending) {
-            return
-          }
-          lastAppliedFrameAtRef.current = Date.now()
-          applyFrame(pending.frame, pending.cacheKey)
-        },
-        Math.max(0, MOBILE_BROWSER_FRAME_MIN_INTERVAL_MS - elapsed)
-      )
-    },
-    [applyFrame, clearFrameThrottle]
-  )
-
-  const streamRequest = useMemo(
-    () => buildMobileBrowserScreencastRequest(layout, PixelRatio.get(), browserViewMode),
-    [browserViewMode, layout]
-  )
-
-  const frameGeometry = useMemo(
-    () => computeBrowserFrameGeometry(layout, frameMetadata),
-    [frameMetadata, layout]
-  )
-
-  useEffect(() => {
-    if (!frameGeometry) {
-      return
-    }
-    setZoom((current) => {
-      const next = clampBrowserZoomState(current, frameGeometry, MIN_ZOOM, MAX_ZOOM)
-      if (
-        next.scale === current.scale &&
-        next.offsetX === current.offsetX &&
-        next.offsetY === current.offsetY
-      ) {
-        return current
-      }
-      // Why: rotation/layout changes can shrink the legal pan range while the
-      // current zoom state still points at the previous viewport geometry.
-      zoomRef.current = next
-      return next
-    })
-  }, [frameGeometry])
-
-  useEffect(() => {
-    streamGenerationRef.current += 1
-    const generation = streamGenerationRef.current
-    const sameStream = Boolean(cacheKey) && lastStreamCacheKeyRef.current === cacheKey
-    lastStreamCacheKeyRef.current = cacheKey
-    if (!sameStream || !frameUriRef.current) {
-      const cachedFrame = getCachedBrowserFrame(cacheKey)
-      if (cachedFrame) {
-        frameUriRef.current = cachedFrame.uri
-        frameMountedRef.current = true
-        frameMetadataRef.current = cachedFrame.metadata
-        setFrameUri(cachedFrame.uri)
-        setFrameMetadata(cachedFrame.metadata)
-      } else {
-        frameUriRef.current = null
-        frameMountedRef.current = false
-        setFrameUri(null)
-        setFrameMetadata(null)
-        frameMetadataRef.current = null
-      }
-    } else {
-      frameMountedRef.current = true
-    }
-    pendingFrameLayerRef.current = null
-    if (!sameStream || !frameUriRef.current) {
-      visibleFrameLayerRef.current = 0
-    }
-    updateBrowserLayerVisibility(browserLayerRefs.current, visibleFrameLayerRef.current)
-    lastAppliedFrameAtRef.current = 0
-    clearFrameThrottle()
-    busyRef.current = false
-    setDialog(null)
-    setError(null)
-    if (
-      !client ||
-      screencastSupported !== true ||
-      !tab.browserPageId ||
-      !appActive ||
-      !streamRequest
-    ) {
-      busyRef.current = false
-      setBusy(false)
-      if (screencastSupported === false) {
-        setError('Update desktop Orca to stream browser tabs on mobile.')
-      } else if (screencastSupported === null) {
-        setError('Checking desktop browser streaming support.')
-      } else if (!tab.browserPageId) {
-        setError('Browser page is not available yet.')
-      }
-      return
-    }
-    busyRef.current = true
-    setBusy(true)
-    let startupTimer: ReturnType<typeof setTimeout> | null = setTimeout(() => {
-      if (streamGenerationRef.current !== generation) {
-        return
-      }
-      busyRef.current = false
-      setBusy(false)
-      setError('Browser stream timed out.')
-    }, 15_000)
-    const clearStartupTimer = (): void => {
-      if (startupTimer) {
-        clearTimeout(startupTimer)
-        startupTimer = null
-      }
-    }
-    const unsubscribe = client.subscribe(
-      'browser.screencast',
-      {
-        worktree: `id:${worktreeId}`,
-        page: tab.browserPageId,
-        ...streamRequest
-      },
-      (payload) => {
-        if (streamGenerationRef.current !== generation) {
-          return
-        }
-        const event = payload as {
-          type?: string
-          message?: string
-          error?: { message?: string }
-          dialogType?: string
-          tab?: { url?: string; title?: string; canGoBack?: boolean; canGoForward?: boolean }
-        }
-        if (event.type === 'ready') {
-          clearStartupTimer()
-          if (busyRef.current) {
-            busyRef.current = false
-            setBusy(false)
-          }
-          if (typeof event.tab?.url === 'string') {
-            setAddressValue(displayBrowserUrl(event.tab.url))
-            if (event.tab.url !== lastZoomResetUrlRef.current) {
-              lastZoomResetUrlRef.current = event.tab.url
-              resetBrowserZoomState()
-            }
-          }
-        } else if (event.type === 'end') {
-          clearStartupTimer()
-          if (busyRef.current) {
-            busyRef.current = false
-            setBusy(false)
-          }
-        } else if (event.type === 'dialog') {
-          setDialog({
-            dialogType: event.dialogType ?? 'alert',
-            message: event.message ?? 'Browser dialog'
-          })
-        } else if (event.type === 'dialogClosed') {
-          setDialog(null)
-        } else if (event.type === 'error') {
-          clearStartupTimer()
-          if (busyRef.current) {
-            busyRef.current = false
-            setBusy(false)
-          }
-          const message = event.message ?? event.error?.message ?? 'Browser stream failed.'
-          if (shouldSurfaceBrowserError(message)) {
-            setError(message)
-          }
-        }
-      },
-      {
-        onBinaryFrame: (frame) => {
-          if (streamGenerationRef.current !== generation) {
-            return
-          }
-          clearStartupTimer()
-          if (cacheKey) {
-            applyFrameThrottled(frame, cacheKey)
-          }
-        }
-      }
-    )
-    return () => {
-      clearStartupTimer()
-      clearFrameThrottle()
-      unsubscribe()
-    }
-  }, [
+  const { frameGeometry, pageParams, sendBrowserRequest } = useMobileBrowserStream({
     appActive,
-    applyFrameThrottled,
-    clearFrameThrottle,
+    browserImageRefs,
+    browserLayerRefs,
+    browserViewMode,
+    busyRef,
+    cacheKey,
     client,
+    frameMetadata,
+    frameMetadataRef,
+    frameMountedRef,
+    frameThrottleTimerRef,
+    frameUriRef,
+    lastAppliedFrameAtRef,
+    lastStreamCacheKeyRef,
+    lastZoomResetUrlRef,
+    layout,
+    pendingFrameLayerRef,
+    pendingThrottledFrameRef,
     resetBrowserZoomState,
     screencastSupported,
-    streamRequest,
-    cacheKey,
-    tab.browserPageId,
-    worktreeId
-  ])
-
-  const sendBrowserRequest = useCallback(
-    async (
-      method: string,
-      params: Record<string, unknown> = {},
-      opts: { showBusy?: boolean; suppressError?: boolean; timeoutMs?: number } = {}
-    ): Promise<unknown | null> => {
-      const base = pageParams()
-      if (!client || !base) {
-        return null
-      }
-      if (opts.showBusy) {
-        busyRef.current = true
-        setBusy(true)
-      }
-      try {
-        const response = await client.sendRequest(
-          method,
-          { ...base, ...params },
-          { timeoutMs: opts.timeoutMs ?? 15_000 }
-        )
-        if (!response.ok) {
-          throw new Error((response as RpcFailure).error.message)
-        }
-        setError(null)
-        return (response as RpcSuccess).result
-      } catch (err) {
-        const message = browserErrorMessage(err, 'Browser command failed')
-        if (!opts.suppressError && shouldSurfaceBrowserError(message)) {
-          setError(message)
-        }
-        return null
-      } finally {
-        if (opts.showBusy) {
-          busyRef.current = false
-          setBusy(false)
-        }
-      }
-    },
-    [client, pageParams]
-  )
+    setAddressValue,
+    setBusy,
+    setDialog,
+    setError,
+    setFrameMetadata,
+    setFrameUri,
+    setZoom,
+    streamGenerationRef,
+    tab,
+    visibleFrameLayerRef,
+    worktreeId,
+    zoomRef
+  })
 
   const navigateToAddress = useCallback(async () => {
     const url = normalizeBrowserUrl(addressValue)
@@ -591,411 +249,45 @@ export function MobileBrowserPane({
     }
   }, [addressValue, resetBrowserZoomState, sendBrowserRequest])
 
-  const flushPendingWheelCommand = useCallback(() => {
-    if (wheelCommandInFlightRef.current) {
-      return
-    }
-    const pending = pendingWheelCommandRef.current
-    if (!pending || !client) {
-      return
-    }
-    pendingWheelCommandRef.current = null
-    wheelCommandInFlightRef.current = true
-    void (async () => {
-      try {
-        assertRpcOk(
-          await client.sendRequest('browser.mouseMove', {
-            ...pending.base,
-            x: pending.point.x,
-            y: pending.point.y
-          }),
-          'Browser pointer move failed'
-        )
-        assertRpcOk(
-          await client.sendRequest('browser.mouseWheel', {
-            ...pending.base,
-            dx: pending.dx,
-            dy: pending.dy
-          }),
-          'Browser scroll failed'
-        )
-        setError(null)
-      } catch {
-        // Scroll bursts commonly race page reload/navigation. Avoid replacing
-        // the live browser with transient command errors like selector_not_found.
-      } finally {
-        wheelCommandInFlightRef.current = false
-        flushPendingWheelCommand()
-      }
-    })()
-  }, [client])
+  const { panResponder, sendDialogCommand, sendKeyboardText, sendKeypress, togglePointerModifier } =
+    useMobileBrowserInteractions({
+      clearLongPressTimer,
+      client,
+      dialogRef,
+      frameGeometry,
+      frameMetadataRef,
+      keyboardValue,
+      layoutRef,
+      longPressTimerRef,
+      onToast,
+      pageParams,
+      panRef,
+      pinchRef,
+      pointerModifiers,
+      sendBrowserRequest,
+      scrollingRef,
+      startPointRef,
+      setDialog,
+      setError,
+      setKeyboardValue,
+      setPointerModifiers,
+      setZoom,
+      zoomRef
+    })
 
-  const sendPointerClick = useCallback(
-    async (point: BrowserPoint, button: 'left' | 'right') => {
-      const base = pageParams()
-      if (!client || !base) {
-        return
-      }
-      const clickResult = await sendBrowserRequest(
-        'browser.mouseClick',
-        {
-          x: point.x,
-          y: point.y,
-          button,
-          modifiers: pointerModifiers,
-          ...(button === 'left'
-            ? {
-                radius: computeBrowserTouchClickRadiusCss(
-                  layoutRef.current,
-                  frameMetadataRef.current,
-                  zoomRef.current,
-                  TOUCH_CLICK_RADIUS_DIP
-                )
-              }
-            : {})
-        },
-        { suppressError: true, timeoutMs: 5_000 }
-      )
-      if (clickResult !== null || pointerModifiers.length > 0) {
-        return
-      }
-      try {
-        assertRpcOk(
-          await client.sendRequest('browser.mouseMove', { ...base, x: point.x, y: point.y }),
-          'Browser pointer move failed'
-        )
-        assertRpcOk(
-          await client.sendRequest('browser.mouseDown', { ...base, button }),
-          'Browser pointer down failed'
-        )
-        assertRpcOk(
-          await client.sendRequest('browser.mouseUp', { ...base, button }),
-          'Browser pointer up failed'
-        )
-        setError(null)
-      } catch {
-        // Pointer commands can race page navigation. Keep the stream visible;
-        // actionable failures still surface through navigation/stream errors.
-      }
-    },
-    [client, pageParams, pointerModifiers, sendBrowserRequest]
-  )
-
-  const togglePointerModifier = useCallback((modifier: BrowserPointerModifier) => {
-    setPointerModifiers((current) =>
-      current.includes(modifier)
-        ? current.filter((candidate) => candidate !== modifier)
-        : [...current, modifier]
-    )
-  }, [])
-
-  const sendWheel = useCallback(
-    (point: BrowserPoint, screenDx: number, screenDy: number) => {
-      const base = pageParams()
-      if (!client || !base) {
-        return
-      }
-      const currentLayout = layoutRef.current
-      const geometry = computeBrowserFrameGeometry(currentLayout, frameMetadataRef.current)
-      const localZoom = zoomRef.current.scale
-      const scale = (geometry?.scale ?? 1) * localZoom
-      const cssDx = screenDx / scale
-      const cssDy = screenDy / scale
-      const delta = { dx: Math.round(-cssDx), dy: Math.round(-cssDy) }
-      if (Math.abs(delta.dx) < 1 && Math.abs(delta.dy) < 1) {
-        return
-      }
-      const pending = pendingWheelCommandRef.current
-      pendingWheelCommandRef.current =
-        pending &&
-        pending.base.page === base.page &&
-        pending.gestureId === wheelGestureIdRef.current
-          ? {
-              base,
-              point,
-              gestureId: wheelGestureIdRef.current,
-              dx: pending.dx + delta.dx,
-              dy: pending.dy + delta.dy
-            }
-          : { base, point, gestureId: wheelGestureIdRef.current, ...delta }
-      flushPendingWheelCommand()
-    },
-    [client, flushPendingWheelCommand, pageParams]
-  )
-
-  const mapTouchPoint = useCallback((locationX: number, locationY: number): BrowserPoint | null => {
-    return mapScreenToBrowserPoint(
-      locationX,
-      locationY,
-      layoutRef.current,
-      frameMetadataRef.current,
-      zoomRef.current
-    )
-  }, [])
-
-  const handleResponderGrant = useCallback(
-    (event: GestureResponderEvent) => {
-      const pinch = createPinchGesture(event, frameGeometry, zoomRef.current)
-      if (pinch) {
-        clearLongPressTimer()
-        pinchRef.current = pinch
-        panRef.current = null
-        startPointRef.current = null
-        return
-      }
-      const startPoint = readLocalTouchPoint(event.nativeEvent)
-      if (!startPoint) {
-        return
-      }
-      startPointRef.current = { x: startPoint.x, y: startPoint.y, t: Date.now() }
-      rightClickSentRef.current = false
-      scrollingRef.current = false
-      wheelGestureIdRef.current += 1
-      lastWheelRef.current = { dx: 0, dy: 0, at: 0 }
-      panRef.current =
-        zoomRef.current.scale > MIN_ZOOM
-          ? {
-              x: startPoint.x,
-              y: startPoint.y,
-              offsetX: zoomRef.current.offsetX,
-              offsetY: zoomRef.current.offsetY
-            }
-          : null
-      clearLongPressTimer()
-      longPressTimerRef.current = setTimeout(() => {
-        const start = startPointRef.current
-        if (!start) {
-          return
-        }
-        const point = mapTouchPoint(start.x, start.y)
-        if (!point) {
-          return
-        }
-        rightClickSentRef.current = true
-        void sendPointerClick(point, 'right')
-        onToast('Right click')
-      }, LONG_PRESS_MS)
-    },
-    [clearLongPressTimer, frameGeometry, mapTouchPoint, onToast, sendPointerClick]
-  )
-
-  const handleResponderMove = useCallback(
-    (event: GestureResponderEvent, gesture: PanResponderGestureState) => {
-      const startedPinch = pinchRef.current
-        ? null
-        : createPinchGesture(event, frameGeometry, zoomRef.current)
-      if (startedPinch) {
-        clearLongPressTimer()
-        pinchRef.current = startedPinch
-        panRef.current = null
-        startPointRef.current = null
-      }
-      const activePinch = pinchRef.current
-      const nextPinch = activePinch ? updatePinchZoom(event, frameGeometry, activePinch) : null
-      if (nextPinch) {
-        clearLongPressTimer()
-        zoomRef.current = nextPinch
-        setZoom(nextPinch)
-        return
-      }
-      if (activePinch) {
-        pinchRef.current = null
-      }
-      const moved = Math.hypot(gesture.dx, gesture.dy)
-      if (moved > TAP_SLOP) {
-        clearLongPressTimer()
-      }
-      const activePan = panRef.current
-      if (activePan && frameGeometry) {
-        const currentPoint = readLocalTouchPoint(event.nativeEvent)
-        if (!currentPoint) {
-          return
-        }
-        if (!scrollingRef.current && moved <= TAP_SLOP) {
-          return
-        }
-        scrollingRef.current = true
-        startPointRef.current = null
-        const nextZoom = clampBrowserZoomState(
-          {
-            scale: zoomRef.current.scale,
-            offsetX: activePan.offsetX + currentPoint.x - activePan.x,
-            offsetY: activePan.offsetY + currentPoint.y - activePan.y
-          },
-          frameGeometry,
-          MIN_ZOOM,
-          MAX_ZOOM
-        )
-        zoomRef.current = nextZoom
-        setZoom(nextZoom)
-        return
-      }
-      if (!scrollingRef.current) {
-        if (moved <= SCROLL_START_SLOP) {
-          return
-        }
-        scrollingRef.current = true
-        startPointRef.current = null
-      }
-      const now = Date.now()
-      if (now - lastWheelRef.current.at < WHEEL_INTERVAL_MS) {
-        return
-      }
-      const deltaX = gesture.dx - lastWheelRef.current.dx
-      const deltaY = gesture.dy - lastWheelRef.current.dy
-      if (Math.abs(deltaX) + Math.abs(deltaY) < 8) {
-        return
-      }
-      const currentPoint = readLocalTouchPoint(event.nativeEvent)
-      if (!currentPoint) {
-        return
-      }
-      const point = mapTouchPoint(currentPoint.x, currentPoint.y)
-      if (!point) {
-        return
-      }
-      lastWheelRef.current = { dx: gesture.dx, dy: gesture.dy, at: now }
-      sendWheel(point, deltaX, deltaY)
-    },
-    [clearLongPressTimer, frameGeometry, mapTouchPoint, sendWheel]
-  )
-
-  const handleResponderRelease = useCallback(
-    (event: GestureResponderEvent, gesture: PanResponderGestureState) => {
-      clearLongPressTimer()
-      pinchRef.current = null
-      panRef.current = null
-      const start = startPointRef.current
-      startPointRef.current = null
-      const wasScrolling = scrollingRef.current
-      scrollingRef.current = false
-      if (!start || rightClickSentRef.current || wasScrolling) {
-        return
-      }
-      const moved = Math.hypot(gesture.dx, gesture.dy)
-      if (moved <= TAP_SLOP && Date.now() - start.t < LONG_PRESS_MS) {
-        // Why: native browser taps resolve at touch-up. Using touch-down makes
-        // tiny finger drift feel like the click lands left/up of the finger.
-        const release = readLocalTouchPoint(event.nativeEvent) ?? start
-        const point = mapTouchPoint(release.x, release.y)
-        if (point) {
-          void sendPointerClick(point, 'left')
-        }
-      }
-    },
-    [clearLongPressTimer, mapTouchPoint, sendPointerClick]
-  )
-
-  const panResponder = useMemo(
-    () =>
-      PanResponder.create({
-        onStartShouldSetPanResponder: () => dialogRef.current === null,
-        onMoveShouldSetPanResponder: () => dialogRef.current === null,
-        onPanResponderGrant: handleResponderGrant,
-        onPanResponderMove: handleResponderMove,
-        onPanResponderRelease: handleResponderRelease,
-        onPanResponderTerminate: () => {
-          clearLongPressTimer()
-          pinchRef.current = null
-          panRef.current = null
-          scrollingRef.current = false
-          startPointRef.current = null
-        },
-        onPanResponderTerminationRequest: () => true
-      }),
-    [clearLongPressTimer, handleResponderGrant, handleResponderMove, handleResponderRelease]
-  )
-
-  const sendKeyboardText = useCallback(async () => {
-    const text = keyboardValue
-    if (!text) {
-      return
-    }
-    setKeyboardValue('')
-    const result = await sendBrowserRequest(
-      'browser.keyboardInsertText',
-      { text },
-      { suppressError: true }
-    )
-    if (result !== null) {
-      onToast('Sent')
-    } else {
-      setKeyboardValue(text)
-    }
-  }, [keyboardValue, onToast, sendBrowserRequest])
-
-  const sendKeypress = useCallback(
-    async (key: string) => {
-      await sendBrowserRequest('browser.keypress', { key }, { suppressError: true })
-    },
-    [sendBrowserRequest]
-  )
-
-  const sendDialogCommand = useCallback(
-    async (method: 'browser.dialogAccept' | 'browser.dialogDismiss') => {
-      setDialog(null)
-      await sendBrowserRequest(method, {}, { suppressError: true, timeoutMs: 5_000 })
-    },
-    [sendBrowserRequest]
-  )
-
-  const setBrowserImageRef = useCallback((layer: FrameLayer, image: Image | null) => {
-    browserImageRefs.current[layer] = image
-    const currentFrameUri = frameUriRef.current
-    if (image && currentFrameUri) {
-      updateBrowserImageSource(image, currentFrameUri)
-    }
-  }, [])
-  const setBrowserLayerRef = useCallback((layer: FrameLayer, view: View | null) => {
-    browserLayerRefs.current[layer] = view
-    updateBrowserLayerVisibility(browserLayerRefs.current, visibleFrameLayerRef.current)
-  }, [])
-  const setBrowserLayer0Ref = useCallback(
-    (view: View | null) => setBrowserLayerRef(0, view),
-    [setBrowserLayerRef]
-  )
-  const setBrowserLayer1Ref = useCallback(
-    (view: View | null) => setBrowserLayerRef(1, view),
-    [setBrowserLayerRef]
-  )
-  const setBrowserImageLayer0Ref = useCallback(
-    (image: Image | null) => setBrowserImageRef(0, image),
-    [setBrowserImageRef]
-  )
-  const setBrowserImageLayer1Ref = useCallback(
-    (image: Image | null) => setBrowserImageRef(1, image),
-    [setBrowserImageRef]
-  )
-
-  const handleBrowserImageLoad = useCallback((layer: FrameLayer) => {
-    if (pendingFrameLayerRef.current !== layer) {
-      return
-    }
-    pendingFrameLayerRef.current = null
-    visibleFrameLayerRef.current = layer
-    updateBrowserLayerVisibility(browserLayerRefs.current, layer)
-  }, [])
-  const handleBrowserImageLayer0Load = useCallback(
-    () => handleBrowserImageLoad(0),
-    [handleBrowserImageLoad]
-  )
-  const handleBrowserImageLayer1Load = useCallback(
-    () => handleBrowserImageLoad(1),
-    [handleBrowserImageLoad]
-  )
-  const handleBrowserImageError = useCallback((layer: FrameLayer) => {
-    if (pendingFrameLayerRef.current === layer) {
-      pendingFrameLayerRef.current = null
-    }
-  }, [])
-  const handleBrowserImageLayer0Error = useCallback(
-    () => handleBrowserImageError(0),
-    [handleBrowserImageError]
-  )
-  const handleBrowserImageLayer1Error = useCallback(
-    () => handleBrowserImageError(1),
-    [handleBrowserImageError]
-  )
+  const {
+    browserLayerRef,
+    frameLayerErrorHandler,
+    frameLayerLoadHandler,
+    frameLayerRef,
+    frameLayerStyle
+  } = useMobileBrowserPaneLayers({
+    browserImageRefs,
+    browserLayerRefs,
+    frameUriRef,
+    pendingFrameLayerRef,
+    visibleFrameLayerRef
+  })
 
   const controlsDisabled = !client || !tab.browserPageId || screencastSupported !== true
   const goBack = useCallback(() => {
@@ -1016,6 +308,7 @@ export function MobileBrowserPane({
     }
     void sendBrowserRequest('browser.reload', {}, { suppressError: true })
   }, [controlsDisabled, sendBrowserRequest])
+
   const selectBrowserViewMode = useCallback(
     (mode: MobileBrowserViewMode) => {
       if (browserViewMode === mode) {
@@ -1028,241 +321,48 @@ export function MobileBrowserPane({
     },
     [browserViewMode, resetBrowserZoomState, tab.browserPageId, worktreeId]
   )
+
   const renderedFrameSource =
     frameUriRef.current || frameUri ? { uri: frameUriRef.current ?? frameUri! } : null
-  const frameLayerStyle = useCallback((layer: FrameLayer) => {
-    return [
-      styles.browserImageLayer,
-      visibleFrameLayerRef.current !== layer && styles.browserImageLayerHidden
-    ]
-  }, [])
-  const browserLayerRef = useCallback(
-    (layer: FrameLayer) => (layer === 0 ? setBrowserLayer0Ref : setBrowserLayer1Ref),
-    [setBrowserLayer0Ref, setBrowserLayer1Ref]
-  )
-  const frameLayerRef = useCallback(
-    (layer: FrameLayer) => (layer === 0 ? setBrowserImageLayer0Ref : setBrowserImageLayer1Ref),
-    [setBrowserImageLayer0Ref, setBrowserImageLayer1Ref]
-  )
-  const frameLayerLoadHandler = useCallback(
-    (layer: FrameLayer) =>
-      layer === 0 ? handleBrowserImageLayer0Load : handleBrowserImageLayer1Load,
-    [handleBrowserImageLayer0Load, handleBrowserImageLayer1Load]
-  )
-  const frameLayerErrorHandler = useCallback(
-    (layer: FrameLayer) =>
-      layer === 0 ? handleBrowserImageLayer0Error : handleBrowserImageLayer1Error,
-    [handleBrowserImageLayer0Error, handleBrowserImageLayer1Error]
-  )
 
   return (
-    <View ref={setRootViewRef} style={styles.root}>
-      <View style={styles.toolbar}>
-        <MobileBrowserToolbarIconButton
-          disabled={controlsDisabled || !tab.canGoBack}
-          label="Back"
-          onPress={goBack}
-        >
-          <ChevronLeft size={15} color={buttonColor(!controlsDisabled && tab.canGoBack)} />
-        </MobileBrowserToolbarIconButton>
-        <MobileBrowserToolbarIconButton
-          disabled={controlsDisabled || !tab.canGoForward}
-          label="Forward"
-          onPress={goForward}
-        >
-          <ChevronRight size={15} color={buttonColor(!controlsDisabled && tab.canGoForward)} />
-        </MobileBrowserToolbarIconButton>
-        <MobileBrowserToolbarIconButton
-          disabled={controlsDisabled}
-          label="Reload"
-          onPress={reloadPage}
-        >
-          <RefreshCw size={15} color={buttonColor(!controlsDisabled)} />
-        </MobileBrowserToolbarIconButton>
-        <MobileBrowserAddressField
-          value={addressValue}
-          onChangeText={setAddressValue}
-          onFocus={() => setAddressFocused(true)}
-          onBlur={() => setAddressFocused(false)}
-          onSubmit={() => void navigateToAddress()}
-          focused={addressFocused}
-          disabled={controlsDisabled}
-        />
-        <MobileBrowserViewModeSwitch
-          disabled={controlsDisabled}
-          value={browserViewMode}
-          onChange={selectBrowserViewMode}
-        />
-      </View>
-
-      <View
-        style={styles.viewport}
-        onLayout={(event) => {
-          const next = {
-            width: event.nativeEvent.layout.width,
-            height: event.nativeEvent.layout.height
-          }
-          const current = layoutRef.current
-          if (current && current.width === next.width && current.height === next.height) {
-            return
-          }
-          layoutRef.current = next
-          setLayout(next)
-        }}
-        {...panResponder.panHandlers}
-      >
-        {renderedFrameSource ? (
-          <View style={styles.browserImageHost}>
-            {frameGeometry ? (
-              <View
-                pointerEvents="none"
-                style={[
-                  styles.browserZoomOffset,
-                  {
-                    width: frameGeometry.renderedWidth,
-                    height: frameGeometry.renderedHeight,
-                    transform: [{ translateX: zoom.offsetX }, { translateY: zoom.offsetY }]
-                  }
-                ]}
-              >
-                <View
-                  style={[
-                    styles.browserFrameBox,
-                    {
-                      width: frameGeometry.renderedWidth,
-                      height: frameGeometry.renderedHeight,
-                      transform: [{ scale: zoom.scale }]
-                    }
-                  ]}
-                >
-                  {([0, 1] as const).map((layer) => (
-                    <View
-                      key={layer}
-                      ref={browserLayerRef(layer)}
-                      pointerEvents="none"
-                      style={frameLayerStyle(layer)}
-                    >
-                      <Image
-                        ref={frameLayerRef(layer)}
-                        source={renderedFrameSource}
-                        resizeMode="stretch"
-                        fadeDuration={0}
-                        onLoad={frameLayerLoadHandler(layer)}
-                        onError={frameLayerErrorHandler(layer)}
-                        style={[
-                          styles.browserImage,
-                          {
-                            width: frameGeometry.renderedWidth,
-                            height: frameGeometry.renderedHeight
-                          }
-                        ]}
-                      />
-                    </View>
-                  ))}
-                </View>
-              </View>
-            ) : (
-              ([0, 1] as const).map((layer) => (
-                <View
-                  key={layer}
-                  ref={browserLayerRef(layer)}
-                  pointerEvents="none"
-                  style={frameLayerStyle(layer)}
-                >
-                  <Image
-                    ref={frameLayerRef(layer)}
-                    source={renderedFrameSource}
-                    resizeMode="contain"
-                    fadeDuration={0}
-                    onLoad={frameLayerLoadHandler(layer)}
-                    onError={frameLayerErrorHandler(layer)}
-                    style={styles.browserImageFill}
-                  />
-                </View>
-              ))
-            )}
-          </View>
-        ) : null}
-        {!renderedFrameSource || busy || error ? (
-          <View pointerEvents="none" style={styles.overlay}>
-            {/* Why: a stream can report ready and then deliver no frames, so key the
-                indicator off actually having pixels or it clears into a blank pane. */}
-            {busy || (!renderedFrameSource && !error) ? (
-              <ActivityIndicator size="small" color={colors.textSecondary} />
-            ) : null}
-            {error ? <Text style={styles.errorText}>{error}</Text> : null}
-          </View>
-        ) : null}
-        {dialog ? (
-          <View style={styles.dialogOverlay}>
-            <View style={styles.dialogCard}>
-              <Text style={styles.dialogTitle}>Browser Dialog</Text>
-              <Text style={styles.dialogMessage}>{dialog.message}</Text>
-              <View style={styles.dialogActions}>
-                {dialog.dialogType !== 'alert' ? (
-                  <Pressable
-                    style={({ pressed }) => [
-                      styles.dialogButton,
-                      pressed && styles.dialogButtonPressed
-                    ]}
-                    onPress={() => void sendDialogCommand('browser.dialogDismiss')}
-                  >
-                    <Text style={styles.dialogButtonText}>Cancel</Text>
-                  </Pressable>
-                ) : null}
-                <Pressable
-                  style={({ pressed }) => [
-                    styles.dialogButton,
-                    styles.dialogButtonPrimary,
-                    pressed && styles.dialogButtonPressed
-                  ]}
-                  onPress={() => void sendDialogCommand('browser.dialogAccept')}
-                >
-                  <Text style={[styles.dialogButtonText, styles.dialogButtonPrimaryText]}>OK</Text>
-                </Pressable>
-              </View>
-            </View>
-          </View>
-        ) : null}
-      </View>
-
-      <View
-        style={[
-          styles.keyboardDock,
-          { paddingBottom: bottomInset, transform: [{ translateY: -keyboardLift }] }
-        ]}
-      >
-        <MobileBrowserPointerModifiers
-          disabled={controlsDisabled}
-          selectedModifiers={pointerModifiers}
-          onToggle={togglePointerModifier}
-        />
-        <MobileBrowserKeyRow
-          disabled={controlsDisabled}
-          onKeypress={(key) => void sendKeypress(key)}
-        />
-        <View style={styles.inputRow}>
-          <TextInput
-            style={styles.keyboardInput}
-            value={keyboardValue}
-            onChangeText={setKeyboardValue}
-            placeholder="Type on page…"
-            placeholderTextColor={colors.textMuted}
-            autoCapitalize="none"
-            autoCorrect={false}
-            editable={!controlsDisabled}
-            onSubmitEditing={() => void sendKeyboardText()}
-          />
-          <Pressable
-            style={[styles.sendButton, (controlsDisabled || !keyboardValue) && styles.disabled]}
-            disabled={controlsDisabled || !keyboardValue}
-            onPress={() => void sendKeyboardText()}
-            accessibilityLabel="Send text to browser"
-          >
-            <ArrowUp size={18} color={buttonColor(!controlsDisabled && !!keyboardValue)} />
-          </Pressable>
-        </View>
-      </View>
-    </View>
+    <MobileBrowserPaneView
+      addressFocused={addressFocused}
+      addressValue={addressValue}
+      bottomInset={bottomInset}
+      browserLayerRef={browserLayerRef}
+      browserViewMode={browserViewMode}
+      busy={busy}
+      controlsDisabled={controlsDisabled}
+      dialog={dialog}
+      error={error}
+      frameGeometry={frameGeometry}
+      frameLayerErrorHandler={frameLayerErrorHandler}
+      frameLayerLoadHandler={frameLayerLoadHandler}
+      frameLayerRef={frameLayerRef}
+      frameLayerStyle={frameLayerStyle}
+      goBack={goBack}
+      goForward={goForward}
+      keyboardLift={keyboardLift}
+      keyboardValue={keyboardValue}
+      layoutRef={layoutRef}
+      navigateToAddress={navigateToAddress}
+      panResponder={panResponder}
+      pointerModifiers={pointerModifiers}
+      reloadPage={reloadPage}
+      renderedFrameSource={renderedFrameSource}
+      selectBrowserViewMode={selectBrowserViewMode}
+      sendDialogCommand={sendDialogCommand}
+      sendKeyboardText={sendKeyboardText}
+      sendKeypress={sendKeypress}
+      setAddressFocused={setAddressFocused}
+      setAddressValue={setAddressValue}
+      setKeyboardValue={setKeyboardValue}
+      setLayout={setLayout}
+      setRootViewRef={setRootViewRef}
+      tab={tab}
+      togglePointerModifier={togglePointerModifier}
+      zoom={zoom}
+    />
   )
 }
diff --git a/mobile/src/browser/MobileBrowserPaneView.tsx b/mobile/src/browser/MobileBrowserPaneView.tsx
new file mode 100644
index 00000000000..e36e7044837
--- /dev/null
+++ b/mobile/src/browser/MobileBrowserPaneView.tsx
@@ -0,0 +1,321 @@
+import type { Dispatch, RefObject, SetStateAction } from 'react'
+import {
+  ActivityIndicator,
+  Image,
+  Pressable,
+  Text,
+  TextInput,
+  View,
+  type PanResponderInstance,
+  type StyleProp,
+  type ViewStyle
+} from 'react-native'
+import { ArrowUp, ChevronLeft, ChevronRight, RefreshCw } from 'lucide-react-native'
+import { colors } from '../theme/mobile-theme'
+import { MobileBrowserAddressField } from './MobileBrowserAddressField'
+import { MobileBrowserKeyRow } from './MobileBrowserKeyRow'
+import {
+  MobileBrowserPointerModifiers,
+  type BrowserPointerModifier
+} from './MobileBrowserPointerModifiers'
+import { MobileBrowserToolbarIconButton } from './MobileBrowserToolbarIconButton'
+import { MobileBrowserViewModeSwitch } from './MobileBrowserViewModeSwitch'
+import { buttonColor, type FrameLayer } from './mobile-browser-frame-state'
+import { mobileBrowserPaneStyles as styles } from './mobile-browser-pane-styles'
+import type {
+  BrowserFrameGeometry,
+  BrowserTouchLayout,
+  BrowserZoomState
+} from './browser-touch-geometry'
+import type { MobileBrowserViewMode } from './browser-screencast-request'
+import type { MobileBrowserTab } from './MobileBrowserPane'
+
+type MobileBrowserPaneViewProps = {
+  addressFocused: boolean
+  addressValue: string
+  bottomInset: number
+  browserLayerRef: (layer: FrameLayer) => (view: View | null) => void
+  browserViewMode: MobileBrowserViewMode
+  busy: boolean
+  controlsDisabled: boolean
+  dialog: { dialogType: string; message: string } | null
+  error: string | null
+  frameGeometry: BrowserFrameGeometry | null
+  frameLayerErrorHandler: (layer: FrameLayer) => () => void
+  frameLayerLoadHandler: (layer: FrameLayer) => () => void
+  frameLayerRef: (layer: FrameLayer) => (image: Image | null) => void
+  frameLayerStyle: (layer: FrameLayer) => StyleProp<ViewStyle>
+  goBack: () => void
+  goForward: () => void
+  keyboardLift: number
+  keyboardValue: string
+  layoutRef: RefObject<BrowserTouchLayout | null>
+  navigateToAddress: () => Promise<void>
+  panResponder: PanResponderInstance
+  pointerModifiers: BrowserPointerModifier[]
+  reloadPage: () => void
+  renderedFrameSource: { uri: string } | null
+  selectBrowserViewMode: (mode: MobileBrowserViewMode) => void
+  sendDialogCommand: (method: 'browser.dialogDismiss' | 'browser.dialogAccept') => Promise<void>
+  sendKeyboardText: () => Promise<void>
+  sendKeypress: (key: string) => Promise<void>
+  setAddressFocused: Dispatch<SetStateAction<boolean>>
+  setAddressValue: Dispatch<SetStateAction<string>>
+  setKeyboardValue: Dispatch<SetStateAction<string>>
+  setLayout: Dispatch<SetStateAction<BrowserTouchLayout | null>>
+  setRootViewRef: (view: View | null) => void
+  tab: MobileBrowserTab
+  togglePointerModifier: (modifier: BrowserPointerModifier) => void
+  zoom: BrowserZoomState
+}
+
+export function MobileBrowserPaneView(props: MobileBrowserPaneViewProps) {
+  const {
+    addressFocused,
+    addressValue,
+    bottomInset,
+    browserLayerRef,
+    browserViewMode,
+    busy,
+    controlsDisabled,
+    dialog,
+    error,
+    frameGeometry,
+    frameLayerErrorHandler,
+    frameLayerLoadHandler,
+    frameLayerRef,
+    frameLayerStyle,
+    goBack,
+    goForward,
+    keyboardLift,
+    keyboardValue,
+    layoutRef,
+    navigateToAddress,
+    panResponder,
+    pointerModifiers,
+    reloadPage,
+    renderedFrameSource,
+    selectBrowserViewMode,
+    sendDialogCommand,
+    sendKeyboardText,
+    sendKeypress,
+    setAddressFocused,
+    setAddressValue,
+    setKeyboardValue,
+    setLayout,
+    setRootViewRef,
+    tab,
+    togglePointerModifier,
+    zoom
+  } = props
+  return (
+    <View ref={setRootViewRef} style={styles.root}>
+      <View style={styles.toolbar}>
+        <MobileBrowserToolbarIconButton
+          disabled={controlsDisabled || !tab.canGoBack}
+          label="Back"
+          onPress={goBack}
+        >
+          <ChevronLeft size={15} color={buttonColor(!controlsDisabled && tab.canGoBack)} />
+        </MobileBrowserToolbarIconButton>
+        <MobileBrowserToolbarIconButton
+          disabled={controlsDisabled || !tab.canGoForward}
+          label="Forward"
+          onPress={goForward}
+        >
+          <ChevronRight size={15} color={buttonColor(!controlsDisabled && tab.canGoForward)} />
+        </MobileBrowserToolbarIconButton>
+        <MobileBrowserToolbarIconButton
+          disabled={controlsDisabled}
+          label="Reload"
+          onPress={reloadPage}
+        >
+          <RefreshCw size={15} color={buttonColor(!controlsDisabled)} />
+        </MobileBrowserToolbarIconButton>
+        <MobileBrowserAddressField
+          value={addressValue}
+          onChangeText={setAddressValue}
+          onFocus={() => setAddressFocused(true)}
+          onBlur={() => setAddressFocused(false)}
+          onSubmit={() => void navigateToAddress()}
+          focused={addressFocused}
+          disabled={controlsDisabled}
+        />
+        <MobileBrowserViewModeSwitch
+          disabled={controlsDisabled}
+          value={browserViewMode}
+          onChange={selectBrowserViewMode}
+        />
+      </View>
+
+      <View
+        style={styles.viewport}
+        onLayout={(event) => {
+          const next = {
+            width: event.nativeEvent.layout.width,
+            height: event.nativeEvent.layout.height
+          }
+          const current = layoutRef.current
+          if (current && current.width === next.width && current.height === next.height) {
+            return
+          }
+          layoutRef.current = next
+          setLayout(next)
+        }}
+        {...panResponder.panHandlers}
+      >
+        {renderedFrameSource ? (
+          <View style={styles.browserImageHost}>
+            {frameGeometry ? (
+              <View
+                pointerEvents="none"
+                style={[
+                  styles.browserZoomOffset,
+                  {
+                    width: frameGeometry.renderedWidth,
+                    height: frameGeometry.renderedHeight,
+                    transform: [{ translateX: zoom.offsetX }, { translateY: zoom.offsetY }]
+                  }
+                ]}
+              >
+                <View
+                  style={[
+                    styles.browserFrameBox,
+                    {
+                      width: frameGeometry.renderedWidth,
+                      height: frameGeometry.renderedHeight,
+                      transform: [{ scale: zoom.scale }]
+                    }
+                  ]}
+                >
+                  {([0, 1] as const).map((layer) => (
+                    <View
+                      key={layer}
+                      ref={browserLayerRef(layer)}
+                      pointerEvents="none"
+                      style={frameLayerStyle(layer)}
+                    >
+                      <Image
+                        ref={frameLayerRef(layer)}
+                        source={renderedFrameSource}
+                        resizeMode="stretch"
+                        fadeDuration={0}
+                        onLoad={frameLayerLoadHandler(layer)}
+                        onError={frameLayerErrorHandler(layer)}
+                        style={[
+                          styles.browserImage,
+                          {
+                            width: frameGeometry.renderedWidth,
+                            height: frameGeometry.renderedHeight
+                          }
+                        ]}
+                      />
+                    </View>
+                  ))}
+                </View>
+              </View>
+            ) : (
+              ([0, 1] as const).map((layer) => (
+                <View
+                  key={layer}
+                  ref={browserLayerRef(layer)}
+                  pointerEvents="none"
+                  style={frameLayerStyle(layer)}
+                >
+                  <Image
+                    ref={frameLayerRef(layer)}
+                    source={renderedFrameSource}
+                    resizeMode="contain"
+                    fadeDuration={0}
+                    onLoad={frameLayerLoadHandler(layer)}
+                    onError={frameLayerErrorHandler(layer)}
+                    style={styles.browserImageFill}
+                  />
+                </View>
+              ))
+            )}
+          </View>
+        ) : null}
+        {!renderedFrameSource || busy || error ? (
+          <View pointerEvents="none" style={styles.overlay}>
+            {/* Why: a stream can report ready and then deliver no frames, so key the
+                indicator off actually having pixels or it clears into a blank pane. */}
+            {busy || (!renderedFrameSource && !error) ? (
+              <ActivityIndicator size="small" color={colors.textSecondary} />
+            ) : null}
+            {error ? <Text style={styles.errorText}>{error}</Text> : null}
+          </View>
+        ) : null}
+        {dialog ? (
+          <View style={styles.dialogOverlay}>
+            <View style={styles.dialogCard}>
+              <Text style={styles.dialogTitle}>Browser Dialog</Text>
+              <Text style={styles.dialogMessage}>{dialog.message}</Text>
+              <View style={styles.dialogActions}>
+                {dialog.dialogType !== 'alert' ? (
+                  <Pressable
+                    style={({ pressed }) => [
+                      styles.dialogButton,
+                      pressed && styles.dialogButtonPressed
+                    ]}
+                    onPress={() => void sendDialogCommand('browser.dialogDismiss')}
+                  >
+                    <Text style={styles.dialogButtonText}>Cancel</Text>
+                  </Pressable>
+                ) : null}
+                <Pressable
+                  style={({ pressed }) => [
+                    styles.dialogButton,
+                    styles.dialogButtonPrimary,
+                    pressed && styles.dialogButtonPressed
+                  ]}
+                  onPress={() => void sendDialogCommand('browser.dialogAccept')}
+                >
+                  <Text style={[styles.dialogButtonText, styles.dialogButtonPrimaryText]}>OK</Text>
+                </Pressable>
+              </View>
+            </View>
+          </View>
+        ) : null}
+      </View>
+
+      <View
+        style={[
+          styles.keyboardDock,
+          { paddingBottom: bottomInset, transform: [{ translateY: -keyboardLift }] }
+        ]}
+      >
+        <MobileBrowserPointerModifiers
+          disabled={controlsDisabled}
+          selectedModifiers={pointerModifiers}
+          onToggle={togglePointerModifier}
+        />
+        <MobileBrowserKeyRow
+          disabled={controlsDisabled}
+          onKeypress={(key) => void sendKeypress(key)}
+        />
+        <View style={styles.inputRow}>
+          <TextInput
+            style={styles.keyboardInput}
+            value={keyboardValue}
+            onChangeText={setKeyboardValue}
+            placeholder="Type on page…"
+            placeholderTextColor={colors.textMuted}
+            autoCapitalize="none"
+            autoCorrect={false}
+            editable={!controlsDisabled}
+            onSubmitEditing={() => void sendKeyboardText()}
+          />
+          <Pressable
+            style={[styles.sendButton, (controlsDisabled || !keyboardValue) && styles.disabled]}
+            disabled={controlsDisabled || !keyboardValue}
+            onPress={() => void sendKeyboardText()}
+            accessibilityLabel="Send text to browser"
+          >
+            <ArrowUp size={18} color={buttonColor(!controlsDisabled && !!keyboardValue)} />
+          </Pressable>
+        </View>
+      </View>
+    </View>
+  )
+}
diff --git a/mobile/src/browser/mobile-browser-stream-events.ts b/mobile/src/browser/mobile-browser-stream-events.ts
new file mode 100644
index 00000000000..5b65b2987f6
--- /dev/null
+++ b/mobile/src/browser/mobile-browser-stream-events.ts
@@ -0,0 +1,77 @@
+import type { Dispatch, SetStateAction } from 'react'
+import { displayBrowserUrl } from './browser-url'
+import { shouldSurfaceBrowserError } from './mobile-browser-frame-state'
+
+export type BrowserDialogState = { dialogType: string; message: string }
+
+export type ScreencastEvent = {
+  type?: string
+  message?: string
+  error?: { message?: string }
+  dialogType?: string
+  tab?: { url?: string; title?: string; canGoBack?: boolean; canGoForward?: boolean }
+}
+
+type HandleScreencastEventArgs = {
+  busyRef: { current: boolean }
+  clearStartupTimer: () => void
+  event: ScreencastEvent
+  lastZoomResetUrlRef: { current: string }
+  resetBrowserZoomState: () => void
+  setAddressValue: Dispatch<SetStateAction<string>>
+  setBusy: Dispatch<SetStateAction<boolean>>
+  setDialog: Dispatch<SetStateAction<BrowserDialogState | null>>
+  setError: Dispatch<SetStateAction<string | null>>
+}
+
+export function handleBrowserScreencastEvent(args: HandleScreencastEventArgs): void {
+  const {
+    busyRef,
+    clearStartupTimer,
+    event,
+    lastZoomResetUrlRef,
+    resetBrowserZoomState,
+    setAddressValue,
+    setBusy,
+    setDialog,
+    setError
+  } = args
+
+  if (event.type === 'ready') {
+    clearStartupTimer()
+    if (busyRef.current) {
+      busyRef.current = false
+      setBusy(false)
+    }
+    if (typeof event.tab?.url === 'string') {
+      setAddressValue(displayBrowserUrl(event.tab.url))
+      if (event.tab.url !== lastZoomResetUrlRef.current) {
+        lastZoomResetUrlRef.current = event.tab.url
+        resetBrowserZoomState()
+      }
+    }
+  } else if (event.type === 'end') {
+    clearStartupTimer()
+    if (busyRef.current) {
+      busyRef.current = false
+      setBusy(false)
+    }
+  } else if (event.type === 'dialog') {
+    setDialog({
+      dialogType: event.dialogType ?? 'alert',
+      message: event.message ?? 'Browser dialog'
+    })
+  } else if (event.type === 'dialogClosed') {
+    setDialog(null)
+  } else if (event.type === 'error') {
+    clearStartupTimer()
+    if (busyRef.current) {
+      busyRef.current = false
+      setBusy(false)
+    }
+    const message = event.message ?? event.error?.message ?? 'Browser stream failed.'
+    if (shouldSurfaceBrowserError(message)) {
+      setError(message)
+    }
+  }
+}
diff --git a/mobile/src/browser/use-mobile-browser-commands.ts b/mobile/src/browser/use-mobile-browser-commands.ts
new file mode 100644
index 00000000000..30554d4db5f
--- /dev/null
+++ b/mobile/src/browser/use-mobile-browser-commands.ts
@@ -0,0 +1,248 @@
+import { useCallback, useRef, type Dispatch, type SetStateAction } from 'react'
+import type { RpcClient } from '../transport/rpc-client'
+import type { BrowserScreencastFrameMetadata } from '../transport/browser-screencast-protocol'
+import { assertRpcOk } from './mobile-browser-frame-state'
+import {
+  computeBrowserFrameGeometry,
+  computeBrowserTouchClickRadiusCss,
+  mapScreenToBrowserPoint,
+  type BrowserPoint,
+  type BrowserTouchLayout,
+  type BrowserZoomState
+} from './browser-touch-geometry'
+import type { BrowserPointerModifier } from './MobileBrowserPointerModifiers'
+
+const TOUCH_CLICK_RADIUS_DIP = 14
+type BrowserPageParams = { worktree: string; page: string }
+type PendingWheelCommand = {
+  base: BrowserPageParams
+  point: BrowserPoint
+  gestureId: number
+  dx: number
+  dy: number
+}
+type SendBrowserRequest = (
+  method: string,
+  params?: Record<string, unknown>,
+  options?: { showBusy?: boolean; suppressError?: boolean; timeoutMs?: number }
+) => Promise<unknown | null>
+
+type MobileBrowserCommandArgs = {
+  client: RpcClient | null
+  frameMetadataRef: { current: BrowserScreencastFrameMetadata | null }
+  keyboardValue: string
+  layoutRef: { current: BrowserTouchLayout | null }
+  onToast: (message: string, durationMs?: number) => void
+  pageParams: () => BrowserPageParams | null
+  pointerModifiers: BrowserPointerModifier[]
+  sendBrowserRequest: SendBrowserRequest
+  setDialog: Dispatch<SetStateAction<{ dialogType: string; message: string } | null>>
+  setError: Dispatch<SetStateAction<string | null>>
+  setKeyboardValue: Dispatch<SetStateAction<string>>
+  setPointerModifiers: Dispatch<SetStateAction<BrowserPointerModifier[]>>
+  zoomRef: { current: BrowserZoomState }
+}
+
+export function useMobileBrowserCommands(args: MobileBrowserCommandArgs) {
+  const {
+    client,
+    frameMetadataRef,
+    keyboardValue,
+    layoutRef,
+    onToast,
+    pageParams,
+    pointerModifiers,
+    sendBrowserRequest,
+    setDialog,
+    setError,
+    setKeyboardValue,
+    setPointerModifiers,
+    zoomRef
+  } = args
+
+  const pendingWheelCommandRef = useRef<PendingWheelCommand | null>(null)
+
+  const wheelCommandInFlightRef = useRef(false)
+
+  const flushPendingWheelCommand = useCallback(() => {
+    if (wheelCommandInFlightRef.current) {
+      return
+    }
+    const pending = pendingWheelCommandRef.current
+    if (!pending || !client) {
+      return
+    }
+    pendingWheelCommandRef.current = null
+    wheelCommandInFlightRef.current = true
+    void (async () => {
+      try {
+        assertRpcOk(
+          await client.sendRequest('browser.mouseMove', {
+            ...pending.base,
+            x: pending.point.x,
+            y: pending.point.y
+          }),
+          'Browser pointer move failed'
+        )
+        assertRpcOk(
+          await client.sendRequest('browser.mouseWheel', {
+            ...pending.base,
+            dx: pending.dx,
+            dy: pending.dy
+          }),
+          'Browser scroll failed'
+        )
+        setError(null)
+      } catch {
+        // Scroll bursts commonly race page reload/navigation. Avoid replacing
+        // the live browser with transient command errors like selector_not_found.
+      } finally {
+        wheelCommandInFlightRef.current = false
+        flushPendingWheelCommand()
+      }
+    })()
+  }, [client])
+
+  const sendPointerClick = useCallback(
+    async (point: BrowserPoint, button: 'left' | 'right') => {
+      const base = pageParams()
+      if (!client || !base) {
+        return
+      }
+      const clickResult = await sendBrowserRequest(
+        'browser.mouseClick',
+        {
+          x: point.x,
+          y: point.y,
+          button,
+          modifiers: pointerModifiers,
+          ...(button === 'left'
+            ? {
+                radius: computeBrowserTouchClickRadiusCss(
+                  layoutRef.current,
+                  frameMetadataRef.current,
+                  zoomRef.current,
+                  TOUCH_CLICK_RADIUS_DIP
+                )
+              }
+            : {})
+        },
+        { suppressError: true, timeoutMs: 5_000 }
+      )
+      if (clickResult !== null || pointerModifiers.length > 0) {
+        return
+      }
+      try {
+        assertRpcOk(
+          await client.sendRequest('browser.mouseMove', { ...base, x: point.x, y: point.y }),
+          'Browser pointer move failed'
+        )
+        assertRpcOk(
+          await client.sendRequest('browser.mouseDown', { ...base, button }),
+          'Browser pointer down failed'
+        )
+        assertRpcOk(
+          await client.sendRequest('browser.mouseUp', { ...base, button }),
+          'Browser pointer up failed'
+        )
+        setError(null)
+      } catch {
+        // Pointer commands can race page navigation. Keep the stream visible;
+        // actionable failures still surface through navigation/stream errors.
+      }
+    },
+    [client, pageParams, pointerModifiers, sendBrowserRequest]
+  )
+
+  const togglePointerModifier = useCallback((modifier: BrowserPointerModifier) => {
+    setPointerModifiers((current) =>
+      current.includes(modifier)
+        ? current.filter((candidate) => candidate !== modifier)
+        : [...current, modifier]
+    )
+  }, [])
+
+  const sendWheel = useCallback(
+    (point: BrowserPoint, screenDx: number, screenDy: number, gestureId: number) => {
+      const base = pageParams()
+      if (!client || !base) {
+        return
+      }
+      const currentLayout = layoutRef.current
+      const geometry = computeBrowserFrameGeometry(currentLayout, frameMetadataRef.current)
+      const localZoom = zoomRef.current.scale
+      const scale = (geometry?.scale ?? 1) * localZoom
+      const cssDx = screenDx / scale
+      const cssDy = screenDy / scale
+      const delta = { dx: Math.round(-cssDx), dy: Math.round(-cssDy) }
+      if (Math.abs(delta.dx) < 1 && Math.abs(delta.dy) < 1) {
+        return
+      }
+      const pending = pendingWheelCommandRef.current
+      pendingWheelCommandRef.current =
+        pending && pending.base.page === base.page && pending.gestureId === gestureId
+          ? {
+              base,
+              point,
+              gestureId,
+              dx: pending.dx + delta.dx,
+              dy: pending.dy + delta.dy
+            }
+          : { base, point, gestureId, ...delta }
+      flushPendingWheelCommand()
+    },
+    [client, flushPendingWheelCommand, pageParams]
+  )
+
+  const mapTouchPoint = useCallback((locationX: number, locationY: number): BrowserPoint | null => {
+    return mapScreenToBrowserPoint(
+      locationX,
+      locationY,
+      layoutRef.current,
+      frameMetadataRef.current,
+      zoomRef.current
+    )
+  }, [])
+
+  const sendKeyboardText = useCallback(async () => {
+    const text = keyboardValue
+    if (!text) {
+      return
+    }
+    setKeyboardValue('')
+    const result = await sendBrowserRequest(
+      'browser.keyboardInsertText',
+      { text },
+      { suppressError: true }
+    )
+    if (result !== null) {
+      onToast('Sent')
+    } else {
+      setKeyboardValue(text)
+    }
+  }, [keyboardValue, onToast, sendBrowserRequest])
+
+  const sendKeypress = useCallback(
+    async (key: string) => {
+      await sendBrowserRequest('browser.keypress', { key }, { suppressError: true })
+    },
+    [sendBrowserRequest]
+  )
+
+  const sendDialogCommand = useCallback(
+    async (method: 'browser.dialogAccept' | 'browser.dialogDismiss') => {
+      setDialog(null)
+      await sendBrowserRequest(method, {}, { suppressError: true, timeoutMs: 5_000 })
+    },
+    [sendBrowserRequest]
+  )
+  return {
+    mapTouchPoint,
+    sendDialogCommand,
+    sendKeyboardText,
+    sendKeypress,
+    sendPointerClick,
+    sendWheel,
+    togglePointerModifier
+  }
+}
diff --git a/mobile/src/browser/use-mobile-browser-frame-apply.ts b/mobile/src/browser/use-mobile-browser-frame-apply.ts
new file mode 100644
index 00000000000..8634edbc924
--- /dev/null
+++ b/mobile/src/browser/use-mobile-browser-frame-apply.ts
@@ -0,0 +1,122 @@
+import { useCallback, type Dispatch, type SetStateAction } from 'react'
+import type { Image } from 'react-native'
+import type {
+  BrowserScreencastFrame,
+  BrowserScreencastFrameMetadata
+} from '../transport/browser-screencast-protocol'
+import { MOBILE_BROWSER_FRAME_MIN_INTERVAL_MS } from './browser-screencast-request'
+import {
+  browserFrameMetadataEqual,
+  cacheBrowserFrame,
+  createBrowserFrameDataUri,
+  updateBrowserImageSource,
+  type FrameLayer
+} from './mobile-browser-frame-state'
+
+type PendingFrame = { frame: BrowserScreencastFrame; cacheKey: string }
+type BrowserFrameApplyArgs = {
+  browserImageRefs: { current: [Image | null, Image | null] }
+  busyRef: { current: boolean }
+  frameMetadataRef: { current: BrowserScreencastFrameMetadata | null }
+  frameMountedRef: { current: boolean }
+  frameThrottleTimerRef: { current: ReturnType<typeof setTimeout> | null }
+  frameUriRef: { current: string | null }
+  lastAppliedFrameAtRef: { current: number }
+  pendingFrameLayerRef: { current: FrameLayer | null }
+  pendingThrottledFrameRef: { current: PendingFrame | null }
+  setBusy: Dispatch<SetStateAction<boolean>>
+  setFrameMetadata: Dispatch<SetStateAction<BrowserScreencastFrameMetadata | null>>
+  setFrameUri: Dispatch<SetStateAction<string | null>>
+  visibleFrameLayerRef: { current: FrameLayer }
+}
+export function useMobileBrowserFrameApply(args: BrowserFrameApplyArgs) {
+  const {
+    browserImageRefs,
+    busyRef,
+    frameMetadataRef,
+    frameMountedRef,
+    frameThrottleTimerRef,
+    frameUriRef,
+    lastAppliedFrameAtRef,
+    pendingFrameLayerRef,
+    pendingThrottledFrameRef,
+    setBusy,
+    setFrameMetadata,
+    setFrameUri,
+    visibleFrameLayerRef
+  } = args
+  const applyFrame = useCallback((frame: BrowserScreencastFrame, frameCacheKey: string): void => {
+    if (!browserFrameMetadataEqual(frameMetadataRef.current, frame.metadata)) {
+      frameMetadataRef.current = frame.metadata
+      setFrameMetadata(frame.metadata)
+    }
+    const nextFrameUri = createBrowserFrameDataUri(frame)
+    cacheBrowserFrame(frameCacheKey, { uri: nextFrameUri, metadata: frame.metadata })
+    if (!frameMountedRef.current) {
+      frameUriRef.current = nextFrameUri
+      frameMountedRef.current = true
+      setFrameUri(nextFrameUri)
+      updateBrowserImageSource(browserImageRefs.current[0], nextFrameUri)
+    } else if (pendingFrameLayerRef.current === null) {
+      // Why: decode the next frame offscreen and keep the previous layer visible
+      // until onLoad; replacing the visible Image directly flashes black.
+      const nextLayer: FrameLayer = visibleFrameLayerRef.current === 0 ? 1 : 0
+      frameUriRef.current = nextFrameUri
+      pendingFrameLayerRef.current = nextLayer
+      updateBrowserImageSource(browserImageRefs.current[nextLayer], nextFrameUri)
+    } else {
+      // Why: popovers/menus can settle in one final frame while the previous
+      // offscreen frame is still decoding. Keep the hidden layer pointed at
+      // the newest frame instead of dropping the final static state.
+      frameUriRef.current = nextFrameUri
+      updateBrowserImageSource(browserImageRefs.current[pendingFrameLayerRef.current], nextFrameUri)
+    }
+    if (busyRef.current) {
+      busyRef.current = false
+      setBusy(false)
+    }
+  }, [])
+
+  const clearFrameThrottle = useCallback(() => {
+    pendingThrottledFrameRef.current = null
+    if (frameThrottleTimerRef.current) {
+      clearTimeout(frameThrottleTimerRef.current)
+      frameThrottleTimerRef.current = null
+    }
+  }, [])
+
+  const applyFrameThrottled = useCallback(
+    (frame: BrowserScreencastFrame, frameCacheKey: string): void => {
+      const now = Date.now()
+      const elapsed = now - lastAppliedFrameAtRef.current
+      if (lastAppliedFrameAtRef.current === 0 || elapsed >= MOBILE_BROWSER_FRAME_MIN_INTERVAL_MS) {
+        clearFrameThrottle()
+        lastAppliedFrameAtRef.current = now
+        applyFrame(frame, frameCacheKey)
+        return
+      }
+
+      // Why: static UI changes can be the last frame Chromium emits. Coalesce
+      // throttled frames so the final visible state is applied after the delay.
+      pendingThrottledFrameRef.current = { frame, cacheKey: frameCacheKey }
+      if (frameThrottleTimerRef.current) {
+        return
+      }
+      frameThrottleTimerRef.current = setTimeout(
+        () => {
+          frameThrottleTimerRef.current = null
+          const pending = pendingThrottledFrameRef.current
+          pendingThrottledFrameRef.current = null
+          if (!pending) {
+            return
+          }
+          lastAppliedFrameAtRef.current = Date.now()
+          applyFrame(pending.frame, pending.cacheKey)
+        },
+        Math.max(0, MOBILE_BROWSER_FRAME_MIN_INTERVAL_MS - elapsed)
+      )
+    },
+    [applyFrame, clearFrameThrottle]
+  )
+  return { applyFrameThrottled, clearFrameThrottle }
+}
diff --git a/mobile/src/browser/use-mobile-browser-interactions.ts b/mobile/src/browser/use-mobile-browser-interactions.ts
new file mode 100644
index 00000000000..519ad45ab3b
--- /dev/null
+++ b/mobile/src/browser/use-mobile-browser-interactions.ts
@@ -0,0 +1,290 @@
+import { useCallback, useMemo, useRef, type Dispatch, type SetStateAction } from 'react'
+import {
+  PanResponder,
+  type GestureResponderEvent,
+  type PanResponderGestureState
+} from 'react-native'
+import type { RpcClient } from '../transport/rpc-client'
+import {
+  createPinchGesture,
+  MAX_ZOOM,
+  MIN_ZOOM,
+  updatePinchZoom,
+  type PinchGesture
+} from './mobile-browser-frame-state'
+import {
+  clampBrowserZoomState,
+  readLocalTouchPoint,
+  type BrowserFrameGeometry,
+  type BrowserTouchLayout,
+  type BrowserZoomState
+} from './browser-touch-geometry'
+import type { BrowserPointerModifier } from './MobileBrowserPointerModifiers'
+import type { BrowserScreencastFrameMetadata } from '../transport/browser-screencast-protocol'
+
+import { useMobileBrowserCommands } from './use-mobile-browser-commands'
+const TAP_SLOP = 16
+const SCROLL_START_SLOP = 22
+const LONG_PRESS_MS = 550
+const WHEEL_INTERVAL_MS = 70
+
+type BrowserPageParams = { worktree: string; page: string }
+type PanGesture = { x: number; y: number; offsetX: number; offsetY: number }
+type SendBrowserRequest = (
+  method: string,
+  params?: Record<string, unknown>,
+  options?: { showBusy?: boolean; suppressError?: boolean; timeoutMs?: number }
+) => Promise<unknown | null>
+
+type MobileBrowserInteractionArgs = {
+  clearLongPressTimer: () => void
+  client: RpcClient | null
+  dialogRef: { current: { dialogType: string; message: string } | null }
+  frameGeometry: BrowserFrameGeometry | null
+  frameMetadataRef: { current: BrowserScreencastFrameMetadata | null }
+  keyboardValue: string
+  layoutRef: { current: BrowserTouchLayout | null }
+  longPressTimerRef: { current: ReturnType<typeof setTimeout> | null }
+  onToast: (message: string, durationMs?: number) => void
+  pageParams: () => BrowserPageParams | null
+  panRef: { current: PanGesture | null }
+  pinchRef: { current: PinchGesture | null }
+  pointerModifiers: BrowserPointerModifier[]
+  sendBrowserRequest: SendBrowserRequest
+  setDialog: Dispatch<SetStateAction<{ dialogType: string; message: string } | null>>
+  setError: Dispatch<SetStateAction<string | null>>
+  setKeyboardValue: Dispatch<SetStateAction<string>>
+  scrollingRef: { current: boolean }
+  startPointRef: { current: { x: number; y: number; t: number } | null }
+  setPointerModifiers: Dispatch<SetStateAction<BrowserPointerModifier[]>>
+  setZoom: Dispatch<SetStateAction<BrowserZoomState>>
+  zoomRef: { current: BrowserZoomState }
+}
+
+export function useMobileBrowserInteractions(args: MobileBrowserInteractionArgs) {
+  const {
+    clearLongPressTimer,
+    client,
+    dialogRef,
+    frameGeometry,
+    frameMetadataRef,
+    keyboardValue,
+    layoutRef,
+    longPressTimerRef,
+    onToast,
+    pageParams,
+    panRef,
+    pinchRef,
+    pointerModifiers,
+    scrollingRef,
+    sendBrowserRequest,
+    setDialog,
+    setError,
+    setKeyboardValue,
+    setPointerModifiers,
+    setZoom,
+    startPointRef,
+    zoomRef
+  } = args
+  const rightClickSentRef = useRef(false)
+  const lastWheelRef = useRef({ dx: 0, dy: 0, at: 0 })
+  const wheelGestureIdRef = useRef(0)
+  const {
+    mapTouchPoint,
+    sendDialogCommand,
+    sendKeyboardText,
+    sendKeypress,
+    sendPointerClick,
+    sendWheel,
+    togglePointerModifier
+  } = useMobileBrowserCommands({
+    client,
+    frameMetadataRef,
+    keyboardValue,
+    layoutRef,
+    onToast,
+    pageParams,
+    pointerModifiers,
+    sendBrowserRequest,
+    setDialog,
+    setError,
+    setKeyboardValue,
+    setPointerModifiers,
+    zoomRef
+  })
+
+  const handleResponderGrant = useCallback(
+    (event: GestureResponderEvent) => {
+      const pinch = createPinchGesture(event, frameGeometry, zoomRef.current)
+      if (pinch) {
+        clearLongPressTimer()
+        pinchRef.current = pinch
+        panRef.current = null
+        startPointRef.current = null
+        return
+      }
+      const startPoint = readLocalTouchPoint(event.nativeEvent)
+      if (!startPoint) {
+        return
+      }
+      startPointRef.current = { x: startPoint.x, y: startPoint.y, t: Date.now() }
+      rightClickSentRef.current = false
+      scrollingRef.current = false
+      wheelGestureIdRef.current += 1
+      lastWheelRef.current = { dx: 0, dy: 0, at: 0 }
+      panRef.current =
+        zoomRef.current.scale > MIN_ZOOM
+          ? {
+              x: startPoint.x,
+              y: startPoint.y,
+              offsetX: zoomRef.current.offsetX,
+              offsetY: zoomRef.current.offsetY
+            }
+          : null
+      clearLongPressTimer()
+      longPressTimerRef.current = setTimeout(() => {
+        const start = startPointRef.current
+        if (!start) {
+          return
+        }
+        const point = mapTouchPoint(start.x, start.y)
+        if (!point) {
+          return
+        }
+        rightClickSentRef.current = true
+        void sendPointerClick(point, 'right')
+        onToast('Right click')
+      }, LONG_PRESS_MS)
+    },
+    [clearLongPressTimer, frameGeometry, mapTouchPoint, onToast, sendPointerClick]
+  )
+
+  const handleResponderMove = useCallback(
+    (event: GestureResponderEvent, gesture: PanResponderGestureState) => {
+      const startedPinch = pinchRef.current
+        ? null
+        : createPinchGesture(event, frameGeometry, zoomRef.current)
+      if (startedPinch) {
+        clearLongPressTimer()
+        pinchRef.current = startedPinch
+        panRef.current = null
+        startPointRef.current = null
+      }
+      const activePinch = pinchRef.current
+      const nextPinch = activePinch ? updatePinchZoom(event, frameGeometry, activePinch) : null
+      if (nextPinch) {
+        clearLongPressTimer()
+        zoomRef.current = nextPinch
+        setZoom(nextPinch)
+        return
+      }
+      if (activePinch) {
+        pinchRef.current = null
+      }
+      const moved = Math.hypot(gesture.dx, gesture.dy)
+      if (moved > TAP_SLOP) {
+        clearLongPressTimer()
+      }
+      const activePan = panRef.current
+      if (activePan && frameGeometry) {
+        const currentPoint = readLocalTouchPoint(event.nativeEvent)
+        if (!currentPoint) {
+          return
+        }
+        if (!scrollingRef.current && moved <= TAP_SLOP) {
+          return
+        }
+        scrollingRef.current = true
+        startPointRef.current = null
+        const nextZoom = clampBrowserZoomState(
+          {
+            scale: zoomRef.current.scale,
+            offsetX: activePan.offsetX + currentPoint.x - activePan.x,
+            offsetY: activePan.offsetY + currentPoint.y - activePan.y
+          },
+          frameGeometry,
+          MIN_ZOOM,
+          MAX_ZOOM
+        )
+        zoomRef.current = nextZoom
+        setZoom(nextZoom)
+        return
+      }
+      if (!scrollingRef.current) {
+        if (moved <= SCROLL_START_SLOP) {
+          return
+        }
+        scrollingRef.current = true
+        startPointRef.current = null
+      }
+      const now = Date.now()
+      if (now - lastWheelRef.current.at < WHEEL_INTERVAL_MS) {
+        return
+      }
+      const deltaX = gesture.dx - lastWheelRef.current.dx
+      const deltaY = gesture.dy - lastWheelRef.current.dy
+      if (Math.abs(deltaX) + Math.abs(deltaY) < 8) {
+        return
+      }
+      const currentPoint = readLocalTouchPoint(event.nativeEvent)
+      if (!currentPoint) {
+        return
+      }
+      const point = mapTouchPoint(currentPoint.x, currentPoint.y)
+      if (!point) {
+        return
+      }
+      lastWheelRef.current = { dx: gesture.dx, dy: gesture.dy, at: now }
+      sendWheel(point, deltaX, deltaY, wheelGestureIdRef.current)
+    },
+    [clearLongPressTimer, frameGeometry, mapTouchPoint, sendWheel]
+  )
+
+  const handleResponderRelease = useCallback(
+    (event: GestureResponderEvent, gesture: PanResponderGestureState) => {
+      clearLongPressTimer()
+      pinchRef.current = null
+      panRef.current = null
+      const start = startPointRef.current
+      startPointRef.current = null
+      const wasScrolling = scrollingRef.current
+      scrollingRef.current = false
+      if (!start || rightClickSentRef.current || wasScrolling) {
+        return
+      }
+      const moved = Math.hypot(gesture.dx, gesture.dy)
+      if (moved <= TAP_SLOP && Date.now() - start.t < LONG_PRESS_MS) {
+        // Why: native browser taps resolve at touch-up. Using touch-down makes
+        // tiny finger drift feel like the click lands left/up of the finger.
+        const release = readLocalTouchPoint(event.nativeEvent) ?? start
+        const point = mapTouchPoint(release.x, release.y)
+        if (point) {
+          void sendPointerClick(point, 'left')
+        }
+      }
+    },
+    [clearLongPressTimer, mapTouchPoint, sendPointerClick]
+  )
+
+  const panResponder = useMemo(
+    () =>
+      PanResponder.create({
+        onStartShouldSetPanResponder: () => dialogRef.current === null,
+        onMoveShouldSetPanResponder: () => dialogRef.current === null,
+        onPanResponderGrant: handleResponderGrant,
+        onPanResponderMove: handleResponderMove,
+        onPanResponderRelease: handleResponderRelease,
+        onPanResponderTerminate: () => {
+          clearLongPressTimer()
+          pinchRef.current = null
+          panRef.current = null
+          scrollingRef.current = false
+          startPointRef.current = null
+        },
+        onPanResponderTerminationRequest: () => true
+      }),
+    [clearLongPressTimer, handleResponderGrant, handleResponderMove, handleResponderRelease]
+  )
+
+  return { panResponder, sendDialogCommand, sendKeyboardText, sendKeypress, togglePointerModifier }
+}
diff --git a/mobile/src/browser/use-mobile-browser-pane-layers.ts b/mobile/src/browser/use-mobile-browser-pane-layers.ts
new file mode 100644
index 00000000000..a91ca22e71f
--- /dev/null
+++ b/mobile/src/browser/use-mobile-browser-pane-layers.ts
@@ -0,0 +1,141 @@
+import { useCallback } from 'react'
+import type { Image, View } from 'react-native'
+import {
+  updateBrowserImageSource,
+  updateBrowserLayerVisibility,
+  type FrameLayer
+} from './mobile-browser-frame-state'
+import { mobileBrowserPaneStyles as styles } from './mobile-browser-pane-styles'
+
+type BrowserLayerHandlersArgs = {
+  browserImageRefs: { current: [Image | null, Image | null] }
+  browserLayerRefs: { current: [View | null, View | null] }
+  frameUriRef: { current: string | null }
+  pendingFrameLayerRef: { current: FrameLayer | null }
+  visibleFrameLayerRef: { current: FrameLayer }
+}
+
+export function useMobileBrowserPaneLayers(args: BrowserLayerHandlersArgs) {
+  const {
+    browserImageRefs,
+    browserLayerRefs,
+    frameUriRef,
+    pendingFrameLayerRef,
+    visibleFrameLayerRef
+  } = args
+
+  const setBrowserImageRef = useCallback(
+    (layer: FrameLayer, image: Image | null) => {
+      browserImageRefs.current[layer] = image
+      const currentFrameUri = frameUriRef.current
+      if (image && currentFrameUri) {
+        updateBrowserImageSource(image, currentFrameUri)
+      }
+    },
+    [browserImageRefs, frameUriRef]
+  )
+
+  const setBrowserLayerRef = useCallback(
+    (layer: FrameLayer, view: View | null) => {
+      browserLayerRefs.current[layer] = view
+      updateBrowserLayerVisibility(browserLayerRefs.current, visibleFrameLayerRef.current)
+    },
+    [browserLayerRefs, visibleFrameLayerRef]
+  )
+
+  const setBrowserLayer0Ref = useCallback(
+    (view: View | null) => setBrowserLayerRef(0, view),
+    [setBrowserLayerRef]
+  )
+  const setBrowserLayer1Ref = useCallback(
+    (view: View | null) => setBrowserLayerRef(1, view),
+    [setBrowserLayerRef]
+  )
+  const setBrowserImageLayer0Ref = useCallback(
+    (image: Image | null) => setBrowserImageRef(0, image),
+    [setBrowserImageRef]
+  )
+  const setBrowserImageLayer1Ref = useCallback(
+    (image: Image | null) => setBrowserImageRef(1, image),
+    [setBrowserImageRef]
+  )
+
+  const handleBrowserImageLoad = useCallback(
+    (layer: FrameLayer) => {
+      if (pendingFrameLayerRef.current !== layer) {
+        return
+      }
+      pendingFrameLayerRef.current = null
+      visibleFrameLayerRef.current = layer
+      updateBrowserLayerVisibility(browserLayerRefs.current, layer)
+    },
+    [browserLayerRefs, pendingFrameLayerRef, visibleFrameLayerRef]
+  )
+
+  const handleBrowserImageLayer0Load = useCallback(
+    () => handleBrowserImageLoad(0),
+    [handleBrowserImageLoad]
+  )
+  const handleBrowserImageLayer1Load = useCallback(
+    () => handleBrowserImageLoad(1),
+    [handleBrowserImageLoad]
+  )
+
+  const handleBrowserImageError = useCallback(
+    (layer: FrameLayer) => {
+      if (pendingFrameLayerRef.current === layer) {
+        pendingFrameLayerRef.current = null
+      }
+    },
+    [pendingFrameLayerRef]
+  )
+
+  const handleBrowserImageLayer0Error = useCallback(
+    () => handleBrowserImageError(0),
+    [handleBrowserImageError]
+  )
+  const handleBrowserImageLayer1Error = useCallback(
+    () => handleBrowserImageError(1),
+    [handleBrowserImageError]
+  )
+
+  const frameLayerStyle = useCallback(
+    (layer: FrameLayer) => {
+      return [
+        styles.browserImageLayer,
+        visibleFrameLayerRef.current !== layer && styles.browserImageLayerHidden
+      ]
+    },
+    [visibleFrameLayerRef]
+  )
+
+  const browserLayerRef = useCallback(
+    (layer: FrameLayer) => (layer === 0 ? setBrowserLayer0Ref : setBrowserLayer1Ref),
+    [setBrowserLayer0Ref, setBrowserLayer1Ref]
+  )
+
+  const frameLayerRef = useCallback(
+    (layer: FrameLayer) => (layer === 0 ? setBrowserImageLayer0Ref : setBrowserImageLayer1Ref),
+    [setBrowserImageLayer0Ref, setBrowserImageLayer1Ref]
+  )
+
+  const frameLayerLoadHandler = useCallback(
+    (layer: FrameLayer) =>
+      layer === 0 ? handleBrowserImageLayer0Load : handleBrowserImageLayer1Load,
+    [handleBrowserImageLayer0Load, handleBrowserImageLayer1Load]
+  )
+
+  const frameLayerErrorHandler = useCallback(
+    (layer: FrameLayer) =>
+      layer === 0 ? handleBrowserImageLayer0Error : handleBrowserImageLayer1Error,
+    [handleBrowserImageLayer0Error, handleBrowserImageLayer1Error]
+  )
+
+  return {
+    browserLayerRef,
+    frameLayerErrorHandler,
+    frameLayerLoadHandler,
+    frameLayerRef,
+    frameLayerStyle
+  }
+}
diff --git a/mobile/src/browser/use-mobile-browser-request.ts b/mobile/src/browser/use-mobile-browser-request.ts
new file mode 100644
index 00000000000..311b9250ff0
--- /dev/null
+++ b/mobile/src/browser/use-mobile-browser-request.ts
@@ -0,0 +1,67 @@
+import { useCallback, type Dispatch, type SetStateAction } from 'react'
+import type { RpcClient } from '../transport/rpc-client'
+import type { RpcFailure, RpcSuccess } from '../transport/types'
+import { browserErrorMessage, shouldSurfaceBrowserError } from './mobile-browser-frame-state'
+
+type BrowserRequestArgs = {
+  busyRef: { current: boolean }
+  client: RpcClient | null
+  pageId: string | null
+  setBusy: Dispatch<SetStateAction<boolean>>
+  setError: Dispatch<SetStateAction<string | null>>
+  worktreeId: string
+}
+export function useMobileBrowserRequest(args: BrowserRequestArgs) {
+  const { busyRef, client, pageId, setBusy, setError, worktreeId } = args
+  const pageParams = useCallback(() => {
+    if (!pageId) {
+      return null
+    }
+    return {
+      worktree: `id:${worktreeId}`,
+      page: pageId
+    }
+  }, [pageId, worktreeId])
+
+  const sendBrowserRequest = useCallback(
+    async (
+      method: string,
+      params: Record<string, unknown> = {},
+      opts: { showBusy?: boolean; suppressError?: boolean; timeoutMs?: number } = {}
+    ): Promise<unknown | null> => {
+      const base = pageParams()
+      if (!client || !base) {
+        return null
+      }
+      if (opts.showBusy) {
+        busyRef.current = true
+        setBusy(true)
+      }
+      try {
+        const response = await client.sendRequest(
+          method,
+          { ...base, ...params },
+          { timeoutMs: opts.timeoutMs ?? 15_000 }
+        )
+        if (!response.ok) {
+          throw new Error((response as RpcFailure).error.message)
+        }
+        setError(null)
+        return (response as RpcSuccess).result
+      } catch (err) {
+        const message = browserErrorMessage(err, 'Browser command failed')
+        if (!opts.suppressError && shouldSurfaceBrowserError(message)) {
+          setError(message)
+        }
+        return null
+      } finally {
+        if (opts.showBusy) {
+          busyRef.current = false
+          setBusy(false)
+        }
+      }
+    },
+    [client, pageParams]
+  )
+  return { pageParams, sendBrowserRequest }
+}
diff --git a/mobile/src/browser/use-mobile-browser-stream.ts b/mobile/src/browser/use-mobile-browser-stream.ts
new file mode 100644
index 00000000000..5b55dd03ff5
--- /dev/null
+++ b/mobile/src/browser/use-mobile-browser-stream.ts
@@ -0,0 +1,283 @@
+import { useEffect, useMemo, type Dispatch, type SetStateAction } from 'react'
+import { PixelRatio, type Image, type View } from 'react-native'
+import type { RpcClient } from '../transport/rpc-client'
+import type {
+  BrowserScreencastFrame,
+  BrowserScreencastFrameMetadata
+} from '../transport/browser-screencast-protocol'
+import {
+  buildMobileBrowserScreencastRequest,
+  type MobileBrowserViewMode
+} from './browser-screencast-request'
+import {
+  MAX_ZOOM,
+  MIN_ZOOM,
+  getCachedBrowserFrame,
+  updateBrowserLayerVisibility,
+  type FrameLayer
+} from './mobile-browser-frame-state'
+import {
+  clampBrowserZoomState,
+  computeBrowserFrameGeometry,
+  type BrowserTouchLayout,
+  type BrowserZoomState
+} from './browser-touch-geometry'
+import type { MobileBrowserTab } from './MobileBrowserPane'
+import {
+  handleBrowserScreencastEvent,
+  type BrowserDialogState,
+  type ScreencastEvent
+} from './mobile-browser-stream-events'
+import { useMobileBrowserFrameApply } from './use-mobile-browser-frame-apply'
+import { useMobileBrowserRequest } from './use-mobile-browser-request'
+
+type PendingFrame = { frame: BrowserScreencastFrame; cacheKey: string }
+
+type MobileBrowserStreamArgs = {
+  appActive: boolean
+  browserImageRefs: { current: [Image | null, Image | null] }
+  browserLayerRefs: { current: [View | null, View | null] }
+  browserViewMode: MobileBrowserViewMode
+  busyRef: { current: boolean }
+  cacheKey: string | null
+  client: RpcClient | null
+  frameMetadata: BrowserScreencastFrameMetadata | null
+  frameMetadataRef: { current: BrowserScreencastFrameMetadata | null }
+  frameMountedRef: { current: boolean }
+  frameThrottleTimerRef: { current: ReturnType<typeof setTimeout> | null }
+  frameUriRef: { current: string | null }
+  lastAppliedFrameAtRef: { current: number }
+  lastStreamCacheKeyRef: { current: string | null }
+  lastZoomResetUrlRef: { current: string }
+  layout: BrowserTouchLayout | null
+  pendingFrameLayerRef: { current: FrameLayer | null }
+  pendingThrottledFrameRef: { current: PendingFrame | null }
+  resetBrowserZoomState: () => void
+  screencastSupported: boolean | null
+  setAddressValue: Dispatch<SetStateAction<string>>
+  setBusy: Dispatch<SetStateAction<boolean>>
+  setDialog: Dispatch<SetStateAction<BrowserDialogState | null>>
+  setError: Dispatch<SetStateAction<string | null>>
+  setFrameMetadata: Dispatch<SetStateAction<BrowserScreencastFrameMetadata | null>>
+  setFrameUri: Dispatch<SetStateAction<string | null>>
+  setZoom: Dispatch<SetStateAction<BrowserZoomState>>
+  streamGenerationRef: { current: number }
+  tab: MobileBrowserTab
+  visibleFrameLayerRef: { current: FrameLayer }
+  worktreeId: string
+  zoomRef: { current: BrowserZoomState }
+}
+
+export function useMobileBrowserStream(args: MobileBrowserStreamArgs) {
+  const {
+    appActive,
+    browserImageRefs,
+    browserLayerRefs,
+    browserViewMode,
+    busyRef,
+    cacheKey,
+    client,
+    frameMetadata,
+    frameMetadataRef,
+    frameMountedRef,
+    frameThrottleTimerRef,
+    frameUriRef,
+    lastAppliedFrameAtRef,
+    lastStreamCacheKeyRef,
+    lastZoomResetUrlRef,
+    layout,
+    pendingFrameLayerRef,
+    pendingThrottledFrameRef,
+    resetBrowserZoomState,
+    screencastSupported,
+    setAddressValue,
+    setBusy,
+    setDialog,
+    setError,
+    setFrameMetadata,
+    setFrameUri,
+    setZoom,
+    streamGenerationRef,
+    tab,
+    visibleFrameLayerRef,
+    worktreeId,
+    zoomRef
+  } = args
+
+  const { pageParams, sendBrowserRequest } = useMobileBrowserRequest({
+    busyRef,
+    client,
+    pageId: tab.browserPageId,
+    setBusy,
+    setError,
+    worktreeId
+  })
+
+  const { applyFrameThrottled, clearFrameThrottle } = useMobileBrowserFrameApply({
+    browserImageRefs,
+    busyRef,
+    frameMetadataRef,
+    frameMountedRef,
+    frameThrottleTimerRef,
+    frameUriRef,
+    lastAppliedFrameAtRef,
+    pendingFrameLayerRef,
+    pendingThrottledFrameRef,
+    setBusy,
+    setFrameMetadata,
+    setFrameUri,
+    visibleFrameLayerRef
+  })
+
+  const streamRequest = useMemo(
+    () => buildMobileBrowserScreencastRequest(layout, PixelRatio.get(), browserViewMode),
+    [browserViewMode, layout]
+  )
+
+  const frameGeometry = useMemo(
+    () => computeBrowserFrameGeometry(layout, frameMetadata),
+    [frameMetadata, layout]
+  )
+
+  useEffect(() => {
+    if (!frameGeometry) {
+      return
+    }
+    setZoom((current) => {
+      const next = clampBrowserZoomState(current, frameGeometry, MIN_ZOOM, MAX_ZOOM)
+      if (
+        next.scale === current.scale &&
+        next.offsetX === current.offsetX &&
+        next.offsetY === current.offsetY
+      ) {
+        return current
+      }
+      // Why: rotation/layout changes can shrink the legal pan range while the
+      // current zoom state still points at the previous viewport geometry.
+      zoomRef.current = next
+      return next
+    })
+  }, [frameGeometry])
+
+  useEffect(() => {
+    streamGenerationRef.current += 1
+    const generation = streamGenerationRef.current
+    const sameStream = Boolean(cacheKey) && lastStreamCacheKeyRef.current === cacheKey
+    lastStreamCacheKeyRef.current = cacheKey
+    if (!sameStream || !frameUriRef.current) {
+      const cachedFrame = getCachedBrowserFrame(cacheKey)
+      if (cachedFrame) {
+        frameUriRef.current = cachedFrame.uri
+        frameMountedRef.current = true
+        frameMetadataRef.current = cachedFrame.metadata
+        setFrameUri(cachedFrame.uri)
+        setFrameMetadata(cachedFrame.metadata)
+      } else {
+        frameUriRef.current = null
+        frameMountedRef.current = false
+        setFrameUri(null)
+        setFrameMetadata(null)
+        frameMetadataRef.current = null
+      }
+    } else {
+      frameMountedRef.current = true
+    }
+    pendingFrameLayerRef.current = null
+    if (!sameStream || !frameUriRef.current) {
+      visibleFrameLayerRef.current = 0
+    }
+    updateBrowserLayerVisibility(browserLayerRefs.current, visibleFrameLayerRef.current)
+    lastAppliedFrameAtRef.current = 0
+    clearFrameThrottle()
+    busyRef.current = false
+    setDialog(null)
+    setError(null)
+    if (
+      !client ||
+      screencastSupported !== true ||
+      !tab.browserPageId ||
+      !appActive ||
+      !streamRequest
+    ) {
+      busyRef.current = false
+      setBusy(false)
+      if (screencastSupported === false) {
+        setError('Update desktop Orca to stream browser tabs on mobile.')
+      } else if (screencastSupported === null) {
+        setError('Checking desktop browser streaming support.')
+      } else if (!tab.browserPageId) {
+        setError('Browser page is not available yet.')
+      }
+      return
+    }
+    busyRef.current = true
+    setBusy(true)
+    let startupTimer: ReturnType<typeof setTimeout> | null = setTimeout(() => {
+      if (streamGenerationRef.current !== generation) {
+        return
+      }
+      busyRef.current = false
+      setBusy(false)
+      setError('Browser stream timed out.')
+    }, 15_000)
+    const clearStartupTimer = (): void => {
+      if (startupTimer) {
+        clearTimeout(startupTimer)
+        startupTimer = null
+      }
+    }
+    const unsubscribe = client.subscribe(
+      'browser.screencast',
+      {
+        worktree: `id:${worktreeId}`,
+        page: tab.browserPageId,
+        ...streamRequest
+      },
+      (payload) => {
+        if (streamGenerationRef.current !== generation) {
+          return
+        }
+        handleBrowserScreencastEvent({
+          busyRef,
+          clearStartupTimer,
+          event: payload as ScreencastEvent,
+          lastZoomResetUrlRef,
+          resetBrowserZoomState,
+          setAddressValue,
+          setBusy,
+          setDialog,
+          setError
+        })
+      },
+      {
+        onBinaryFrame: (frame) => {
+          if (streamGenerationRef.current !== generation) {
+            return
+          }
+          clearStartupTimer()
+          if (cacheKey) {
+            applyFrameThrottled(frame, cacheKey)
+          }
+        }
+      }
+    )
+    return () => {
+      clearStartupTimer()
+      clearFrameThrottle()
+      unsubscribe()
+    }
+  }, [
+    appActive,
+    applyFrameThrottled,
+    clearFrameThrottle,
+    client,
+    resetBrowserZoomState,
+    screencastSupported,
+    streamRequest,
+    cacheKey,
+    tab.browserPageId,
+    worktreeId
+  ])
+
+  return { frameGeometry, pageParams, sendBrowserRequest }
+}

From 871601b6fed71a85e6d0745397df329355002fc0 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sat, 29 Aug 2026 20:06:41 -0700
Subject: [PATCH 23/31] Prune resolved max-lines suppressions (#17142)

* Split speech session lifecycle

* Split terminal output scheduler pipeline

* Split mobile browser pane modules

* Prune resolved max-lines suppressions

* Fix F3-speech for #17123

* Fix F1-cycle for #17131
---
 config/max-lines-baseline.txt     | 2 --
 mobile/.oxlintrc.json             | 6 ------
 src/relay/workspace-space-scan.ts | 2 --
 3 files changed, 10 deletions(-)

diff --git a/config/max-lines-baseline.txt b/config/max-lines-baseline.txt
index cd2253dcde7..740626e9bae 100644
--- a/config/max-lines-baseline.txt
+++ b/config/max-lines-baseline.txt
@@ -38,7 +38,6 @@ inline src/preload/index.ts
 inline src/relay/dispatcher.ts
 inline src/relay/git-handler.ts
 inline src/relay/pty-handler.ts
-inline src/relay/workspace-space-scan.ts
 inline src/renderer/src/components/GitLabItemDialog.tsx
 inline src/renderer/src/components/LinearItemDrawer.tsx
 inline src/renderer/src/components/TaskPage.tsx
@@ -83,6 +82,5 @@ mobile-config app/h/*/tasks.tsx
 mobile-config app/index.tsx
 mobile-config app/troubleshoot.tsx
 mobile-config scripts/mock-server.ts
-mobile-config src/components/NewWorktreeModal.tsx
 mobile-config src/terminal/terminal-webview-html.ts
 mobile-config src/transport/rpc-client.ts
diff --git a/mobile/.oxlintrc.json b/mobile/.oxlintrc.json
index 7192820eb16..9100394b001 100644
--- a/mobile/.oxlintrc.json
+++ b/mobile/.oxlintrc.json
@@ -57,12 +57,6 @@
         "max-lines": ["error", { "max": 1422, "skipBlankLines": true, "skipComments": true }]
       }
     },
-    {
-      "files": ["src/components/NewWorktreeModal.tsx"],
-      "rules": {
-        "max-lines": ["error", { "max": 1263, "skipBlankLines": true, "skipComments": true }]
-      }
-    },
     {
       "files": ["src/transport/rpc-client.ts"],
       "rules": {
diff --git a/src/relay/workspace-space-scan.ts b/src/relay/workspace-space-scan.ts
index d66f0d0e618..73a68454833 100644
--- a/src/relay/workspace-space-scan.ts
+++ b/src/relay/workspace-space-scan.ts
@@ -1,5 +1,3 @@
-/* eslint-disable max-lines -- Why: local and relay Space scans share the same
-   cancellation, symlink, and top-level compaction semantics in one scanner. */
 import { execFile } from 'node:child_process'
 import type { Dirent } from 'node:fs'
 import { lstat, opendir } from 'node:fs/promises'

From 11a0deb8ee5af61c014679fbb9115a07a1ce181d Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sat, 29 Aug 2026 20:07:03 -0700
Subject: [PATCH 24/31] Split pane tree equalization logic (#17145)

* Split speech session lifecycle

* Split terminal output scheduler pipeline

* Split mobile browser pane modules

* Prune resolved max-lines suppressions

* Split pane tree equalization logic

* Fix F3-speech for #17123

* Fix F1-cycle for #17131
---
 config/max-lines-baseline.txt                 |  1 -
 .../pane-manager/pane-tree-equalization.ts    | 59 ++++++++++++++++++
 .../src/lib/pane-manager/pane-tree-ops.ts     | 62 +------------------
 3 files changed, 60 insertions(+), 62 deletions(-)
 create mode 100644 src/renderer/src/lib/pane-manager/pane-tree-equalization.ts

diff --git a/config/max-lines-baseline.txt b/config/max-lines-baseline.txt
index 740626e9bae..db6c77afbd8 100644
--- a/config/max-lines-baseline.txt
+++ b/config/max-lines-baseline.txt
@@ -61,7 +61,6 @@ inline src/renderer/src/components/terminal-pane/remote-runtime-pty-transport.ts
 inline src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts
 inline src/renderer/src/hooks/useAutomationDispatchEvents.ts
 inline src/renderer/src/hooks/useSettingsNavigationMetadata.ts
-inline src/renderer/src/lib/pane-manager/pane-tree-ops.ts
 inline src/renderer/src/runtime/remote-runtime-terminal-multiplexer.ts
 inline src/renderer/src/runtime/runtime-file-client.ts
 inline src/renderer/src/runtime/sync-runtime-graph.ts
diff --git a/src/renderer/src/lib/pane-manager/pane-tree-equalization.ts b/src/renderer/src/lib/pane-manager/pane-tree-equalization.ts
new file mode 100644
index 00000000000..7e36064d9bc
--- /dev/null
+++ b/src/renderer/src/lib/pane-manager/pane-tree-equalization.ts
@@ -0,0 +1,59 @@
+/** Find non-divider children (panes and splits) of an element. */
+export function findPaneChildren(parent: HTMLElement): HTMLElement[] {
+  return Array.from(parent.children).filter(
+    (child): child is HTMLElement =>
+      child instanceof HTMLElement &&
+      (child.classList.contains('pane') || child.classList.contains('pane-split'))
+  )
+}
+
+function getSplitDirection(split: HTMLElement): 'vertical' | 'horizontal' {
+  return split.classList.contains('is-horizontal') ? 'horizontal' : 'vertical'
+}
+
+function getEqualizeWeight(el: HTMLElement, direction: 'vertical' | 'horizontal'): number {
+  if (!el.classList.contains('pane-split') || getSplitDirection(el) !== direction) {
+    return 1
+  }
+
+  const children = findPaneChildren(el)
+  return Math.max(
+    1,
+    children.reduce((sum, child) => sum + getEqualizeWeight(child, direction), 0)
+  )
+}
+
+export function equalizePaneSplitSizes(root: HTMLElement | null): boolean {
+  if (!root) {
+    return false
+  }
+
+  let changed = false
+  const visit = (el: HTMLElement): void => {
+    if (!el.classList.contains('pane-split')) {
+      return
+    }
+
+    const direction = getSplitDirection(el)
+    const children = findPaneChildren(el)
+    if (children.length >= 2) {
+      for (const child of children) {
+        // Why: same-axis nested splits need pane-count weighting so three
+        // side-by-side panes become thirds, not 50/25/25.
+        const weight = getEqualizeWeight(child, direction)
+        const nextFlex = `${weight} 1 0%`
+        if (child.style.flex !== nextFlex) {
+          child.style.flex = nextFlex
+          changed = true
+        }
+      }
+    }
+
+    for (const child of children) {
+      visit(child)
+    }
+  }
+
+  visit(root)
+  return changed
+}
diff --git a/src/renderer/src/lib/pane-manager/pane-tree-ops.ts b/src/renderer/src/lib/pane-manager/pane-tree-ops.ts
index 833eb1ff822..3549860183b 100644
--- a/src/renderer/src/lib/pane-manager/pane-tree-ops.ts
+++ b/src/renderer/src/lib/pane-manager/pane-tree-ops.ts
@@ -1,4 +1,3 @@
-/* eslint-disable max-lines -- Why: split-tree DOM reparent, promote, and equalize rules need one consistent owner. */
 import type {
   DropZone,
   ManagedPane,
@@ -16,6 +15,7 @@ export {
   type SafeFitContinuationHandle
 } from './pane-fit'
 export { captureScrollState, restoreScrollState } from './pane-scroll'
+export { equalizePaneSplitSizes, findPaneChildren } from './pane-tree-equalization'
 
 // ---------------------------------------------------------------------------
 // Split-tree manipulation: detach, insert, promote sibling
@@ -242,66 +242,6 @@ export function removeDividers(parent: HTMLElement): void {
   }
 }
 
-/** Find non-divider children (panes and splits) of an element. */
-export function findPaneChildren(parent: HTMLElement): HTMLElement[] {
-  return Array.from(parent.children).filter(
-    (child): child is HTMLElement =>
-      child instanceof HTMLElement &&
-      (child.classList.contains('pane') || child.classList.contains('pane-split'))
-  )
-}
-
-function getSplitDirection(split: HTMLElement): 'vertical' | 'horizontal' {
-  return split.classList.contains('is-horizontal') ? 'horizontal' : 'vertical'
-}
-
-function getEqualizeWeight(el: HTMLElement, direction: 'vertical' | 'horizontal'): number {
-  if (!el.classList.contains('pane-split') || getSplitDirection(el) !== direction) {
-    return 1
-  }
-
-  const children = findPaneChildren(el)
-  return Math.max(
-    1,
-    children.reduce((sum, child) => sum + getEqualizeWeight(child, direction), 0)
-  )
-}
-
-export function equalizePaneSplitSizes(root: HTMLElement | null): boolean {
-  if (!root) {
-    return false
-  }
-
-  let changed = false
-  const visit = (el: HTMLElement): void => {
-    if (!el.classList.contains('pane-split')) {
-      return
-    }
-
-    const direction = getSplitDirection(el)
-    const children = findPaneChildren(el)
-    if (children.length >= 2) {
-      for (const child of children) {
-        // Why: same-axis nested splits need pane-count weighting so three
-        // side-by-side panes become thirds, not 50/25/25.
-        const weight = getEqualizeWeight(child, direction)
-        const nextFlex = `${weight} 1 0%`
-        if (child.style.flex !== nextFlex) {
-          child.style.flex = nextFlex
-          changed = true
-        }
-      }
-    }
-
-    for (const child of children) {
-      visit(child)
-    }
-  }
-
-  visit(root)
-  return changed
-}
-
 /**
  * Create a flex split wrapper that replaces `existingContainer` in the DOM,
  * then places [existing] [divider] [new] inside it.

From 5f75b247b9ccffca614c83f26f1c41fa13f29b04 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sat, 29 Aug 2026 20:07:23 -0700
Subject: [PATCH 25/31] Extract mobile troubleshoot screen styles (#17146)

* Split speech session lifecycle

* Split terminal output scheduler pipeline

* Split mobile browser pane modules

* Prune resolved max-lines suppressions

* Split pane tree equalization logic

* Extract mobile troubleshoot screen styles

* Fix F3-speech for #17123

* Fix F1-cycle for #17131
---
 config/max-lines-baseline.txt                 |   1 -
 mobile/.oxlintrc.json                         |   6 -
 mobile/app/troubleshoot.tsx                   | 145 +-----------------
 .../diagnostics/troubleshoot-screen-styles.ts | 134 ++++++++++++++++
 4 files changed, 137 insertions(+), 149 deletions(-)
 create mode 100644 mobile/src/diagnostics/troubleshoot-screen-styles.ts

diff --git a/config/max-lines-baseline.txt b/config/max-lines-baseline.txt
index db6c77afbd8..859b4f5c59c 100644
--- a/config/max-lines-baseline.txt
+++ b/config/max-lines-baseline.txt
@@ -79,7 +79,6 @@ mobile-config app/h/*/session/*.tsx
 mobile-config app/h/*/source-control/*.tsx
 mobile-config app/h/*/tasks.tsx
 mobile-config app/index.tsx
-mobile-config app/troubleshoot.tsx
 mobile-config scripts/mock-server.ts
 mobile-config src/terminal/terminal-webview-html.ts
 mobile-config src/transport/rpc-client.ts
diff --git a/mobile/.oxlintrc.json b/mobile/.oxlintrc.json
index 9100394b001..f845c3e9a1f 100644
--- a/mobile/.oxlintrc.json
+++ b/mobile/.oxlintrc.json
@@ -69,12 +69,6 @@
         "max-lines": ["error", { "max": 407, "skipBlankLines": true, "skipComments": true }]
       }
     },
-    {
-      "files": ["app/troubleshoot.tsx"],
-      "rules": {
-        "max-lines": ["error", { "max": 436, "skipBlankLines": true, "skipComments": true }]
-      }
-    },
     {
       "files": ["app/h/*/files/*.tsx"],
       "rules": {
diff --git a/mobile/app/troubleshoot.tsx b/mobile/app/troubleshoot.tsx
index c4313e88fcc..63fc0ddd477 100644
--- a/mobile/app/troubleshoot.tsx
+++ b/mobile/app/troubleshoot.tsx
@@ -1,13 +1,5 @@
 import { useState, useCallback, useRef } from 'react'
-import {
-  View,
-  Text,
-  StyleSheet,
-  Pressable,
-  ScrollView,
-  ActivityIndicator,
-  Platform
-} from 'react-native'
+import { View, Text, Pressable, ScrollView, ActivityIndicator, Platform } from 'react-native'
 import { useSafeAreaInsets } from 'react-native-safe-area-context'
 import { useRouter } from 'expo-router'
 import {
@@ -20,7 +12,7 @@ import {
   XCircle,
   AlertTriangle
 } from 'lucide-react-native'
-import { colors, spacing, typography } from '../src/theme/mobile-theme'
+import { colors, spacing } from '../src/theme/mobile-theme'
 import { loadHosts } from '../src/transport/host-store'
 import {
   startDiagnosticFetchTimeout,
@@ -32,6 +24,7 @@ import {
   unreachableHostDetail
 } from '../src/diagnostics/host-reachability'
 import { troubleshootCommonIssues } from '../src/diagnostics/troubleshoot-common-issues'
+import { troubleshootScreenStyles as styles } from '../src/diagnostics/troubleshoot-screen-styles'
 
 type DiagnosticStatus = 'idle' | 'running' | 'done'
 
@@ -281,135 +274,3 @@ export default function TroubleshootScreen() {
     </View>
   )
 }
-
-const styles = StyleSheet.create({
-  container: {
-    flex: 1,
-    backgroundColor: colors.bgBase,
-    padding: spacing.lg
-  },
-  topRow: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    marginBottom: spacing.lg
-  },
-  backButton: {
-    width: 36,
-    height: 36,
-    borderRadius: 18,
-    alignItems: 'center',
-    justifyContent: 'center',
-    marginRight: spacing.sm
-  },
-  heading: {
-    fontSize: 20,
-    fontWeight: '700',
-    color: colors.textPrimary
-  },
-  scroll: {
-    flex: 1
-  },
-  scrollContent: {
-    paddingBottom: spacing.xl
-  },
-  diagnosticButton: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    justifyContent: 'center',
-    gap: spacing.sm,
-    backgroundColor: colors.bgRaised,
-    borderRadius: 10,
-    paddingVertical: spacing.md,
-    paddingHorizontal: spacing.lg,
-    marginBottom: spacing.lg
-  },
-  diagnosticButtonPressed: {
-    opacity: 0.7
-  },
-  diagnosticButtonDisabled: {
-    opacity: 0.5
-  },
-  diagnosticButtonLabel: {
-    fontSize: typography.bodySize,
-    fontWeight: '600',
-    color: colors.textPrimary
-  },
-  checkRow: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    gap: spacing.sm,
-    paddingVertical: spacing.sm + 2,
-    paddingHorizontal: spacing.md + 2
-  },
-  checkLabel: {
-    fontSize: typography.bodySize,
-    fontWeight: '500',
-    color: colors.textPrimary
-  },
-  checkDetail: {
-    flex: 1,
-    textAlign: 'right',
-    fontSize: typography.metaSize,
-    color: colors.textMuted
-  },
-  checkDetailFail: {
-    color: colors.statusRed
-  },
-  sectionHeading: {
-    fontSize: typography.metaSize,
-    fontWeight: '600',
-    color: colors.textMuted,
-    textTransform: 'uppercase',
-    letterSpacing: 0.5,
-    marginBottom: spacing.sm,
-    marginTop: spacing.sm,
-    paddingHorizontal: spacing.xs
-  },
-  section: {
-    backgroundColor: colors.bgPanel,
-    borderRadius: 12,
-    overflow: 'hidden',
-    marginBottom: spacing.lg
-  },
-  separator: {
-    height: StyleSheet.hairlineWidth,
-    backgroundColor: colors.borderSubtle,
-    marginHorizontal: spacing.md
-  },
-  rowPressed: {
-    backgroundColor: colors.bgRaised
-  },
-  accordionHeader: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    gap: spacing.sm + 2,
-    paddingVertical: spacing.md,
-    paddingHorizontal: spacing.md + 2
-  },
-  accordionTitle: {
-    flex: 1,
-    fontSize: typography.bodySize,
-    fontWeight: '500',
-    color: colors.textPrimary
-  },
-  accordionBody: {
-    paddingHorizontal: spacing.md + 2,
-    paddingBottom: spacing.md,
-    gap: spacing.xs + 2
-  },
-  stepRow: {
-    flexDirection: 'row',
-    gap: spacing.sm
-  },
-  bullet: {
-    fontSize: typography.metaSize,
-    color: colors.textMuted,
-    lineHeight: 18
-  },
-  stepText: {
-    flex: 1,
-    fontSize: typography.metaSize,
-    color: colors.textMuted,
-    lineHeight: 18
-  }
-})
diff --git a/mobile/src/diagnostics/troubleshoot-screen-styles.ts b/mobile/src/diagnostics/troubleshoot-screen-styles.ts
new file mode 100644
index 00000000000..bf200e3c080
--- /dev/null
+++ b/mobile/src/diagnostics/troubleshoot-screen-styles.ts
@@ -0,0 +1,134 @@
+import { StyleSheet } from 'react-native'
+import { colors, spacing, typography } from '../theme/mobile-theme'
+
+export const troubleshootScreenStyles = StyleSheet.create({
+  container: {
+    flex: 1,
+    backgroundColor: colors.bgBase,
+    padding: spacing.lg
+  },
+  topRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    marginBottom: spacing.lg
+  },
+  backButton: {
+    width: 36,
+    height: 36,
+    borderRadius: 18,
+    alignItems: 'center',
+    justifyContent: 'center',
+    marginRight: spacing.sm
+  },
+  heading: {
+    fontSize: 20,
+    fontWeight: '700',
+    color: colors.textPrimary
+  },
+  scroll: {
+    flex: 1
+  },
+  scrollContent: {
+    paddingBottom: spacing.xl
+  },
+  diagnosticButton: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: spacing.sm,
+    backgroundColor: colors.bgRaised,
+    borderRadius: 10,
+    paddingVertical: spacing.md,
+    paddingHorizontal: spacing.lg,
+    marginBottom: spacing.lg
+  },
+  diagnosticButtonPressed: {
+    opacity: 0.7
+  },
+  diagnosticButtonDisabled: {
+    opacity: 0.5
+  },
+  diagnosticButtonLabel: {
+    fontSize: typography.bodySize,
+    fontWeight: '600',
+    color: colors.textPrimary
+  },
+  checkRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: spacing.sm,
+    paddingVertical: spacing.sm + 2,
+    paddingHorizontal: spacing.md + 2
+  },
+  checkLabel: {
+    fontSize: typography.bodySize,
+    fontWeight: '500',
+    color: colors.textPrimary
+  },
+  checkDetail: {
+    flex: 1,
+    textAlign: 'right',
+    fontSize: typography.metaSize,
+    color: colors.textMuted
+  },
+  checkDetailFail: {
+    color: colors.statusRed
+  },
+  sectionHeading: {
+    fontSize: typography.metaSize,
+    fontWeight: '600',
+    color: colors.textMuted,
+    textTransform: 'uppercase',
+    letterSpacing: 0.5,
+    marginBottom: spacing.sm,
+    marginTop: spacing.sm,
+    paddingHorizontal: spacing.xs
+  },
+  section: {
+    backgroundColor: colors.bgPanel,
+    borderRadius: 12,
+    overflow: 'hidden',
+    marginBottom: spacing.lg
+  },
+  separator: {
+    height: StyleSheet.hairlineWidth,
+    backgroundColor: colors.borderSubtle,
+    marginHorizontal: spacing.md
+  },
+  rowPressed: {
+    backgroundColor: colors.bgRaised
+  },
+  accordionHeader: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: spacing.sm + 2,
+    paddingVertical: spacing.md,
+    paddingHorizontal: spacing.md + 2
+  },
+  accordionTitle: {
+    flex: 1,
+    fontSize: typography.bodySize,
+    fontWeight: '500',
+    color: colors.textPrimary
+  },
+  accordionBody: {
+    paddingHorizontal: spacing.md + 2,
+    paddingBottom: spacing.md,
+    gap: spacing.xs + 2
+  },
+  stepRow: {
+    flexDirection: 'row',
+    gap: spacing.sm
+  },
+  bullet: {
+    fontSize: typography.metaSize,
+    color: colors.textMuted,
+    lineHeight: 18
+  },
+  stepText: {
+    flex: 1,
+    fontSize: typography.metaSize,
+    color: colors.textMuted,
+    lineHeight: 18
+  }
+})

From 7b5bed955098c1f8d117b431de095da858caeac4 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sat, 29 Aug 2026 20:07:46 -0700
Subject: [PATCH 26/31] Split external automation manager (#17149)

* Split speech session lifecycle

* Split terminal output scheduler pipeline

* Split mobile browser pane modules

* Prune resolved max-lines suppressions

* Split pane tree equalization logic

* Extract mobile troubleshoot screen styles

* Split external automation manager

* Fix F3-speech for #17123

* Fix F1-cycle for #17131
---
 config/max-lines-baseline.txt                 |   1 -
 .../automations/external-manager-discovery.ts | 163 ++++++
 .../automations/external-manager-job-id.ts    |   7 +
 .../external-manager-local-command.ts         |  45 ++
 .../automations/external-manager-mutations.ts | 139 ++++++
 .../automations/external-manager-relay.ts     |  35 ++
 src/main/automations/external-manager-runs.ts |  81 +++
 src/main/automations/external-manager.ts      | 462 +-----------------
 8 files changed, 490 insertions(+), 443 deletions(-)
 create mode 100644 src/main/automations/external-manager-discovery.ts
 create mode 100644 src/main/automations/external-manager-job-id.ts
 create mode 100644 src/main/automations/external-manager-local-command.ts
 create mode 100644 src/main/automations/external-manager-mutations.ts
 create mode 100644 src/main/automations/external-manager-relay.ts
 create mode 100644 src/main/automations/external-manager-runs.ts

diff --git a/config/max-lines-baseline.txt b/config/max-lines-baseline.txt
index 859b4f5c59c..83c550911ee 100644
--- a/config/max-lines-baseline.txt
+++ b/config/max-lines-baseline.txt
@@ -3,7 +3,6 @@
 # split the oversized file instead (AGENTS.md → "Do Not Disable Max Lines").
 # Regenerate/prune: pnpm check:max-lines-ratchet --prune   (removes stale entries only)
 inline src/main/agent-hooks/server.ts
-inline src/main/automations/external-manager.ts
 inline src/main/browser/agent-browser-bridge.ts
 inline src/main/browser/browser-cookie-import.ts
 inline src/main/browser/browser-manager.ts
diff --git a/src/main/automations/external-manager-discovery.ts b/src/main/automations/external-manager-discovery.ts
new file mode 100644
index 00000000000..9eed6c44a40
--- /dev/null
+++ b/src/main/automations/external-manager-discovery.ts
@@ -0,0 +1,163 @@
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import type {
+  ExternalAutomationManager,
+  ExternalAutomationProvider
+} from '../../shared/automations-types'
+import type { SshTarget } from '../../shared/ssh-types'
+import { getActiveMultiplexer } from '../ssh/ssh-target-registry'
+import { mapHermesJobs, mapOpenClawJobs } from './external-job-mappers'
+import { readHermesCronOutputRunsPage } from './hermes-cron-output'
+import { isExternalAutomationCommandOnPath } from './external-manager-local-command'
+import { externalAutomationRelayErrorMessage } from './external-manager-relay'
+
+const HERMES_HOME = process.env.HERMES_HOME?.trim() || join(homedir(), '.hermes')
+const HERMES_CRON_DIR = join(HERMES_HOME, 'cron')
+const HERMES_JOBS_FILE = join(HERMES_CRON_DIR, 'jobs.json')
+const OPENCLAW_JOBS_FILE = join(homedir(), '.openclaw', 'cron', 'jobs.json')
+const PROVIDER_LABELS: Record<ExternalAutomationProvider, string> = {
+  hermes: 'Hermes',
+  openclaw: 'OpenClaw'
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+async function readLocalHermesJobs(): Promise<unknown[]> {
+  if (!existsSync(HERMES_JOBS_FILE)) {
+    return []
+  }
+  const content = await readFile(HERMES_JOBS_FILE, 'utf-8')
+  const parsed = JSON.parse(content) as unknown
+  const jobs = Array.isArray(parsed)
+    ? parsed
+    : isRecord(parsed) && Array.isArray(parsed.jobs)
+      ? parsed.jobs
+      : []
+  return Promise.all(
+    jobs.map(async (job) => {
+      if (!isRecord(job)) {
+        return job
+      }
+      const jobId = typeof job.id === 'string' ? job.id : null
+      if (!jobId) {
+        return job
+      }
+      const runsPage = await readHermesCronOutputRunsPage(jobId, { page: 1, pageSize: 0 })
+      return {
+        ...job,
+        run_count: runsPage.total,
+        runs: []
+      }
+    })
+  )
+}
+
+async function readLocalOpenClawJobs(): Promise<unknown[]> {
+  if (!existsSync(OPENCLAW_JOBS_FILE)) {
+    return []
+  }
+  const content = await readFile(OPENCLAW_JOBS_FILE, 'utf-8')
+  const parsed = JSON.parse(content) as unknown
+  return isRecord(parsed) && Array.isArray(parsed.jobs) ? parsed.jobs : []
+}
+
+function mapProviderJobs(
+  provider: ExternalAutomationProvider,
+  managerId: string,
+  jobs: unknown[]
+): ExternalAutomationManager['jobs'] {
+  return provider === 'hermes' ? mapHermesJobs(managerId, jobs) : mapOpenClawJobs(managerId, jobs)
+}
+
+export async function listLocalManager(
+  provider: ExternalAutomationProvider
+): Promise<ExternalAutomationManager | null> {
+  const [availableResult, jobsResult] = await Promise.allSettled([
+    isExternalAutomationCommandOnPath(provider),
+    provider === 'hermes' ? readLocalHermesJobs() : readLocalOpenClawJobs()
+  ])
+  const available = availableResult.status === 'fulfilled' && availableResult.value
+  const jobs = jobsResult.status === 'fulfilled' ? jobsResult.value : []
+  const readError = jobsResult.status === 'rejected' ? String(jobsResult.reason) : null
+  if (!available && jobs.length === 0 && !readError) {
+    return null
+  }
+  const managerId = `${provider}:local`
+  const providerLabel = PROVIDER_LABELS[provider]
+  return {
+    id: managerId,
+    provider,
+    label: `${providerLabel} on this computer`,
+    targetLabel: 'this computer',
+    target: { type: 'local' },
+    status: readError ? 'unavailable' : 'available',
+    error:
+      readError ??
+      (available
+        ? null
+        : `${providerLabel} jobs were found, but the ${provider} CLI is not on PATH.`),
+    canManage: !readError && available,
+    jobs: mapProviderJobs(provider, managerId, jobs)
+  }
+}
+
+export async function listRemoteManager(
+  target: SshTarget,
+  provider: ExternalAutomationProvider
+): Promise<ExternalAutomationManager> {
+  const providerLabel = PROVIDER_LABELS[provider]
+  const managerProviderId = `${provider}:ssh:${target.id}`
+  const mux = getActiveMultiplexer(target.id)
+  if (!mux || mux.isDisposed()) {
+    return {
+      id: managerProviderId,
+      provider,
+      label: `${providerLabel} on ${target.label}`,
+      targetLabel: target.label,
+      target: { type: 'ssh', connectionId: target.id },
+      status: 'unavailable',
+      error: 'SSH target is not connected.',
+      canManage: false,
+      jobs: []
+    }
+  }
+  try {
+    const result = (await mux.request('externalAutomations.list', { provider })) as {
+      jobs?: unknown[]
+      hermesAvailable?: boolean
+      openclawAvailable?: boolean
+      error?: string | null
+    }
+    const commandAvailable =
+      provider === 'hermes' ? result.hermesAvailable === true : result.openclawAvailable === true
+    const readError = result.error ?? null
+    return {
+      id: managerProviderId,
+      provider,
+      label: `${providerLabel} on ${target.label}`,
+      targetLabel: target.label,
+      target: { type: 'ssh', connectionId: target.id },
+      status: readError ? 'unavailable' : 'available',
+      error:
+        readError ?? (commandAvailable ? null : `${providerLabel} CLI is not on the remote PATH.`),
+      canManage: !readError && commandAvailable,
+      jobs: mapProviderJobs(provider, managerProviderId, result.jobs ?? [])
+    }
+  } catch (error) {
+    return {
+      id: managerProviderId,
+      provider,
+      label: `${providerLabel} on ${target.label}`,
+      targetLabel: target.label,
+      target: { type: 'ssh', connectionId: target.id },
+      status: 'unavailable',
+      error: externalAutomationRelayErrorMessage(error),
+      canManage: false,
+      jobs: []
+    }
+  }
+}
diff --git a/src/main/automations/external-manager-job-id.ts b/src/main/automations/external-manager-job-id.ts
new file mode 100644
index 00000000000..6d8ac157f98
--- /dev/null
+++ b/src/main/automations/external-manager-job-id.ts
@@ -0,0 +1,7 @@
+const EXTERNAL_JOB_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/
+
+export function assertExternalAutomationJobId(jobId: string): void {
+  if (!EXTERNAL_JOB_ID_PATTERN.test(jobId)) {
+    throw new Error('Invalid external automation job ID.')
+  }
+}
diff --git a/src/main/automations/external-manager-local-command.ts b/src/main/automations/external-manager-local-command.ts
new file mode 100644
index 00000000000..44d81e68ec8
--- /dev/null
+++ b/src/main/automations/external-manager-local-command.ts
@@ -0,0 +1,45 @@
+import { runProcess } from '../../shared/child-process/run-process'
+
+const LOCAL_COMMAND_LOOKUP_TIMEOUT_MS = 5_000
+const LOCAL_AUTOMATION_COMMAND_TIMEOUT_MS = 30_000
+
+function runLocalProviderCommand(
+  command: string,
+  args: string[],
+  options: { timeoutMs: number; timeoutMessage: string }
+): Promise<void> {
+  return runProcess({ program: command, args, timeoutMs: options.timeoutMs }).then((result) => {
+    if (result.timedOut) {
+      throw new Error(options.timeoutMessage)
+    }
+    if (result.code !== 0) {
+      throw new Error(
+        result.stderr.trim() || `Command exited with code ${result.code ?? 'unknown'}.`
+      )
+    }
+  })
+}
+
+export async function isExternalAutomationCommandOnPath(command: string): Promise<boolean> {
+  const finder = process.platform === 'win32' ? 'where' : 'which'
+  try {
+    // Why: these probes run while loading Automations; a wedged PATH shim must
+    // not keep the list IPC pending forever.
+    await runLocalProviderCommand(finder, [command], {
+      timeoutMs: LOCAL_COMMAND_LOOKUP_TIMEOUT_MS,
+      timeoutMessage: `Command lookup timed out after ${LOCAL_COMMAND_LOOKUP_TIMEOUT_MS}ms.`
+    })
+    return true
+  } catch {
+    return false
+  }
+}
+
+// Why: local automation mutations back UI actions; a wedged CLI must not keep
+// create/edit/run/delete pending after Node signals a timeout.
+export function runLocalAutomationCommand(command: string, args: string[]): Promise<void> {
+  return runLocalProviderCommand(command, args, {
+    timeoutMs: LOCAL_AUTOMATION_COMMAND_TIMEOUT_MS,
+    timeoutMessage: `Local automation command timed out after ${LOCAL_AUTOMATION_COMMAND_TIMEOUT_MS}ms.`
+  })
+}
diff --git a/src/main/automations/external-manager-mutations.ts b/src/main/automations/external-manager-mutations.ts
new file mode 100644
index 00000000000..215e00e7a8e
--- /dev/null
+++ b/src/main/automations/external-manager-mutations.ts
@@ -0,0 +1,139 @@
+import type {
+  ExternalAutomationAction,
+  ExternalAutomationActionInput,
+  ExternalAutomationCreateInput,
+  ExternalAutomationProvider,
+  ExternalAutomationUpdateInput
+} from '../../shared/automations-types'
+import { assertExternalAutomationJobId } from './external-manager-job-id'
+import { runLocalAutomationCommand } from './external-manager-local-command'
+import { requireExternalAutomationMultiplexer } from './external-manager-relay'
+import { clearHermesCronOutputRunCountCache } from './hermes-cron-output'
+
+const PROVIDER_ACTION_COMMANDS: Record<
+  ExternalAutomationProvider,
+  Record<ExternalAutomationAction, string>
+> = {
+  hermes: { pause: 'pause', resume: 'resume', run: 'run', delete: 'remove' },
+  openclaw: { pause: 'disable', resume: 'enable', run: 'run', delete: 'rm' }
+}
+
+/** Fails closed like its neighbours: an unlisted or inherited key is not an action. */
+function providerActionCommand(
+  provider: ExternalAutomationProvider,
+  action: ExternalAutomationAction
+): string {
+  const commands = Object.hasOwn(PROVIDER_ACTION_COMMANDS, provider)
+    ? PROVIDER_ACTION_COMMANDS[provider]
+    : null
+  const command = commands && Object.hasOwn(commands, action) ? commands[action] : null
+  if (typeof command !== 'string') {
+    throw new Error('Unsupported external automation action.')
+  }
+  return command
+}
+
+function normalizeHermesCronMutationInput(input: ExternalAutomationCreateInput): {
+  name: string
+  prompt: string
+  schedule: string
+  workdir: string | null
+} {
+  if (input.provider !== 'hermes') {
+    throw new Error('Only Hermes cron creation and editing are supported.')
+  }
+  const name = input.name.trim()
+  const prompt = input.prompt.trim()
+  const schedule = input.schedule.trim()
+  const workdir = input.workdir?.trim() || null
+  if (!prompt) {
+    throw new Error('Hermes cron requires a prompt.')
+  }
+  if (!schedule) {
+    throw new Error('Hermes cron requires a schedule.')
+  }
+  return {
+    name: name || prompt.slice(0, 50).trim() || 'Hermes cron',
+    prompt,
+    schedule,
+    workdir
+  }
+}
+
+/** Edit args when `jobId` is given, create args otherwise; both are argv, never a shell string. */
+function hermesCronMutationArgs(
+  jobId: string | null,
+  input: { name: string; prompt: string; schedule: string; workdir: string | null }
+): string[] {
+  const args = jobId
+    ? ['cron', 'edit', jobId, '--schedule', input.schedule, '--prompt', input.prompt]
+    : ['cron', 'create', input.schedule, input.prompt]
+  args.push('--name', input.name)
+  if (!jobId) {
+    args.push('--deliver', 'local')
+  }
+  if (input.workdir) {
+    args.push('--workdir', input.workdir)
+  }
+  return args
+}
+
+export async function createExternalAutomation(
+  input: ExternalAutomationCreateInput
+): Promise<void> {
+  const normalized = normalizeHermesCronMutationInput(input)
+  if (input.target.type === 'local') {
+    await runLocalAutomationCommand('hermes', hermesCronMutationArgs(null, normalized))
+    clearHermesCronOutputRunCountCache()
+    return
+  }
+  await requireExternalAutomationMultiplexer(input.target.connectionId).request(
+    'externalAutomations.create',
+    {
+      provider: input.provider,
+      ...normalized
+    }
+  )
+}
+
+export async function updateExternalAutomation(
+  input: ExternalAutomationUpdateInput
+): Promise<void> {
+  assertExternalAutomationJobId(input.jobId)
+  const normalized = normalizeHermesCronMutationInput(input)
+  if (input.target.type === 'local') {
+    await runLocalAutomationCommand('hermes', hermesCronMutationArgs(input.jobId, normalized))
+    clearHermesCronOutputRunCountCache(input.jobId)
+    return
+  }
+  await requireExternalAutomationMultiplexer(input.target.connectionId).request(
+    'externalAutomations.update',
+    {
+      provider: input.provider,
+      jobId: input.jobId,
+      ...normalized
+    }
+  )
+}
+
+export async function runExternalAutomationAction(
+  input: ExternalAutomationActionInput
+): Promise<void> {
+  assertExternalAutomationJobId(input.jobId)
+  const command = providerActionCommand(input.provider, input.action)
+  if (input.target.type === 'local') {
+    await runLocalAutomationCommand(input.provider, ['cron', command, input.jobId])
+    if (input.provider === 'hermes') {
+      clearHermesCronOutputRunCountCache(input.jobId)
+    }
+    return
+  }
+  await requireExternalAutomationMultiplexer(input.target.connectionId).request(
+    'externalAutomations.act',
+    {
+      provider: input.provider,
+      action: input.action,
+      jobId: input.jobId
+    }
+  )
+}
diff --git a/src/main/automations/external-manager-relay.ts b/src/main/automations/external-manager-relay.ts
new file mode 100644
index 00000000000..f223c55d0b8
--- /dev/null
+++ b/src/main/automations/external-manager-relay.ts
@@ -0,0 +1,35 @@
+import { JsonRpcErrorCode } from '../ssh/relay-protocol'
+import { getActiveMultiplexer } from '../ssh/ssh-target-registry'
+
+export function requireExternalAutomationMultiplexer(
+  connectionId: string
+): NonNullable<ReturnType<typeof getActiveMultiplexer>> {
+  const mux = getActiveMultiplexer(connectionId)
+  if (!mux || mux.isDisposed()) {
+    throw new Error(`SSH target "${connectionId}" is not connected.`)
+  }
+  return mux
+}
+
+/**
+ * True only for a structured JSON-RPC `-32601`, never for error prose.
+ *
+ * A `-32601` object means the peer parsed the request and declined the method,
+ * so it is positive evidence the connection is healthy. Matching the words
+ * "method not found" instead would let a genuinely broken relay be reported as
+ * a missing capability, hiding a dead connection behind a capability notice.
+ */
+export function isRelayMethodNotFoundError(error: unknown): boolean {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    (error as { code?: unknown }).code === JsonRpcErrorCode.MethodNotFound
+  )
+}
+
+export function externalAutomationRelayErrorMessage(error: unknown): string {
+  if (isRelayMethodNotFoundError(error)) {
+    return 'Remote relay does not support external automation management. Reconnect the SSH target to deploy the latest relay.'
+  }
+  return error instanceof Error ? error.message : String(error)
+}
diff --git a/src/main/automations/external-manager-runs.ts b/src/main/automations/external-manager-runs.ts
new file mode 100644
index 00000000000..ebb0b0b6dde
--- /dev/null
+++ b/src/main/automations/external-manager-runs.ts
@@ -0,0 +1,81 @@
+import type {
+  ExternalAutomationProvider,
+  ExternalAutomationRunsInput,
+  ExternalAutomationRunsPage
+} from '../../shared/automations-types'
+import {
+  EXTERNAL_AUTOMATION_SCOPE_CODES,
+  ExternalAutomationScopeError
+} from '../../shared/external-automation-scope'
+import { mapHermesJobs } from './external-job-mappers'
+import { assertExternalAutomationJobId } from './external-manager-job-id'
+import {
+  isRelayMethodNotFoundError,
+  requireExternalAutomationMultiplexer
+} from './external-manager-relay'
+import { readHermesCronOutputRunsPage } from './hermes-cron-output'
+
+/**
+ * Runs the relay's paged runs call, translating "no such method" into a code the
+ * renderer can act on.
+ *
+ * The structured code exists only here: Electron IPC preserves nothing but the
+ * message, so a renderer that re-derived this from the host's prose would be
+ * guessing. Translating at the boundary that can still see the code is what lets
+ * the caller fall back to job-carried runs without matching free text.
+ */
+async function requestRemoteExternalRuns(
+  connectionId: string,
+  params: { provider: ExternalAutomationProvider; jobId: string; page: number; pageSize: number }
+): Promise<{ total?: number; runs?: unknown[] }> {
+  try {
+    return (await requireExternalAutomationMultiplexer(connectionId).request(
+      'externalAutomations.runs',
+      params
+    )) as {
+      total?: number
+      runs?: unknown[]
+    }
+  } catch (error) {
+    if (isRelayMethodNotFoundError(error)) {
+      throw new ExternalAutomationScopeError(EXTERNAL_AUTOMATION_SCOPE_CODES.runsUnsupported)
+    }
+    throw error
+  }
+}
+
+export async function listExternalAutomationRuns(
+  input: ExternalAutomationRunsInput
+): Promise<ExternalAutomationRunsPage> {
+  assertExternalAutomationJobId(input.jobId)
+  const page = Number.isFinite(input.page) ? Math.max(1, Math.floor(input.page)) : 1
+  const pageSize = Number.isFinite(input.pageSize)
+    ? Math.min(100, Math.max(1, Math.floor(input.pageSize)))
+    : 25
+  const identity = {
+    managerId: input.managerId,
+    provider: input.provider,
+    target: input.target,
+    jobId: input.jobId,
+    page,
+    pageSize
+  }
+  if (input.provider !== 'hermes') {
+    return { ...identity, total: 0, runs: [] }
+  }
+  const result =
+    input.target.type === 'local'
+      ? await readHermesCronOutputRunsPage(input.jobId, { page, pageSize })
+      : await requestRemoteExternalRuns(input.target.connectionId, {
+          provider: input.provider,
+          jobId: input.jobId,
+          page,
+          pageSize
+        })
+  return {
+    ...identity,
+    total: typeof result.total === 'number' && Number.isFinite(result.total) ? result.total : 0,
+    runs:
+      mapHermesJobs(input.managerId, [{ id: input.jobId, runs: result.runs ?? [] }])[0]?.runs ?? []
+  }
+}
diff --git a/src/main/automations/external-manager.ts b/src/main/automations/external-manager.ts
index 0905f1943de..d1adeb3e83c 100644
--- a/src/main/automations/external-manager.ts
+++ b/src/main/automations/external-manager.ts
@@ -1,34 +1,16 @@
-/* eslint-disable max-lines -- Why: external automation discovery, pagination,
- * and lifecycle routing share provider/target validation and remote relay fallbacks. */
-import { existsSync } from 'node:fs'
-import { readFile } from 'node:fs/promises'
-import { homedir } from 'node:os'
-import { join } from 'node:path'
-import { runProcess } from '../../shared/child-process/run-process'
 import type {
-  ExternalAutomationAction,
-  ExternalAutomationActionInput,
   ExternalAutomationCreateInput,
-  ExternalAutomationManager,
-  ExternalAutomationProvider,
-  ExternalAutomationRunsInput,
-  ExternalAutomationRunsPage,
-  ExternalAutomationUpdateInput
+  ExternalAutomationRunsPage
 } from '../../shared/automations-types'
-import {
-  EXTERNAL_AUTOMATION_SCOPE_CODES,
-  ExternalAutomationScopeError,
-  type ScopedExternalAutomationRequest,
-  type ScopedExternalManagerActionRequest,
-  type ScopedExternalManagerCreateRequest,
-  type ScopedExternalManagerListRequest,
-  type ScopedExternalManagerMutationFields,
-  type ScopedExternalManagerRunsRequest,
-  type ScopedExternalManagerUpdateRequest
+import type {
+  ScopedExternalAutomationRequest,
+  ScopedExternalManagerActionRequest,
+  ScopedExternalManagerCreateRequest,
+  ScopedExternalManagerListRequest,
+  ScopedExternalManagerMutationFields,
+  ScopedExternalManagerRunsRequest,
+  ScopedExternalManagerUpdateRequest
 } from '../../shared/external-automation-scope'
-import type { SshTarget } from '../../shared/ssh-types'
-import { getActiveMultiplexer } from '../ssh/ssh-target-registry'
-import { JsonRpcErrorCode } from '../ssh/relay-protocol'
 import {
   resolveExternalAutomationScope,
   type DesktopSshTargetRegistry,
@@ -40,423 +22,19 @@ import {
   type ExternalAutomationManagerCacheEntry
 } from './external-automation-manager-cache'
 import type { ExternalAutomationProbeScheduler } from './external-automation-probe-scheduler'
-import { mapHermesJobs, mapOpenClawJobs } from './external-job-mappers'
+import { listLocalManager, listRemoteManager } from './external-manager-discovery'
 import {
-  clearHermesCronOutputRunCountCache,
-  readHermesCronOutputRunsPage
-} from './hermes-cron-output'
+  createExternalAutomation,
+  runExternalAutomationAction,
+  updateExternalAutomation
+} from './external-manager-mutations'
+import { listExternalAutomationRuns } from './external-manager-runs'
 
-const HERMES_HOME = process.env.HERMES_HOME?.trim() || join(homedir(), '.hermes')
-const HERMES_CRON_DIR = join(HERMES_HOME, 'cron')
-const HERMES_JOBS_FILE = join(HERMES_CRON_DIR, 'jobs.json')
-const OPENCLAW_JOBS_FILE = join(homedir(), '.openclaw', 'cron', 'jobs.json')
-const EXTERNAL_JOB_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/
-const LOCAL_COMMAND_LOOKUP_TIMEOUT_MS = 5_000
-const LOCAL_AUTOMATION_COMMAND_TIMEOUT_MS = 30_000
-const PROVIDER_LABELS: Record<ExternalAutomationProvider, string> = {
-  hermes: 'Hermes',
-  openclaw: 'OpenClaw'
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
-
-function runLocalProviderCommand(
-  command: string,
-  args: string[],
-  options: { timeoutMs: number; timeoutMessage: string }
-): Promise<void> {
-  return runProcess({ program: command, args, timeoutMs: options.timeoutMs }).then((result) => {
-    if (result.timedOut) {
-      throw new Error(options.timeoutMessage)
-    }
-    if (result.code !== 0) {
-      throw new Error(
-        result.stderr.trim() || `Command exited with code ${result.code ?? 'unknown'}.`
-      )
-    }
-  })
-}
-
-async function isCommandOnPath(command: string): Promise<boolean> {
-  const finder = process.platform === 'win32' ? 'where' : 'which'
-  try {
-    // Why: these probes run while loading Automations; a wedged PATH shim must
-    // not keep the list IPC pending forever.
-    await runLocalProviderCommand(finder, [command], {
-      timeoutMs: LOCAL_COMMAND_LOOKUP_TIMEOUT_MS,
-      timeoutMessage: `Command lookup timed out after ${LOCAL_COMMAND_LOOKUP_TIMEOUT_MS}ms.`
-    })
-    return true
-  } catch {
-    return false
-  }
-}
-
-// Why: local automation mutations back UI actions; a wedged CLI must not keep
-// create/edit/run/delete pending after Node signals a timeout.
-function runLocalAutomationCommand(command: string, args: string[]): Promise<void> {
-  return runLocalProviderCommand(command, args, {
-    timeoutMs: LOCAL_AUTOMATION_COMMAND_TIMEOUT_MS,
-    timeoutMessage: `Local automation command timed out after ${LOCAL_AUTOMATION_COMMAND_TIMEOUT_MS}ms.`
-  })
-}
-
-async function readLocalHermesJobs(): Promise<unknown[]> {
-  if (!existsSync(HERMES_JOBS_FILE)) {
-    return []
-  }
-  const content = await readFile(HERMES_JOBS_FILE, 'utf-8')
-  const parsed = JSON.parse(content) as unknown
-  const jobs = Array.isArray(parsed)
-    ? parsed
-    : isRecord(parsed) && Array.isArray(parsed.jobs)
-      ? parsed.jobs
-      : []
-  return Promise.all(
-    jobs.map(async (job) => {
-      if (!isRecord(job)) {
-        return job
-      }
-      const jobId = typeof job.id === 'string' ? job.id : null
-      if (!jobId) {
-        return job
-      }
-      const runsPage = await readHermesCronOutputRunsPage(jobId, { page: 1, pageSize: 0 })
-      return {
-        ...job,
-        run_count: runsPage.total,
-        runs: []
-      }
-    })
-  )
-}
-
-async function readLocalOpenClawJobs(): Promise<unknown[]> {
-  if (!existsSync(OPENCLAW_JOBS_FILE)) {
-    return []
-  }
-  const content = await readFile(OPENCLAW_JOBS_FILE, 'utf-8')
-  const parsed = JSON.parse(content) as unknown
-  return isRecord(parsed) && Array.isArray(parsed.jobs) ? parsed.jobs : []
-}
-
-function mapProviderJobs(
-  provider: ExternalAutomationProvider,
-  managerId: string,
-  jobs: unknown[]
-): ExternalAutomationManager['jobs'] {
-  return provider === 'hermes' ? mapHermesJobs(managerId, jobs) : mapOpenClawJobs(managerId, jobs)
-}
-
-async function listLocalManager(
-  provider: ExternalAutomationProvider
-): Promise<ExternalAutomationManager | null> {
-  const [availableResult, jobsResult] = await Promise.allSettled([
-    isCommandOnPath(provider),
-    provider === 'hermes' ? readLocalHermesJobs() : readLocalOpenClawJobs()
-  ])
-  const available = availableResult.status === 'fulfilled' && availableResult.value
-  const jobs = jobsResult.status === 'fulfilled' ? jobsResult.value : []
-  const readError = jobsResult.status === 'rejected' ? String(jobsResult.reason) : null
-  if (!available && jobs.length === 0 && !readError) {
-    return null
-  }
-  const managerId = `${provider}:local`
-  const providerLabel = PROVIDER_LABELS[provider]
-  return {
-    id: managerId,
-    provider,
-    label: `${providerLabel} on this computer`,
-    targetLabel: 'this computer',
-    target: { type: 'local' },
-    status: readError ? 'unavailable' : 'available',
-    error:
-      readError ??
-      (available
-        ? null
-        : `${providerLabel} jobs were found, but the ${provider} CLI is not on PATH.`),
-    canManage: !readError && available,
-    jobs: mapProviderJobs(provider, managerId, jobs)
-  }
-}
-
-function requireMultiplexer(
-  connectionId: string
-): NonNullable<ReturnType<typeof getActiveMultiplexer>> {
-  const mux = getActiveMultiplexer(connectionId)
-  if (!mux || mux.isDisposed()) {
-    throw new Error(`SSH target "${connectionId}" is not connected.`)
-  }
-  return mux
-}
-
-/**
- * True only for a structured JSON-RPC `-32601`, never for error prose.
- *
- * A `-32601` object means the peer parsed the request and declined the method,
- * so it is positive evidence the connection is healthy. Matching the words
- * "method not found" instead would let a genuinely broken relay be reported as
- * a missing capability, hiding a dead connection behind a capability notice.
- */
-function isRelayMethodNotFoundError(error: unknown): boolean {
-  return (
-    typeof error === 'object' &&
-    error !== null &&
-    (error as { code?: unknown }).code === JsonRpcErrorCode.MethodNotFound
-  )
-}
-
-function remoteRelayErrorMessage(error: unknown): string {
-  if (isRelayMethodNotFoundError(error)) {
-    return 'Remote relay does not support external automation management. Reconnect the SSH target to deploy the latest relay.'
-  }
-  return error instanceof Error ? error.message : String(error)
-}
-
-async function listRemoteManager(
-  target: SshTarget,
-  provider: ExternalAutomationProvider
-): Promise<ExternalAutomationManager> {
-  const providerLabel = PROVIDER_LABELS[provider]
-  const managerProviderId = `${provider}:ssh:${target.id}`
-  const mux = getActiveMultiplexer(target.id)
-  if (!mux || mux.isDisposed()) {
-    return {
-      id: managerProviderId,
-      provider,
-      label: `${providerLabel} on ${target.label}`,
-      targetLabel: target.label,
-      target: { type: 'ssh', connectionId: target.id },
-      status: 'unavailable',
-      error: 'SSH target is not connected.',
-      canManage: false,
-      jobs: []
-    }
-  }
-  try {
-    const result = (await mux.request('externalAutomations.list', { provider })) as {
-      jobs?: unknown[]
-      hermesAvailable?: boolean
-      openclawAvailable?: boolean
-      error?: string | null
-    }
-    const commandAvailable =
-      provider === 'hermes' ? result.hermesAvailable === true : result.openclawAvailable === true
-    const readError = result.error ?? null
-    return {
-      id: managerProviderId,
-      provider,
-      label: `${providerLabel} on ${target.label}`,
-      targetLabel: target.label,
-      target: { type: 'ssh', connectionId: target.id },
-      status: readError ? 'unavailable' : 'available',
-      error:
-        readError ?? (commandAvailable ? null : `${providerLabel} CLI is not on the remote PATH.`),
-      canManage: !readError && commandAvailable,
-      jobs: mapProviderJobs(provider, managerProviderId, result.jobs ?? [])
-    }
-  } catch (error) {
-    return {
-      id: managerProviderId,
-      provider,
-      label: `${providerLabel} on ${target.label}`,
-      targetLabel: target.label,
-      target: { type: 'ssh', connectionId: target.id },
-      status: 'unavailable',
-      error: remoteRelayErrorMessage(error),
-      canManage: false,
-      jobs: []
-    }
-  }
-}
-
-/**
- * Runs the relay's paged runs call, translating "no such method" into a code the
- * renderer can act on.
- *
- * The structured code exists only here: Electron IPC preserves nothing but the
- * message, so a renderer that re-derived this from the host's prose would be
- * guessing. Translating at the boundary that can still see the code is what lets
- * the caller fall back to job-carried runs without matching free text.
- */
-async function requestRemoteExternalRuns(
-  connectionId: string,
-  params: { provider: ExternalAutomationProvider; jobId: string; page: number; pageSize: number }
-): Promise<{ total?: number; runs?: unknown[] }> {
-  try {
-    return (await requireMultiplexer(connectionId).request('externalAutomations.runs', params)) as {
-      total?: number
-      runs?: unknown[]
-    }
-  } catch (error) {
-    if (isRelayMethodNotFoundError(error)) {
-      throw new ExternalAutomationScopeError(EXTERNAL_AUTOMATION_SCOPE_CODES.runsUnsupported)
-    }
-    throw error
-  }
-}
-
-export async function listExternalAutomationRuns(
-  input: ExternalAutomationRunsInput
-): Promise<ExternalAutomationRunsPage> {
-  if (!EXTERNAL_JOB_ID_PATTERN.test(input.jobId)) {
-    throw new Error('Invalid external automation job ID.')
-  }
-  const page = Number.isFinite(input.page) ? Math.max(1, Math.floor(input.page)) : 1
-  const pageSize = Number.isFinite(input.pageSize)
-    ? Math.min(100, Math.max(1, Math.floor(input.pageSize)))
-    : 25
-  const identity = {
-    managerId: input.managerId,
-    provider: input.provider,
-    target: input.target,
-    jobId: input.jobId,
-    page,
-    pageSize
-  }
-  if (input.provider !== 'hermes') {
-    return { ...identity, total: 0, runs: [] }
-  }
-  const result =
-    input.target.type === 'local'
-      ? await readHermesCronOutputRunsPage(input.jobId, { page, pageSize })
-      : await requestRemoteExternalRuns(input.target.connectionId, {
-          provider: input.provider,
-          jobId: input.jobId,
-          page,
-          pageSize
-        })
-  return {
-    ...identity,
-    total: typeof result.total === 'number' && Number.isFinite(result.total) ? result.total : 0,
-    runs:
-      mapHermesJobs(input.managerId, [{ id: input.jobId, runs: result.runs ?? [] }])[0]?.runs ?? []
-  }
-}
-
-const PROVIDER_ACTION_COMMANDS: Record<
-  ExternalAutomationProvider,
-  Record<ExternalAutomationAction, string>
-> = {
-  hermes: { pause: 'pause', resume: 'resume', run: 'run', delete: 'remove' },
-  openclaw: { pause: 'disable', resume: 'enable', run: 'run', delete: 'rm' }
-}
-
-/** Fails closed like its neighbours: an unlisted or inherited key is not an action. */
-function providerActionCommand(
-  provider: ExternalAutomationProvider,
-  action: ExternalAutomationAction
-): string {
-  const commands = Object.hasOwn(PROVIDER_ACTION_COMMANDS, provider)
-    ? PROVIDER_ACTION_COMMANDS[provider]
-    : null
-  const command = commands && Object.hasOwn(commands, action) ? commands[action] : null
-  if (typeof command !== 'string') {
-    throw new Error('Unsupported external automation action.')
-  }
-  return command
-}
-
-function normalizeHermesCronMutationInput(input: ExternalAutomationCreateInput): {
-  name: string
-  prompt: string
-  schedule: string
-  workdir: string | null
-} {
-  if (input.provider !== 'hermes') {
-    throw new Error('Only Hermes cron creation and editing are supported.')
-  }
-  const name = input.name.trim()
-  const prompt = input.prompt.trim()
-  const schedule = input.schedule.trim()
-  const workdir = input.workdir?.trim() || null
-  if (!prompt) {
-    throw new Error('Hermes cron requires a prompt.')
-  }
-  if (!schedule) {
-    throw new Error('Hermes cron requires a schedule.')
-  }
-  return {
-    name: name || prompt.slice(0, 50).trim() || 'Hermes cron',
-    prompt,
-    schedule,
-    workdir
-  }
-}
-
-/** Edit args when `jobId` is given, create args otherwise; both are argv, never a shell string. */
-function hermesCronMutationArgs(
-  jobId: string | null,
-  input: { name: string; prompt: string; schedule: string; workdir: string | null }
-): string[] {
-  const args = jobId
-    ? ['cron', 'edit', jobId, '--schedule', input.schedule, '--prompt', input.prompt]
-    : ['cron', 'create', input.schedule, input.prompt]
-  args.push('--name', input.name)
-  if (!jobId) {
-    args.push('--deliver', 'local')
-  }
-  if (input.workdir) {
-    args.push('--workdir', input.workdir)
-  }
-  return args
-}
-
-export async function createExternalAutomation(
-  input: ExternalAutomationCreateInput
-): Promise<void> {
-  const normalized = normalizeHermesCronMutationInput(input)
-  if (input.target.type === 'local') {
-    await runLocalAutomationCommand('hermes', hermesCronMutationArgs(null, normalized))
-    clearHermesCronOutputRunCountCache()
-    return
-  }
-  await requireMultiplexer(input.target.connectionId).request('externalAutomations.create', {
-    provider: input.provider,
-    ...normalized
-  })
-}
-
-export async function updateExternalAutomation(
-  input: ExternalAutomationUpdateInput
-): Promise<void> {
-  if (!EXTERNAL_JOB_ID_PATTERN.test(input.jobId)) {
-    throw new Error('Invalid external automation job ID.')
-  }
-  const normalized = normalizeHermesCronMutationInput(input)
-  if (input.target.type === 'local') {
-    await runLocalAutomationCommand('hermes', hermesCronMutationArgs(input.jobId, normalized))
-    clearHermesCronOutputRunCountCache(input.jobId)
-    return
-  }
-  await requireMultiplexer(input.target.connectionId).request('externalAutomations.update', {
-    provider: input.provider,
-    jobId: input.jobId,
-    ...normalized
-  })
-}
-
-export async function runExternalAutomationAction(
-  input: ExternalAutomationActionInput
-): Promise<void> {
-  if (!EXTERNAL_JOB_ID_PATTERN.test(input.jobId)) {
-    throw new Error('Invalid external automation job ID.')
-  }
-  const command = providerActionCommand(input.provider, input.action)
-  if (input.target.type === 'local') {
-    await runLocalAutomationCommand(input.provider, ['cron', command, input.jobId])
-    if (input.provider === 'hermes') {
-      clearHermesCronOutputRunCountCache(input.jobId)
-    }
-    return
-  }
-  await requireMultiplexer(input.target.connectionId).request('externalAutomations.act', {
-    provider: input.provider,
-    action: input.action,
-    jobId: input.jobId
-  })
+export {
+  createExternalAutomation,
+  listExternalAutomationRuns,
+  runExternalAutomationAction,
+  updateExternalAutomation
 }
 
 export type ScopedExternalAutomationDeps = {

From ecee14bdbc9b1a97be191ad4a2cc18c54325c767 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sat, 29 Aug 2026 20:08:08 -0700
Subject: [PATCH 27/31] Split main window service attachments (#17151)

* Split speech session lifecycle

* Split terminal output scheduler pipeline

* Split mobile browser pane modules

* Prune resolved max-lines suppressions

* Split pane tree equalization logic

* Extract mobile troubleshoot screen styles

* Split external automation manager

* Split main window service attachments

* Fix F3-speech for #17123

* Fix F1-cycle for #17131
---
 config/max-lines-baseline.txt                 |   1 -
 .../window/attach-main-window-services.ts     | 364 +-----------------
 src/main/window/main-window-updater.ts        | 135 +++++++
 src/main/window/runtime-window-lifecycle.ts   | 239 ++++++++++++
 4 files changed, 380 insertions(+), 359 deletions(-)
 create mode 100644 src/main/window/main-window-updater.ts
 create mode 100644 src/main/window/runtime-window-lifecycle.ts

diff --git a/config/max-lines-baseline.txt b/config/max-lines-baseline.txt
index 83c550911ee..7870a1bf8b2 100644
--- a/config/max-lines-baseline.txt
+++ b/config/max-lines-baseline.txt
@@ -32,7 +32,6 @@ inline src/main/ssh/ssh-connection.ts
 inline src/main/ssh/ssh-relay-deploy.ts
 inline src/main/ssh/ssh-relay-session.ts
 inline src/main/updater.ts
-inline src/main/window/attach-main-window-services.ts
 inline src/preload/index.ts
 inline src/relay/dispatcher.ts
 inline src/relay/git-handler.ts
diff --git a/src/main/window/attach-main-window-services.ts b/src/main/window/attach-main-window-services.ts
index 5910a001649..128ff2e0e4e 100644
--- a/src/main/window/attach-main-window-services.ts
+++ b/src/main/window/attach-main-window-services.ts
@@ -1,13 +1,6 @@
-/* eslint-disable max-lines -- Why: this file is the central main-window IPC wiring point; splitting it during the mobile release compatibility rebase would increase release risk. */
-import { randomUUID } from 'node:crypto'
-
-import { app, ipcMain } from 'electron'
+import { ipcMain } from 'electron'
 import type { BrowserWindow, IpcMainInvokeEvent } from 'electron'
 import type { Store } from '../persistence'
-import type { ReleaseBuildListResult, UpdateCheckOptions } from '../../shared/update-status-types'
-import type { CreateWorktreeResult } from '../../shared/worktree/create-types'
-import type { WorktreeStartupLaunch } from '../../shared/worktree/launch-types'
-import { RELEASE_CHANNELS, type ReleaseChannel } from '../../shared/release-channel'
 import {
   acknowledgePendingTccPromptNotice,
   consumePendingTccPromptNotice,
@@ -32,60 +25,27 @@ import { registerRemoteWorkspaceHandlers } from '../ipc/remote-workspace'
 import { browserManager } from '../browser/browser-manager'
 import { hasSystemMediaAccess, requestSystemMediaAccess } from '../browser/browser-media-access'
 import type { OrcaRuntimeService, RuntimeWorktreeLifecycleEvent } from '../runtime/orca-runtime'
-import {
-  checkForUpdatesFromMenu,
-  downloadUpdate,
-  getLinuxPackageInstallInstructions,
-  getUpdateStatus,
-  quitAndInstall,
-  setupAutoUpdater,
-  showLinuxPackage,
-  dismissAvailableUpdate,
-  dismissNudge,
-  listAvailableReleaseBuilds,
-  type UpdateInstallMode
-} from '../updater'
-import { isTrustedUIRenderer } from '../ipc/ui'
+import type { UpdateInstallMode } from '../updater'
 import { scheduleHistoryGc } from '../terminal-history-gc'
 import { hydrateLocalPtyRegistryAtBoot } from '../memory/hydrate-local-pty-registry'
 import type { ClaudeRuntimeAuthPreparation } from '../claude-accounts/runtime-auth-service'
 import { getKnownWorktreeIdsForHistoryGc } from './history-gc-worktree-ids'
-import type {
-  RuntimeMarkdownReadTabResult,
-  RuntimeMarkdownSaveTabResult
-} from '../../shared/mobile-markdown-document'
-import type { RuntimeMobileSessionTabMove } from '../../shared/runtime-types'
-import type { TerminalTabCreateReply } from '../../shared/terminal-reveal-identity'
 import { isNativeFileDropPayload, type NativeFileDropPayload } from '../../shared/native-file-drop'
-import { requestMobileMarkdownFromRenderer } from './mobile-markdown-request-relay'
-import { requestSessionTabCloseFromRenderer } from './session-tab-close-request-relay'
-import { requestTerminalTabCloseFromRenderer } from './terminal-tab-close-request-relay'
 import type { ClaudeAccountSelectionTarget } from '../claude-accounts/runtime-selection'
-import { runWorktreeChangeInvalidators } from '../ipc/worktree-change-invalidators'
 import {
   scheduleWorktreeBaseDirectoryWatcherSync,
   setWorktreeBaseDirectoryWatcherSyncContext
 } from '../ipc/worktree-base-directory-watcher'
 import { startFolderRepoGitUpgradeWatch } from '../ipc/folder-repo-git-upgrade'
-import { logStartupMilestone } from '../startup/startup-diagnostics'
-import { createRuntimeRendererNotificationSender } from './runtime-renderer-notification-sender'
-import { registerRendererDocumentNavigation } from './renderer-document-navigation'
+import { scheduleMainWindowAutoUpdaterSetup } from './main-window-updater'
+import { registerRuntimeWindowLifecycle } from './runtime-window-lifecycle'
 
-const UPDATER_SETUP_FALLBACK_MS = 15_000
-
-// Why: a manual check can arrive before deferred setup runs, so entry points force this pending setup to configure the updater first.
-let pendingAutoUpdaterSetup: (() => void) | null = null
-
-export function ensureAutoUpdaterConfigured(): void {
-  pendingAutoUpdaterSetup?.()
-}
+export { ensureAutoUpdaterConfigured, registerUpdaterHandlers } from './main-window-updater'
 
 let appReloadHandlerTokenCounter = 0
 let activeAppReloadHandlerToken: number | null = null
 let tccPromptHandlerTokenCounter = 0
 let activeTccPromptHandlerToken: number | null = null
-let runtimeNotifierTokenCounter = 0
-let activeRuntimeNotifierToken: number | null = null
 
 export function attachMainWindowServices(
   mainWindow: BrowserWindow,
@@ -163,47 +123,7 @@ export function attachMainWindowServices(
   registerRemoteWorkspaceHandlers(store, () => mainWindow)
   registerFileDropRelay(mainWindow)
   registerTccPromptNoticeHandlers(mainWindow)
-  // Why: setupAutoUpdater sync-require()s electron-updater (slow on cold Windows w/ Defender, #7225), so defer past first paint; timer fallback covers crash-looping renderers.
-  let updaterSetupDone = false
-  const setupAutoUpdaterDeferred = (): void => {
-    if (updaterSetupDone || mainWindow.isDestroyed()) {
-      return
-    }
-    updaterSetupDone = true
-    setupAutoUpdater(mainWindow, {
-      getLastUpdateCheckAt: () => store.getUI().lastUpdateCheckAt,
-      onBeforeQuit: async () => {
-        try {
-          await options?.onBeforeUpdateQuit?.()
-        } finally {
-          await store.flushPendingAsync()
-        }
-      },
-      setLastUpdateCheckAt: (timestamp) => {
-        store.updateUI({ lastUpdateCheckAt: timestamp })
-      },
-      getPendingUpdateNudgeId: () => store.getUI().pendingUpdateNudgeId ?? null,
-      getDismissedUpdateNudgeId: () => store.getUI().dismissedUpdateNudgeId ?? null,
-      setPendingUpdateNudgeId: (id) => {
-        // Why: only the apply branch also nulls dismissedUpdateVersion so relaunch can't resurrect the old hidden card; clearing must not, or it un-dismisses.
-        if (id) {
-          store.updateUI({ pendingUpdateNudgeId: id, dismissedUpdateVersion: null })
-        } else {
-          store.updateUI({ pendingUpdateNudgeId: null })
-        }
-      },
-      setDismissedUpdateNudgeId: (id) => {
-        store.updateUI({ dismissedUpdateNudgeId: id })
-      },
-      getReleaseChannelOverride: () => store.getUI().releaseChannelOverride ?? null,
-      installMode: options?.updateInstallMode
-    })
-    logStartupMilestone('updater-setup-done')
-  }
-  pendingAutoUpdaterSetup = setupAutoUpdaterDeferred
-  mainWindow.once('ready-to-show', () => setImmediate(setupAutoUpdaterDeferred))
-  const updaterSetupFallback = setTimeout(setupAutoUpdaterDeferred, UPDATER_SETUP_FALLBACK_MS)
-  updaterSetupFallback.unref?.()
+  scheduleMainWindowAutoUpdaterSetup(mainWindow, store, options)
   registerRuntimeWindowLifecycle(mainWindow, runtime)
 
   const allowedPermissions = new Set(['media', 'fullscreen', 'pointerLock'])
@@ -321,223 +241,6 @@ function registerAppReloadHandler(
   })
 }
 
-function registerRuntimeWindowLifecycle(
-  mainWindow: BrowserWindow,
-  runtime: OrcaRuntimeService
-): void {
-  const notifierToken = ++runtimeNotifierTokenCounter
-  activeRuntimeNotifierToken = notifierToken
-  runtime.attachWindow(mainWindow.id)
-  const mainWebContents = mainWindow.webContents
-  const rendererNotifications = createRuntimeRendererNotificationSender({
-    isWindowDestroyed: () => mainWindow.isDestroyed(),
-    webContents: mainWebContents,
-    onFailure: (reason) => runtime.markGraphReloadFailed(mainWindow.id, reason)
-  })
-  const send = rendererNotifications.send
-  runtime.setNotifier({
-    worktreesChanged: (repoId, renamed) => {
-      // Why: clear scan caches before the renderer handles this event, so it can't read stale TTL entries after a mutation.
-      runWorktreeChangeInvalidators(repoId)
-      send('worktrees:changed', renamed ? { repoId, renamed } : { repoId })
-    },
-    worktreeBaseStatus: (event) => send('worktree:baseStatus', event),
-    worktreeRemoteBranchConflict: (event) => send('worktree:remoteBranchConflict', event),
-    reposChanged: () => send('repos:changed'),
-    automationsChanged: (payload) => send('automations:changed', payload),
-    activateWorktree: (
-      repoId,
-      worktreeId,
-      setup?: CreateWorktreeResult['setup'],
-      startup?: WorktreeStartupLaunch,
-      defaultTabs?: CreateWorktreeResult['defaultTabs']
-    ) => {
-      send('ui:activateWorktree', {
-        repoId,
-        worktreeId,
-        ...(setup ? { setup } : {}),
-        ...(startup ? { startup } : {}),
-        ...(defaultTabs ? { defaultTabs } : {})
-      })
-    },
-    createTerminal: (worktreeId, opts) =>
-      send('ui:createTerminal', {
-        worktreeId,
-        command: opts.command,
-        ...(opts.cwd ? { cwd: opts.cwd } : {}),
-        ...(opts.env ? { env: opts.env } : {}),
-        title: opts.title,
-        ...(opts.presentation ? { presentation: opts.presentation } : {})
-      }),
-    revealTerminalSession: (worktreeId, opts) =>
-      new Promise((resolve, reject) => {
-        const requestId = randomUUID()
-        const expectedIdentity = opts.expectedProcessIdentity
-          ? opts.tabId && opts.leafId
-            ? { worktreeId, tabId: opts.tabId, leafId: opts.leafId, ptyId: opts.ptyId }
-            : null
-          : undefined
-        if (expectedIdentity === null) {
-          reject(new Error('terminal_reveal_identity_required'))
-          return
-        }
-        const timer = setTimeout(() => {
-          ipcMain.removeListener('terminal:tabCreateReply', handler)
-          reject(new Error('Terminal reveal timed out'))
-        }, 10_000)
-        const handler = (event: Electron.IpcMainEvent, reply: TerminalTabCreateReply): void => {
-          // Why: requestId is renderer-supplied, so only the targeted main window may satisfy the reveal.
-          if (event.sender !== mainWindow.webContents || reply.requestId !== requestId) {
-            return
-          }
-          clearTimeout(timer)
-          ipcMain.removeListener('terminal:tabCreateReply', handler)
-          if (reply.error) {
-            reject(new Error(reply.error))
-            return
-          }
-          if (
-            expectedIdentity &&
-            (!reply.identity ||
-              reply.identity.worktreeId !== expectedIdentity.worktreeId ||
-              reply.identity.tabId !== expectedIdentity.tabId ||
-              reply.identity.leafId !== expectedIdentity.leafId ||
-              reply.identity.ptyId !== expectedIdentity.ptyId)
-          ) {
-            reject(new Error('terminal_reveal_identity_mismatch'))
-            return
-          }
-          resolve({
-            tabId: reply.tabId!,
-            title: reply.title,
-            ...(reply.identity ? { identity: reply.identity } : {})
-          })
-        }
-        ipcMain.on('terminal:tabCreateReply', handler)
-        const sent = send('ui:createTerminal', {
-          requestId,
-          worktreeId,
-          ptyId: opts.ptyId,
-          title: opts.title ?? undefined,
-          ...(opts.cwd ? { cwd: opts.cwd } : {}),
-          ...(opts.launchConfig ? { launchConfig: opts.launchConfig } : {}),
-          ...(opts.launchToken ? { launchToken: opts.launchToken } : {}),
-          ...(opts.launchAgent ? { launchAgent: opts.launchAgent } : {}),
-          ...(opts.viewMode ? { viewMode: opts.viewMode } : {}),
-          activate: opts.activate !== false,
-          ...(opts.presentation ? { presentation: opts.presentation } : {}),
-          ...(opts.surfaceOwner === false ? { surfaceOwner: false } : {}),
-          // Why: pre-minted tabId aligns the renderer tab id with the paneKey baked into the PTY env, so hook events route right.
-          ...(opts.tabId !== undefined ? { tabId: opts.tabId } : {}),
-          ...(opts.leafId !== undefined ? { leafId: opts.leafId } : {}),
-          ...(opts.splitFromLeafId !== undefined ? { splitFromLeafId: opts.splitFromLeafId } : {}),
-          ...(opts.splitDirection !== undefined ? { splitDirection: opts.splitDirection } : {}),
-          ...(opts.splitTelemetrySource !== undefined
-            ? { splitTelemetrySource: opts.splitTelemetrySource }
-            : {}),
-          ...(opts.focus !== undefined ? { focus: opts.focus } : {})
-        })
-        if (!sent) {
-          clearTimeout(timer)
-          ipcMain.removeListener('terminal:tabCreateReply', handler)
-          reject(new Error('runtime_unavailable'))
-        }
-      }),
-    resolveLegacyWorkerTerminalRecovery: (paneKey, resolution, ptyId) =>
-      send('agentStatus:legacyWorkerTerminalRecovery', {
-        paneKey,
-        resolution,
-        ...(ptyId ? { ptyId } : {})
-      }),
-    splitTerminal: (tabId, paneRuntimeId, opts) => {
-      send('ui:splitTerminal', {
-        tabId,
-        paneRuntimeId,
-        direction: opts.direction,
-        command: opts.command,
-        telemetrySource: opts.telemetrySource
-      })
-    },
-    renameTerminal: (tabId, title) => send('ui:renameTerminal', { tabId, title }),
-    focusTerminal: (tabId, worktreeId, leafId) =>
-      send('ui:focusTerminal', { tabId, worktreeId, leafId }),
-    focusEditorTab: (tabId, worktreeId) => send('ui:focusEditorTab', { tabId, worktreeId }),
-    closeSessionTab: (tabId, worktreeId) =>
-      requestSessionTabCloseFromRenderer(mainWindow, tabId, worktreeId),
-    moveSessionTab: (worktreeId: string, move: RuntimeMobileSessionTabMove) =>
-      send('ui:moveSessionTab', { worktreeId, ...move }),
-    openFile: (worktreeId, filePath, relativePath, runtimeEnvironmentId?) =>
-      send('ui:openFileFromMobile', {
-        worktreeId,
-        filePath,
-        relativePath,
-        runtimeEnvironmentId
-      }),
-    openDiff: (worktreeId, filePath, relativePath, staged, runtimeEnvironmentId?) =>
-      send('ui:openDiffFromMobile', {
-        worktreeId,
-        filePath,
-        relativePath,
-        staged,
-        runtimeEnvironmentId
-      }),
-    readMobileMarkdownTab: (worktreeId, tabId) =>
-      requestMobileMarkdownFromRenderer(mainWindow, {
-        operation: 'read',
-        worktreeId,
-        tabId
-      }) as Promise<RuntimeMarkdownReadTabResult>,
-    saveMobileMarkdownTab: (worktreeId, tabId, baseVersion, content) =>
-      requestMobileMarkdownFromRenderer(mainWindow, {
-        operation: 'save',
-        worktreeId,
-        tabId,
-        baseVersion,
-        content
-      }) as Promise<RuntimeMarkdownSaveTabResult>,
-    closeTerminal: (tabId, paneRuntimeId) => send('ui:closeTerminal', { tabId, paneRuntimeId }),
-    closeTerminalTab: (tabId, options) =>
-      requestTerminalTabCloseFromRenderer(mainWindow, tabId, options),
-    sleepWorktree: (worktreeId) => send('ui:sleepWorktree', { worktreeId }),
-    resumeSleepingAgents: (worktreeId) => send('ui:resumeSleepingAgents', { worktreeId }),
-    terminalFitOverrideChanged: (ptyId, mode, cols, rows) =>
-      send('runtime:terminalFitOverrideChanged', { ptyId, mode, cols, rows }),
-    terminalDriverChanged: (ptyId, driver) =>
-      send('runtime:terminalDriverChanged', { ptyId, driver }),
-    nativeChatLaunchDraftResolved: (tabId, resolution) =>
-      send('runtime:nativeChatLaunchDraftResolved', { tabId, ...resolution }),
-    browserDriverChanged: (browserPageId, driver) =>
-      send('runtime:browserDriverChanged', { browserPageId, driver }),
-    browserRemoteViewersChanged: (browserPageId, hasRemoteViewers) =>
-      send('runtime:browserRemoteViewersChanged', { browserPageId, hasRemoteViewers }),
-    clientHostedBrowserRowsChanged: (event) => send('runtime:clientHostedBrowserRowsChanged', event)
-  })
-  registerRendererDocumentNavigation(mainWebContents, () => {
-    rendererNotifications.onMainFrameReloadStarted()
-    const fence = runtime.markRendererReloading(mainWindow.id)
-    return () => {
-      if (fence && runtime.markRendererReloadCancelled(mainWindow.id, fence)) {
-        rendererNotifications.onMainFrameReloadCancelled()
-      }
-    }
-  })
-  mainWebContents.on('did-finish-load', () => {
-    rendererNotifications.onMainFrameLoadFinished()
-  })
-  mainWebContents.on('render-process-gone', () => {
-    rendererNotifications.onRendererProcessGone()
-  })
-  mainWindow.on('closed', () => {
-    rendererNotifications.close()
-    runtime.markGraphUnavailable(mainWindow.id)
-    if (activeRuntimeNotifierToken === notifierToken) {
-      // Why: the notifier closes over the window; clear it in the no-window gap so the runtime can't retain destroyed graphs.
-      runtime.setNotifier(null)
-      activeRuntimeNotifierToken = null
-    }
-  })
-}
-
 function registerFileDropRelay(mainWindow: BrowserWindow): void {
   const channel = 'terminal:file-dropped-from-preload'
   const mainWebContents = mainWindow.webContents
@@ -563,58 +266,3 @@ function registerFileDropRelay(mainWindow: BrowserWindow): void {
     ipcMain.removeListener(channel, relayFileDrop)
   })
 }
-
-export function registerUpdaterHandlers(_store: Store): void {
-  ipcMain.removeHandler('updater:getStatus')
-  ipcMain.removeHandler('updater:getVersion')
-  ipcMain.removeHandler('updater:check')
-  ipcMain.removeHandler('updater:download')
-  ipcMain.removeHandler('updater:quitAndInstall')
-  ipcMain.removeHandler('updater:dismissNudge')
-  ipcMain.removeHandler('updater:dismissAvailableUpdate')
-  ipcMain.removeHandler('updater:getLinuxPackageInstallInstructions')
-  ipcMain.removeHandler('updater:showLinuxPackage')
-  ipcMain.removeHandler('updater:listBuilds')
-
-  ipcMain.handle('updater:getStatus', () => getUpdateStatus())
-  ipcMain.handle('updater:getVersion', () => app.getVersion())
-  ipcMain.handle('updater:check', (_event, options?: UpdateCheckOptions) => {
-    ensureAutoUpdaterConfigured()
-    return checkForUpdatesFromMenu(options)
-  })
-  ipcMain.handle('updater:download', () => downloadUpdate())
-  ipcMain.handle('updater:quitAndInstall', () => quitAndInstall())
-  ipcMain.handle('updater:dismissNudge', () => dismissNudge())
-  ipcMain.handle('updater:dismissAvailableUpdate', () => dismissAvailableUpdate())
-  // Why: the response carries a local package path and the reveal touches the native desktop, so
-  // neither may be reached from a guest, dashboard popout, stale window, or utility renderer.
-  ipcMain.handle('updater:getLinuxPackageInstallInstructions', (event) => {
-    assertTrustedUpdaterRecoverySender(event)
-    return getLinuxPackageInstallInstructions()
-  })
-  ipcMain.handle('updater:showLinuxPackage', (event) => {
-    assertTrustedUpdaterRecoverySender(event)
-    return showLinuxPackage()
-  })
-  ipcMain.handle(
-    'updater:listBuilds',
-    async (_event, channel: ReleaseChannel): Promise<ReleaseBuildListResult> => {
-      if (!RELEASE_CHANNELS.includes(channel)) {
-        return { ok: false, channel, message: `Unknown release channel "${channel}".` }
-      }
-      try {
-        return { ok: true, channel, builds: await listAvailableReleaseBuilds(channel) }
-      } catch (error) {
-        // Why: a network/rate-limit failure is expected here; return it as data so
-        // the picker can render the reason instead of rejecting the invoke.
-        return { ok: false, channel, message: String((error as Error)?.message ?? error) }
-      }
-    }
-  )
-}
-
-function assertTrustedUpdaterRecoverySender(event: IpcMainInvokeEvent): void {
-  if (!isTrustedUIRenderer(event.sender)) {
-    throw new Error('Unauthorized updater package recovery sender')
-  }
-}
diff --git a/src/main/window/main-window-updater.ts b/src/main/window/main-window-updater.ts
new file mode 100644
index 00000000000..51860db8dc5
--- /dev/null
+++ b/src/main/window/main-window-updater.ts
@@ -0,0 +1,135 @@
+import { app, ipcMain } from 'electron'
+import type { BrowserWindow, IpcMainInvokeEvent } from 'electron'
+import type { ReleaseBuildListResult, UpdateCheckOptions } from '../../shared/update-status-types'
+import { RELEASE_CHANNELS, type ReleaseChannel } from '../../shared/release-channel'
+import { isTrustedUIRenderer } from '../ipc/ui'
+import type { Store } from '../persistence'
+import { logStartupMilestone } from '../startup/startup-diagnostics'
+import {
+  checkForUpdatesFromMenu,
+  dismissAvailableUpdate,
+  dismissNudge,
+  downloadUpdate,
+  getLinuxPackageInstallInstructions,
+  getUpdateStatus,
+  listAvailableReleaseBuilds,
+  quitAndInstall,
+  setupAutoUpdater,
+  showLinuxPackage,
+  type UpdateInstallMode
+} from '../updater'
+
+const UPDATER_SETUP_FALLBACK_MS = 15_000
+
+// Why: a manual check can arrive before deferred setup runs, so entry points force this pending setup to configure the updater first.
+let pendingAutoUpdaterSetup: (() => void) | null = null
+
+export function ensureAutoUpdaterConfigured(): void {
+  pendingAutoUpdaterSetup?.()
+}
+
+export function scheduleMainWindowAutoUpdaterSetup(
+  mainWindow: BrowserWindow,
+  store: Store,
+  options?: {
+    onBeforeUpdateQuit?: () => void | Promise<void>
+    updateInstallMode?: UpdateInstallMode
+  }
+): void {
+  // Why: setupAutoUpdater sync-require()s electron-updater (slow on cold Windows w/ Defender, #7225), so defer past first paint; timer fallback covers crash-looping renderers.
+  let updaterSetupDone = false
+  const setupAutoUpdaterDeferred = (): void => {
+    if (updaterSetupDone || mainWindow.isDestroyed()) {
+      return
+    }
+    updaterSetupDone = true
+    setupAutoUpdater(mainWindow, {
+      getLastUpdateCheckAt: () => store.getUI().lastUpdateCheckAt,
+      onBeforeQuit: async () => {
+        try {
+          await options?.onBeforeUpdateQuit?.()
+        } finally {
+          await store.flushPendingAsync()
+        }
+      },
+      setLastUpdateCheckAt: (timestamp) => {
+        store.updateUI({ lastUpdateCheckAt: timestamp })
+      },
+      getPendingUpdateNudgeId: () => store.getUI().pendingUpdateNudgeId ?? null,
+      getDismissedUpdateNudgeId: () => store.getUI().dismissedUpdateNudgeId ?? null,
+      setPendingUpdateNudgeId: (id) => {
+        // Why: only the apply branch also nulls dismissedUpdateVersion so relaunch can't resurrect the old hidden card; clearing must not, or it un-dismisses.
+        if (id) {
+          store.updateUI({ pendingUpdateNudgeId: id, dismissedUpdateVersion: null })
+        } else {
+          store.updateUI({ pendingUpdateNudgeId: null })
+        }
+      },
+      setDismissedUpdateNudgeId: (id) => {
+        store.updateUI({ dismissedUpdateNudgeId: id })
+      },
+      getReleaseChannelOverride: () => store.getUI().releaseChannelOverride ?? null,
+      installMode: options?.updateInstallMode
+    })
+    logStartupMilestone('updater-setup-done')
+  }
+  pendingAutoUpdaterSetup = setupAutoUpdaterDeferred
+  mainWindow.once('ready-to-show', () => setImmediate(setupAutoUpdaterDeferred))
+  const updaterSetupFallback = setTimeout(setupAutoUpdaterDeferred, UPDATER_SETUP_FALLBACK_MS)
+  updaterSetupFallback.unref?.()
+}
+
+export function registerUpdaterHandlers(_store: Store): void {
+  ipcMain.removeHandler('updater:getStatus')
+  ipcMain.removeHandler('updater:getVersion')
+  ipcMain.removeHandler('updater:check')
+  ipcMain.removeHandler('updater:download')
+  ipcMain.removeHandler('updater:quitAndInstall')
+  ipcMain.removeHandler('updater:dismissNudge')
+  ipcMain.removeHandler('updater:dismissAvailableUpdate')
+  ipcMain.removeHandler('updater:getLinuxPackageInstallInstructions')
+  ipcMain.removeHandler('updater:showLinuxPackage')
+  ipcMain.removeHandler('updater:listBuilds')
+
+  ipcMain.handle('updater:getStatus', () => getUpdateStatus())
+  ipcMain.handle('updater:getVersion', () => app.getVersion())
+  ipcMain.handle('updater:check', (_event, options?: UpdateCheckOptions) => {
+    ensureAutoUpdaterConfigured()
+    return checkForUpdatesFromMenu(options)
+  })
+  ipcMain.handle('updater:download', () => downloadUpdate())
+  ipcMain.handle('updater:quitAndInstall', () => quitAndInstall())
+  ipcMain.handle('updater:dismissNudge', () => dismissNudge())
+  ipcMain.handle('updater:dismissAvailableUpdate', () => dismissAvailableUpdate())
+  // Why: the response carries a local package path and the reveal touches the native desktop, so
+  // neither may be reached from a guest, dashboard popout, stale window, or utility renderer.
+  ipcMain.handle('updater:getLinuxPackageInstallInstructions', (event) => {
+    assertTrustedUpdaterRecoverySender(event)
+    return getLinuxPackageInstallInstructions()
+  })
+  ipcMain.handle('updater:showLinuxPackage', (event) => {
+    assertTrustedUpdaterRecoverySender(event)
+    return showLinuxPackage()
+  })
+  ipcMain.handle(
+    'updater:listBuilds',
+    async (_event, channel: ReleaseChannel): Promise<ReleaseBuildListResult> => {
+      if (!RELEASE_CHANNELS.includes(channel)) {
+        return { ok: false, channel, message: `Unknown release channel "${channel}".` }
+      }
+      try {
+        return { ok: true, channel, builds: await listAvailableReleaseBuilds(channel) }
+      } catch (error) {
+        // Why: a network/rate-limit failure is expected here; return it as data so
+        // the picker can render the reason instead of rejecting the invoke.
+        return { ok: false, channel, message: String((error as Error)?.message ?? error) }
+      }
+    }
+  )
+}
+
+function assertTrustedUpdaterRecoverySender(event: IpcMainInvokeEvent): void {
+  if (!isTrustedUIRenderer(event.sender)) {
+    throw new Error('Unauthorized updater package recovery sender')
+  }
+}
diff --git a/src/main/window/runtime-window-lifecycle.ts b/src/main/window/runtime-window-lifecycle.ts
new file mode 100644
index 00000000000..cc6b6b47136
--- /dev/null
+++ b/src/main/window/runtime-window-lifecycle.ts
@@ -0,0 +1,239 @@
+import { randomUUID } from 'node:crypto'
+
+import { ipcMain } from 'electron'
+import type { BrowserWindow } from 'electron'
+import type { CreateWorktreeResult } from '../../shared/worktree/create-types'
+import type { WorktreeStartupLaunch } from '../../shared/worktree/launch-types'
+import type {
+  RuntimeMarkdownReadTabResult,
+  RuntimeMarkdownSaveTabResult
+} from '../../shared/mobile-markdown-document'
+import type { RuntimeMobileSessionTabMove } from '../../shared/runtime-types'
+import type { TerminalTabCreateReply } from '../../shared/terminal-reveal-identity'
+import { runWorktreeChangeInvalidators } from '../ipc/worktree-change-invalidators'
+import type { OrcaRuntimeService } from '../runtime/orca-runtime'
+import { requestMobileMarkdownFromRenderer } from './mobile-markdown-request-relay'
+import { registerRendererDocumentNavigation } from './renderer-document-navigation'
+import { createRuntimeRendererNotificationSender } from './runtime-renderer-notification-sender'
+import { requestSessionTabCloseFromRenderer } from './session-tab-close-request-relay'
+import { requestTerminalTabCloseFromRenderer } from './terminal-tab-close-request-relay'
+
+let runtimeNotifierTokenCounter = 0
+let activeRuntimeNotifierToken: number | null = null
+
+export function registerRuntimeWindowLifecycle(
+  mainWindow: BrowserWindow,
+  runtime: OrcaRuntimeService
+): void {
+  const notifierToken = ++runtimeNotifierTokenCounter
+  activeRuntimeNotifierToken = notifierToken
+  runtime.attachWindow(mainWindow.id)
+  const mainWebContents = mainWindow.webContents
+  const rendererNotifications = createRuntimeRendererNotificationSender({
+    isWindowDestroyed: () => mainWindow.isDestroyed(),
+    webContents: mainWebContents,
+    onFailure: (reason) => runtime.markGraphReloadFailed(mainWindow.id, reason)
+  })
+  const send = rendererNotifications.send
+  runtime.setNotifier({
+    worktreesChanged: (repoId, renamed) => {
+      // Why: clear scan caches before the renderer handles this event, so it can't read stale TTL entries after a mutation.
+      runWorktreeChangeInvalidators(repoId)
+      send('worktrees:changed', renamed ? { repoId, renamed } : { repoId })
+    },
+    worktreeBaseStatus: (event) => send('worktree:baseStatus', event),
+    worktreeRemoteBranchConflict: (event) => send('worktree:remoteBranchConflict', event),
+    reposChanged: () => send('repos:changed'),
+    automationsChanged: (payload) => send('automations:changed', payload),
+    activateWorktree: (
+      repoId,
+      worktreeId,
+      setup?: CreateWorktreeResult['setup'],
+      startup?: WorktreeStartupLaunch,
+      defaultTabs?: CreateWorktreeResult['defaultTabs']
+    ) => {
+      send('ui:activateWorktree', {
+        repoId,
+        worktreeId,
+        ...(setup ? { setup } : {}),
+        ...(startup ? { startup } : {}),
+        ...(defaultTabs ? { defaultTabs } : {})
+      })
+    },
+    createTerminal: (worktreeId, opts) =>
+      send('ui:createTerminal', {
+        worktreeId,
+        command: opts.command,
+        ...(opts.cwd ? { cwd: opts.cwd } : {}),
+        ...(opts.env ? { env: opts.env } : {}),
+        title: opts.title,
+        ...(opts.presentation ? { presentation: opts.presentation } : {})
+      }),
+    revealTerminalSession: (worktreeId, opts) =>
+      new Promise((resolve, reject) => {
+        const requestId = randomUUID()
+        const expectedIdentity = opts.expectedProcessIdentity
+          ? opts.tabId && opts.leafId
+            ? { worktreeId, tabId: opts.tabId, leafId: opts.leafId, ptyId: opts.ptyId }
+            : null
+          : undefined
+        if (expectedIdentity === null) {
+          reject(new Error('terminal_reveal_identity_required'))
+          return
+        }
+        const timer = setTimeout(() => {
+          ipcMain.removeListener('terminal:tabCreateReply', handler)
+          reject(new Error('Terminal reveal timed out'))
+        }, 10_000)
+        const handler = (event: Electron.IpcMainEvent, reply: TerminalTabCreateReply): void => {
+          // Why: requestId is renderer-supplied, so only the targeted main window may satisfy the reveal.
+          if (event.sender !== mainWindow.webContents || reply.requestId !== requestId) {
+            return
+          }
+          clearTimeout(timer)
+          ipcMain.removeListener('terminal:tabCreateReply', handler)
+          if (reply.error) {
+            reject(new Error(reply.error))
+            return
+          }
+          if (
+            expectedIdentity &&
+            (!reply.identity ||
+              reply.identity.worktreeId !== expectedIdentity.worktreeId ||
+              reply.identity.tabId !== expectedIdentity.tabId ||
+              reply.identity.leafId !== expectedIdentity.leafId ||
+              reply.identity.ptyId !== expectedIdentity.ptyId)
+          ) {
+            reject(new Error('terminal_reveal_identity_mismatch'))
+            return
+          }
+          resolve({
+            tabId: reply.tabId!,
+            title: reply.title,
+            ...(reply.identity ? { identity: reply.identity } : {})
+          })
+        }
+        ipcMain.on('terminal:tabCreateReply', handler)
+        const sent = send('ui:createTerminal', {
+          requestId,
+          worktreeId,
+          ptyId: opts.ptyId,
+          title: opts.title ?? undefined,
+          ...(opts.cwd ? { cwd: opts.cwd } : {}),
+          ...(opts.launchConfig ? { launchConfig: opts.launchConfig } : {}),
+          ...(opts.launchToken ? { launchToken: opts.launchToken } : {}),
+          ...(opts.launchAgent ? { launchAgent: opts.launchAgent } : {}),
+          ...(opts.viewMode ? { viewMode: opts.viewMode } : {}),
+          activate: opts.activate !== false,
+          ...(opts.presentation ? { presentation: opts.presentation } : {}),
+          ...(opts.surfaceOwner === false ? { surfaceOwner: false } : {}),
+          // Why: pre-minted tabId aligns the renderer tab id with the paneKey baked into the PTY env, so hook events route right.
+          ...(opts.tabId !== undefined ? { tabId: opts.tabId } : {}),
+          ...(opts.leafId !== undefined ? { leafId: opts.leafId } : {}),
+          ...(opts.splitFromLeafId !== undefined ? { splitFromLeafId: opts.splitFromLeafId } : {}),
+          ...(opts.splitDirection !== undefined ? { splitDirection: opts.splitDirection } : {}),
+          ...(opts.splitTelemetrySource !== undefined
+            ? { splitTelemetrySource: opts.splitTelemetrySource }
+            : {}),
+          ...(opts.focus !== undefined ? { focus: opts.focus } : {})
+        })
+        if (!sent) {
+          clearTimeout(timer)
+          ipcMain.removeListener('terminal:tabCreateReply', handler)
+          reject(new Error('runtime_unavailable'))
+        }
+      }),
+    resolveLegacyWorkerTerminalRecovery: (paneKey, resolution, ptyId) =>
+      send('agentStatus:legacyWorkerTerminalRecovery', {
+        paneKey,
+        resolution,
+        ...(ptyId ? { ptyId } : {})
+      }),
+    splitTerminal: (tabId, paneRuntimeId, opts) => {
+      send('ui:splitTerminal', {
+        tabId,
+        paneRuntimeId,
+        direction: opts.direction,
+        command: opts.command,
+        telemetrySource: opts.telemetrySource
+      })
+    },
+    renameTerminal: (tabId, title) => send('ui:renameTerminal', { tabId, title }),
+    focusTerminal: (tabId, worktreeId, leafId) =>
+      send('ui:focusTerminal', { tabId, worktreeId, leafId }),
+    focusEditorTab: (tabId, worktreeId) => send('ui:focusEditorTab', { tabId, worktreeId }),
+    closeSessionTab: (tabId, worktreeId) =>
+      requestSessionTabCloseFromRenderer(mainWindow, tabId, worktreeId),
+    moveSessionTab: (worktreeId: string, move: RuntimeMobileSessionTabMove) =>
+      send('ui:moveSessionTab', { worktreeId, ...move }),
+    openFile: (worktreeId, filePath, relativePath, runtimeEnvironmentId?) =>
+      send('ui:openFileFromMobile', {
+        worktreeId,
+        filePath,
+        relativePath,
+        runtimeEnvironmentId
+      }),
+    openDiff: (worktreeId, filePath, relativePath, staged, runtimeEnvironmentId?) =>
+      send('ui:openDiffFromMobile', {
+        worktreeId,
+        filePath,
+        relativePath,
+        staged,
+        runtimeEnvironmentId
+      }),
+    readMobileMarkdownTab: (worktreeId, tabId) =>
+      requestMobileMarkdownFromRenderer(mainWindow, {
+        operation: 'read',
+        worktreeId,
+        tabId
+      }) as Promise<RuntimeMarkdownReadTabResult>,
+    saveMobileMarkdownTab: (worktreeId, tabId, baseVersion, content) =>
+      requestMobileMarkdownFromRenderer(mainWindow, {
+        operation: 'save',
+        worktreeId,
+        tabId,
+        baseVersion,
+        content
+      }) as Promise<RuntimeMarkdownSaveTabResult>,
+    closeTerminal: (tabId, paneRuntimeId) => send('ui:closeTerminal', { tabId, paneRuntimeId }),
+    closeTerminalTab: (tabId, options) =>
+      requestTerminalTabCloseFromRenderer(mainWindow, tabId, options),
+    sleepWorktree: (worktreeId) => send('ui:sleepWorktree', { worktreeId }),
+    resumeSleepingAgents: (worktreeId) => send('ui:resumeSleepingAgents', { worktreeId }),
+    terminalFitOverrideChanged: (ptyId, mode, cols, rows) =>
+      send('runtime:terminalFitOverrideChanged', { ptyId, mode, cols, rows }),
+    terminalDriverChanged: (ptyId, driver) =>
+      send('runtime:terminalDriverChanged', { ptyId, driver }),
+    nativeChatLaunchDraftResolved: (tabId, resolution) =>
+      send('runtime:nativeChatLaunchDraftResolved', { tabId, ...resolution }),
+    browserDriverChanged: (browserPageId, driver) =>
+      send('runtime:browserDriverChanged', { browserPageId, driver }),
+    browserRemoteViewersChanged: (browserPageId, hasRemoteViewers) =>
+      send('runtime:browserRemoteViewersChanged', { browserPageId, hasRemoteViewers }),
+    clientHostedBrowserRowsChanged: (event) => send('runtime:clientHostedBrowserRowsChanged', event)
+  })
+  registerRendererDocumentNavigation(mainWebContents, () => {
+    rendererNotifications.onMainFrameReloadStarted()
+    const fence = runtime.markRendererReloading(mainWindow.id)
+    return () => {
+      if (fence && runtime.markRendererReloadCancelled(mainWindow.id, fence)) {
+        rendererNotifications.onMainFrameReloadCancelled()
+      }
+    }
+  })
+  mainWebContents.on('did-finish-load', () => {
+    rendererNotifications.onMainFrameLoadFinished()
+  })
+  mainWebContents.on('render-process-gone', () => {
+    rendererNotifications.onRendererProcessGone()
+  })
+  mainWindow.on('closed', () => {
+    rendererNotifications.close()
+    runtime.markGraphUnavailable(mainWindow.id)
+    if (activeRuntimeNotifierToken === notifierToken) {
+      // Why: the notifier closes over the window; clear it in the no-window gap so the runtime can't retain destroyed graphs.
+      runtime.setNotifier(null)
+      activeRuntimeNotifierToken = null
+    }
+  })
+}

From 8ff8e8a5f31ae672a9f69caede35d1131e2b53a1 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sat, 29 Aug 2026 20:08:36 -0700
Subject: [PATCH 28/31] Split hosted review creation checks (#17152)

* Split speech session lifecycle

* Split terminal output scheduler pipeline

* Split mobile browser pane modules

* Prune resolved max-lines suppressions

* Split pane tree equalization logic

* Extract mobile troubleshoot screen styles

* Split external automation manager

* Split main window service attachments

* Split hosted review creation checks

* Fix F3-speech for #17123

* Fix F1-cycle for #17131
---
 config/max-lines-baseline.txt                 |   1 -
 .../hosted-review-creation-blocking.ts        | 102 +++++
 .../hosted-review-creation-git-state.ts       | 179 ++++++++
 .../hosted-review-creation-provider.ts        | 137 ++++++
 .../source-control/hosted-review-creation.ts  | 422 +-----------------
 5 files changed, 432 insertions(+), 409 deletions(-)
 create mode 100644 src/main/source-control/hosted-review-creation-blocking.ts
 create mode 100644 src/main/source-control/hosted-review-creation-git-state.ts
 create mode 100644 src/main/source-control/hosted-review-creation-provider.ts

diff --git a/config/max-lines-baseline.txt b/config/max-lines-baseline.txt
index 7870a1bf8b2..fbc4a24ed38 100644
--- a/config/max-lines-baseline.txt
+++ b/config/max-lines-baseline.txt
@@ -26,7 +26,6 @@ inline src/main/runtime/orca-runtime.test.ts
 inline src/main/runtime/orca-runtime.ts
 inline src/main/runtime/rpc/methods/orchestration.ts
 inline src/main/runtime/runtime-rpc.ts
-inline src/main/source-control/hosted-review-creation.ts
 inline src/main/ssh/ssh-channel-multiplexer.ts
 inline src/main/ssh/ssh-connection.ts
 inline src/main/ssh/ssh-relay-deploy.ts
diff --git a/src/main/source-control/hosted-review-creation-blocking.ts b/src/main/source-control/hosted-review-creation-blocking.ts
new file mode 100644
index 00000000000..455d55049ed
--- /dev/null
+++ b/src/main/source-control/hosted-review-creation-blocking.ts
@@ -0,0 +1,102 @@
+import type {
+  CreateHostedReviewResult,
+  HostedReviewCreationBlockedReason,
+  HostedReviewCreationEligibility,
+  HostedReviewProvider
+} from '../../shared/hosted-review'
+import { reviewCopy } from './hosted-review-creation-provider'
+
+function blockedCreateResultForReason(
+  reason: NonNullable<HostedReviewCreationBlockedReason>,
+  provider: HostedReviewProvider,
+  submittedBase?: string | null
+): CreateHostedReviewResult | null {
+  const copy = reviewCopy(provider)
+  const baseLabel = submittedBase?.trim() ? `"${submittedBase.trim()}" ` : ''
+  const blockedCreateResultByReason = {
+    auth_required: {
+      ok: false,
+      code: 'auth_required',
+      error: `Create ${copy.shortLabel} failed: ${copy.providerName} is not authenticated. Next step: ${copy.authInstruction} in this environment.`
+    },
+    unsupported_provider: {
+      ok: false,
+      code: 'unsupported_provider',
+      error: `Creating ${copy.reviewLabel}s requires a ${copy.providerName} remote.`
+    },
+    dirty: {
+      ok: false,
+      code: 'validation',
+      error: `Create ${copy.shortLabel} failed: commit or discard local changes before creating a ${copy.reviewLabel}.`
+    },
+    detached_head: {
+      ok: false,
+      code: 'validation',
+      error: `Create ${copy.shortLabel} failed: switch to a branch before creating a ${copy.reviewLabel}.`
+    },
+    default_branch: {
+      ok: false,
+      code: 'validation',
+      error: `Create ${copy.shortLabel} failed: choose a feature branch before creating a ${copy.reviewLabel}.`
+    },
+    no_upstream: {
+      ok: false,
+      code: 'validation',
+      error: `Create ${copy.shortLabel} failed: publish this branch before creating a ${copy.reviewLabel}.`
+    },
+    needs_push: {
+      ok: false,
+      code: 'validation',
+      error: `Create ${copy.shortLabel} failed: push this branch before creating a ${copy.reviewLabel}.`
+    },
+    needs_sync: {
+      ok: false,
+      code: 'validation',
+      error: `Create ${copy.shortLabel} failed: sync this branch before creating a ${copy.reviewLabel}.`
+    },
+    fork_head_unsupported: {
+      ok: false,
+      code: 'validation',
+      error: `Create ${copy.shortLabel} failed: refresh source control status and try again.`
+    },
+    base_not_on_remote: {
+      ok: false,
+      code: 'validation',
+      error: `Create ${copy.shortLabel} failed: the base branch ${baseLabel}hasn't been pushed to the remote. Choose a pushed base or push it first.`
+    }
+  } satisfies Partial<
+    Record<NonNullable<HostedReviewCreationBlockedReason>, CreateHostedReviewResult>
+  >
+  return blockedCreateResultByReason[reason] ?? null
+}
+
+export function blockedEligibilityToCreateResult(
+  eligibility: HostedReviewCreationEligibility,
+  submittedBase?: string | null
+): CreateHostedReviewResult | null {
+  if (eligibility.canCreate) {
+    return null
+  }
+  if (eligibility.review?.url) {
+    const copy = reviewCopy(eligibility.provider)
+    return {
+      ok: false,
+      code: 'already_exists',
+      error: `A ${copy.reviewLabel} already exists for this branch.`,
+      existingReview: eligibility.review
+    }
+  }
+  if (eligibility.blockedReason) {
+    return blockedCreateResultForReason(
+      eligibility.blockedReason,
+      eligibility.provider,
+      submittedBase
+    )
+  }
+  const copy = reviewCopy(eligibility.provider)
+  return {
+    ok: false,
+    code: 'validation',
+    error: `Create ${copy.shortLabel} failed: refresh source control status and try again.`
+  }
+}
diff --git a/src/main/source-control/hosted-review-creation-git-state.ts b/src/main/source-control/hosted-review-creation-git-state.ts
new file mode 100644
index 00000000000..5c891e97f06
--- /dev/null
+++ b/src/main/source-control/hosted-review-creation-git-state.ts
@@ -0,0 +1,179 @@
+import {
+  normalizeHostedReviewBaseRef,
+  normalizeHostedReviewHeadRef
+} from '../../shared/hosted-review-refs'
+import { isNoUpstreamError, normalizeGitErrorMessage } from '../../shared/git-remote-error'
+import type { GitUpstreamStatus } from '../../shared/git-status-types'
+import { gitExecFileAsync } from '../github/gh-utils'
+import { gitOptionalLocksDisabledEnv } from '../git/runner'
+import { parsePorcelainV1Records, type PorcelainV1Record } from '../git/porcelain-v1-records'
+import { resolveDefaultBaseRefViaExec } from '../git/repo'
+import { getUpstreamStatus } from '../git/upstream'
+import { findExistingWorktreeSymlinkPaths } from '../git/worktree-symlink-detection'
+import { getSshGitProvider } from '../providers/ssh-git-dispatch'
+import {
+  getHostedReviewLocalGitOptions,
+  type HostedReviewExecutionOptions
+} from './hosted-review-git-options'
+
+export function stripRefPrefix(ref: string): string {
+  return normalizeHostedReviewHeadRef(ref)
+}
+
+export function hostedReviewExecutionContext(
+  options: HostedReviewExecutionOptions = {}
+): HostedReviewExecutionOptions {
+  const localGitExecOptions = getHostedReviewLocalGitOptions(options)
+  return Object.keys(localGitExecOptions).length > 0 ? { localGitExecOptions } : {}
+}
+
+async function runGitForHostedReview(
+  repoPath: string,
+  args: string[],
+  connectionId?: string | null,
+  options: HostedReviewExecutionOptions = {}
+): Promise<{ stdout: string; stderr?: string }> {
+  if (connectionId) {
+    const provider = getSshGitProvider(connectionId)
+    if (!provider) {
+      throw new Error(
+        'Remote connection dropped. Click Reconnect on the SSH target before retrying.'
+      )
+    }
+    return provider.exec(args, repoPath)
+  }
+  return gitExecFileAsync(args, { cwd: repoPath, ...getHostedReviewLocalGitOptions(options) })
+}
+
+export async function getDefaultBaseRef(
+  repoPath: string,
+  connectionId?: string | null,
+  options: HostedReviewExecutionOptions = {}
+): Promise<string | null> {
+  return resolveDefaultBaseRefViaExec((argv) =>
+    runGitForHostedReview(repoPath, argv, connectionId, options)
+  )
+}
+
+/**
+ * Whether the candidate base resolves to a remote-tracking branch on the
+ * executing host.
+ *
+ * Why: matches under *any* remote (not just origin) and reads the local tracking snapshot, not the live remote.
+ */
+export async function baseRefExistsOnRemote(
+  candidate: string,
+  repoPath: string,
+  connectionId?: string | null,
+  options: HostedReviewExecutionOptions = {}
+): Promise<boolean> {
+  const base = normalizeHostedReviewBaseRef(candidate).trim()
+  if (!base) {
+    return false
+  }
+  const run = (argv: string[]): Promise<{ stdout: string }> =>
+    runGitForHostedReview(repoPath, argv, connectionId, options)
+
+  const patterns = [`refs/remotes/*/${base}`]
+  // `*` does not cross `/`, so a remote-qualified candidate (e.g. `fork/main`) needs its exact tracking ref too.
+  if (base.includes('/')) {
+    patterns.push(`refs/remotes/${base}`)
+  }
+
+  try {
+    // for-each-ref exits 0 on no match: empty means absent, a thrown error means transport failure (preserve the candidate).
+    const { stdout } = await run(['for-each-ref', '--count=1', '--format=%(refname)', ...patterns])
+    return stdout.trim().length > 0
+  } catch {
+    return true
+  }
+}
+
+export async function getCurrentBranch(
+  repoPath: string,
+  connectionId?: string | null,
+  options: HostedReviewExecutionOptions = {}
+): Promise<string> {
+  const { stdout } = await runGitForHostedReview(
+    repoPath,
+    ['rev-parse', '--abbrev-ref', 'HEAD'],
+    connectionId,
+    options
+  )
+  return stripRefPrefix(stdout.trim())
+}
+
+export async function hasUncommittedChanges(
+  repoPath: string,
+  connectionId?: string | null,
+  options: HostedReviewExecutionOptions = {}
+): Promise<boolean> {
+  if (connectionId) {
+    const provider = getSshGitProvider(connectionId)
+    if (!provider) {
+      throw new Error(
+        'Remote connection dropped. Click Reconnect on the SSH target before retrying.'
+      )
+    }
+    // Why: the relay restricts generic git.exec, so use the structured status RPC for SSH dirty checks.
+    // No shared-link exclusion here: remote worktree creation skips the symlink
+    // and shared-directory passes entirely, so a remote worktree never has one.
+    return (await provider.getStatus(repoPath)).entries.length > 0
+  }
+  // Why: `-z` keeps paths raw so the shared-link comparison below can't be
+  // defeated by Git quoting a path with spaces or non-ASCII bytes.
+  const { stdout } = await gitExecFileAsync(['status', '--porcelain', '-z'], {
+    cwd: repoPath,
+    ...getHostedReviewLocalGitOptions(options),
+    // Why: don't take Git's optional index lock while the user may be running fetch/pull/rebase in a terminal.
+    env: gitOptionalLocksDisabledEnv()
+  })
+  const records = parsePorcelainV1Records(stdout)
+  if (records.length === 0) {
+    return false
+  }
+  return await anyRecordIsUserDirt(repoPath, records, options.sharedLinkPaths ?? [])
+}
+
+/** True when any record is real user work rather than a shared symlink Orca put
+ *  in the worktree.
+ *
+ *  Fails closed on purpose: anything not positively identified as an Orca-owned
+ *  untracked symlink counts as dirty. A false "clean" would let a review be
+ *  created off a branch missing the user's work. */
+async function anyRecordIsUserDirt(
+  worktreePath: string,
+  records: readonly PorcelainV1Record[],
+  sharedLinkPaths: readonly string[]
+): Promise<boolean> {
+  if (sharedLinkPaths.length === 0 || !records.some((record) => record.xy === '??')) {
+    return true
+  }
+  // Why: only entries that are configured AND really symlinks are excluded, so a
+  // regular file the user created at a configured name still blocks creation.
+  const sharedLinks = new Set(await findExistingWorktreeSymlinkPaths(worktreePath, sharedLinkPaths))
+  return records.some((record) => record.xy !== '??' || !sharedLinks.has(record.path))
+}
+
+export async function getHostedReviewUpstreamStatus(
+  repoPath: string,
+  connectionId?: string | null,
+  options: HostedReviewExecutionOptions = {}
+): Promise<GitUpstreamStatus> {
+  if (!connectionId) {
+    return getUpstreamStatus(repoPath, undefined, getHostedReviewLocalGitOptions(options))
+  }
+  const provider = getSshGitProvider(connectionId)
+  if (!provider) {
+    throw new Error('Remote connection dropped. Click Reconnect on the SSH target before retrying.')
+  }
+  try {
+    // Why: the relay blocks generic git.exec, so use its dedicated upstream RPC for SSH divergence.
+    return await provider.getUpstreamStatus(repoPath)
+  } catch (error) {
+    if (isNoUpstreamError(error)) {
+      return { hasUpstream: false, ahead: 0, behind: 0 }
+    }
+    throw new Error(normalizeGitErrorMessage(error, 'upstream'))
+  }
+}
diff --git a/src/main/source-control/hosted-review-creation-provider.ts b/src/main/source-control/hosted-review-creation-provider.ts
new file mode 100644
index 00000000000..323497d2419
--- /dev/null
+++ b/src/main/source-control/hosted-review-creation-provider.ts
@@ -0,0 +1,137 @@
+import type { HostedReviewProvider } from '../../shared/hosted-review'
+import type { HostedReviewCreationProvider } from '../../shared/hosted-review-creation-providers'
+import { isAzureDevOpsReviewCreationAuthenticated } from '../azure-devops/pull-request-creation'
+import { isBitbucketReviewCreationAuthenticated } from '../bitbucket/pull-request-creation'
+import { isGiteaReviewCreationAuthenticated } from '../gitea/pull-request-creation'
+import { getEnterpriseGitHubRepoSlug } from '../github/github-enterprise-repository'
+import { acquire, ghExecFileAsync, release } from '../github/gh-utils'
+import { getProjectSlug } from '../gitlab/client'
+import {
+  acquire as acquireGlab,
+  glabExecFileAsync,
+  glabRepoExecOptions,
+  release as releaseGlab
+} from '../gitlab/gl-utils'
+import {
+  getHostedReviewLocalGitOptions,
+  type HostedReviewExecutionOptions
+} from './hosted-review-git-options'
+
+async function isGitHubAuthenticated(
+  repoPath: string,
+  connectionId?: string | null,
+  options: HostedReviewExecutionOptions = {}
+): Promise<boolean> {
+  // Why: a non-null enterprise slug already means gh is authenticated there, so skip a redundant probe (#8312).
+  if (await getEnterpriseGitHubRepoSlug(repoPath, connectionId, options)) {
+    return true
+  }
+  await acquire()
+  try {
+    // Why: `host` scopes any rate-limit breaker trip to github.com — the host
+    // this probe actually targets — instead of a GH_HOST-derived scope.
+    await ghExecFileAsync(
+      ['auth', 'status', '--hostname', 'github.com'],
+      connectionId
+        ? { host: 'github.com' }
+        : { cwd: repoPath, ...getHostedReviewLocalGitOptions(options), host: 'github.com' }
+    )
+    return true
+  } catch {
+    return false
+  } finally {
+    release()
+  }
+}
+
+async function isGitLabAuthenticated(
+  repoPath: string,
+  connectionId?: string | null,
+  options: HostedReviewExecutionOptions = {}
+): Promise<boolean> {
+  const projectRef = await getProjectSlug(repoPath, connectionId, options)
+  if (!projectRef) {
+    return false
+  }
+  await acquireGlab()
+  try {
+    await glabExecFileAsync(['auth', 'status', '--hostname', projectRef.host], {
+      ...glabRepoExecOptions(repoPath, connectionId),
+      ...(connectionId ? {} : getHostedReviewLocalGitOptions(options))
+    })
+    return true
+  } catch {
+    return false
+  } finally {
+    releaseGlab()
+  }
+}
+
+export function reviewCopy(provider: HostedReviewProvider): {
+  shortLabel: 'PR' | 'MR'
+  reviewLabel: 'pull request' | 'merge request'
+  providerName: string
+  authInstruction: string
+} {
+  if (provider === 'gitlab') {
+    return {
+      shortLabel: 'MR',
+      reviewLabel: 'merge request',
+      providerName: 'GitLab',
+      authInstruction: 'Run glab auth login'
+    }
+  }
+  if (provider === 'azure-devops') {
+    return {
+      shortLabel: 'PR',
+      reviewLabel: 'pull request',
+      providerName: 'Azure DevOps',
+      authInstruction: 'Set ORCA_AZURE_DEVOPS_TOKEN'
+    }
+  }
+  if (provider === 'gitea') {
+    return {
+      shortLabel: 'PR',
+      reviewLabel: 'pull request',
+      providerName: 'Gitea',
+      authInstruction: 'Set ORCA_GITEA_TOKEN'
+    }
+  }
+  if (provider === 'bitbucket') {
+    return {
+      shortLabel: 'PR',
+      reviewLabel: 'pull request',
+      providerName: 'Bitbucket',
+      authInstruction: 'Connect Bitbucket in Settings > Integrations'
+    }
+  }
+  return {
+    shortLabel: 'PR',
+    reviewLabel: 'pull request',
+    providerName: 'GitHub',
+    authInstruction: 'Run gh auth login'
+  }
+}
+
+export async function isProviderAuthenticated(
+  provider: HostedReviewCreationProvider,
+  repoPath: string,
+  connectionId?: string | null,
+  options: HostedReviewExecutionOptions = {}
+): Promise<boolean> {
+  if (provider === 'gitlab') {
+    return isGitLabAuthenticated(repoPath, connectionId, options)
+  }
+  if (provider === 'azure-devops') {
+    return isAzureDevOpsReviewCreationAuthenticated()
+  }
+  if (provider === 'gitea') {
+    return isGiteaReviewCreationAuthenticated()
+  }
+  if (provider === 'bitbucket') {
+    // Why: falling through to the GitHub check made Create PR unusable for
+    // anyone with Bitbucket connected but no `gh auth login`.
+    return isBitbucketReviewCreationAuthenticated()
+  }
+  return isGitHubAuthenticated(repoPath, connectionId, options)
+}
diff --git a/src/main/source-control/hosted-review-creation.ts b/src/main/source-control/hosted-review-creation.ts
index 9c9be75ab24..a3e06a3acc0 100644
--- a/src/main/source-control/hosted-review-creation.ts
+++ b/src/main/source-control/hosted-review-creation.ts
@@ -1,46 +1,28 @@
-/* eslint-disable max-lines -- Why: detection, eligibility, and creation preflight share one boundary so gating can't drift. */
 import type {
   CreateHostedReviewInput,
   CreateHostedReviewResult,
-  HostedReviewCreationBlockedReason,
   HostedReviewCreationEligibility,
   HostedReviewCreationEligibilityArgs,
-  HostedReviewLookupOutcome,
-  HostedReviewProvider
+  HostedReviewLookupOutcome
 } from '../../shared/hosted-review'
-import {
-  normalizeHostedReviewBaseRef,
-  normalizeHostedReviewHeadRef
-} from '../../shared/hosted-review-refs'
-import {
-  supportsHostedReviewCreation,
-  type HostedReviewCreationProvider
-} from '../../shared/hosted-review-creation-providers'
-import { isAzureDevOpsReviewCreationAuthenticated } from '../azure-devops/pull-request-creation'
-import { isGiteaReviewCreationAuthenticated } from '../gitea/pull-request-creation'
-import { isBitbucketReviewCreationAuthenticated } from '../bitbucket/pull-request-creation'
-import { getEnterpriseGitHubRepoSlug } from '../github/github-enterprise-repository'
+import { supportsHostedReviewCreation } from '../../shared/hosted-review-creation-providers'
+import { normalizeHostedReviewBaseRef } from '../../shared/hosted-review-refs'
 import { getRepoSlug } from '../github/client'
 import { isDefaultGitHubHost } from '../../shared/github/repository-identity-key'
-import { acquire, ghExecFileAsync, gitExecFileAsync, release } from '../github/gh-utils'
-import { isNoUpstreamError, normalizeGitErrorMessage } from '../../shared/git-remote-error'
-import type { GitUpstreamStatus } from '../../shared/git-status-types'
-import { gitOptionalLocksDisabledEnv } from '../git/runner'
-import { parsePorcelainV1Records, type PorcelainV1Record } from '../git/porcelain-v1-records'
-import { findExistingWorktreeSymlinkPaths } from '../git/worktree-symlink-detection'
-import { resolveDefaultBaseRefViaExec } from '../git/repo'
-import { getUpstreamStatus } from '../git/upstream'
-import { getProjectSlug } from '../gitlab/client'
-import {
-  acquire as acquireGlab,
-  glabExecFileAsync,
-  glabRepoExecOptions,
-  release as releaseGlab
-} from '../gitlab/gl-utils'
-import { getSshGitProvider } from '../providers/ssh-git-dispatch'
 import { detectHostedReviewProvider, getForgeProviderForRepository } from './forge-provider'
 import { invalidateHostedReviewBranchCache } from './hosted-review-branch-cache'
 import { getHostedReviewForBranch } from './hosted-review'
+import { blockedEligibilityToCreateResult } from './hosted-review-creation-blocking'
+import {
+  baseRefExistsOnRemote,
+  getCurrentBranch,
+  getDefaultBaseRef,
+  getHostedReviewUpstreamStatus,
+  hasUncommittedChanges,
+  hostedReviewExecutionContext,
+  stripRefPrefix
+} from './hosted-review-creation-git-state'
+import { isProviderAuthenticated, reviewCopy } from './hosted-review-creation-provider'
 import {
   getHostedReviewLocalGitOptions,
   type HostedReviewExecutionOptions
@@ -52,382 +34,6 @@ type HostedReviewCreationEligibilityInput = HostedReviewCreationEligibilityArgs
   enforceBaseOnRemote?: boolean
 } & HostedReviewExecutionOptions
 
-function stripRefPrefix(ref: string): string {
-  return normalizeHostedReviewHeadRef(ref)
-}
-
-function hostedReviewExecutionContext(
-  options: HostedReviewExecutionOptions = {}
-): HostedReviewExecutionOptions {
-  const localGitExecOptions = getHostedReviewLocalGitOptions(options)
-  return Object.keys(localGitExecOptions).length > 0 ? { localGitExecOptions } : {}
-}
-
-async function isGitHubAuthenticated(
-  repoPath: string,
-  connectionId?: string | null,
-  options: HostedReviewExecutionOptions = {}
-): Promise<boolean> {
-  // Why: a non-null enterprise slug already means gh is authenticated there, so skip a redundant probe (#8312).
-  if (await getEnterpriseGitHubRepoSlug(repoPath, connectionId, options)) {
-    return true
-  }
-  await acquire()
-  try {
-    // Why: `host` scopes any rate-limit breaker trip to github.com — the host
-    // this probe actually targets — instead of a GH_HOST-derived scope.
-    await ghExecFileAsync(
-      ['auth', 'status', '--hostname', 'github.com'],
-      connectionId
-        ? { host: 'github.com' }
-        : { cwd: repoPath, ...getHostedReviewLocalGitOptions(options), host: 'github.com' }
-    )
-    return true
-  } catch {
-    return false
-  } finally {
-    release()
-  }
-}
-
-async function isGitLabAuthenticated(
-  repoPath: string,
-  connectionId?: string | null,
-  options: HostedReviewExecutionOptions = {}
-): Promise<boolean> {
-  const projectRef = await getProjectSlug(repoPath, connectionId, options)
-  if (!projectRef) {
-    return false
-  }
-  await acquireGlab()
-  try {
-    await glabExecFileAsync(['auth', 'status', '--hostname', projectRef.host], {
-      ...glabRepoExecOptions(repoPath, connectionId),
-      ...(connectionId ? {} : getHostedReviewLocalGitOptions(options))
-    })
-    return true
-  } catch {
-    return false
-  } finally {
-    releaseGlab()
-  }
-}
-
-async function runGitForHostedReview(
-  repoPath: string,
-  args: string[],
-  connectionId?: string | null,
-  options: HostedReviewExecutionOptions = {}
-): Promise<{ stdout: string; stderr?: string }> {
-  if (connectionId) {
-    const provider = getSshGitProvider(connectionId)
-    if (!provider) {
-      throw new Error(
-        'Remote connection dropped. Click Reconnect on the SSH target before retrying.'
-      )
-    }
-    return provider.exec(args, repoPath)
-  }
-  return gitExecFileAsync(args, { cwd: repoPath, ...getHostedReviewLocalGitOptions(options) })
-}
-
-async function getDefaultBaseRef(
-  repoPath: string,
-  connectionId?: string | null,
-  options: HostedReviewExecutionOptions = {}
-): Promise<string | null> {
-  return resolveDefaultBaseRefViaExec((argv) =>
-    runGitForHostedReview(repoPath, argv, connectionId, options)
-  )
-}
-
-/**
- * Whether the candidate base resolves to a remote-tracking branch on the
- * executing host.
- *
- * Why: matches under *any* remote (not just origin) and reads the local tracking snapshot, not the live remote.
- */
-async function baseRefExistsOnRemote(
-  candidate: string,
-  repoPath: string,
-  connectionId?: string | null,
-  options: HostedReviewExecutionOptions = {}
-): Promise<boolean> {
-  const base = normalizeHostedReviewBaseRef(candidate).trim()
-  if (!base) {
-    return false
-  }
-  const run = (argv: string[]): Promise<{ stdout: string }> =>
-    runGitForHostedReview(repoPath, argv, connectionId, options)
-
-  const patterns = [`refs/remotes/*/${base}`]
-  // `*` does not cross `/`, so a remote-qualified candidate (e.g. `fork/main`) needs its exact tracking ref too.
-  if (base.includes('/')) {
-    patterns.push(`refs/remotes/${base}`)
-  }
-
-  try {
-    // for-each-ref exits 0 on no match: empty means absent, a thrown error means transport failure (preserve the candidate).
-    const { stdout } = await run(['for-each-ref', '--count=1', '--format=%(refname)', ...patterns])
-    return stdout.trim().length > 0
-  } catch {
-    return true
-  }
-}
-
-async function getCurrentBranch(
-  repoPath: string,
-  connectionId?: string | null,
-  options: HostedReviewExecutionOptions = {}
-): Promise<string> {
-  const { stdout } = await runGitForHostedReview(
-    repoPath,
-    ['rev-parse', '--abbrev-ref', 'HEAD'],
-    connectionId,
-    options
-  )
-  return stripRefPrefix(stdout.trim())
-}
-
-async function hasUncommittedChanges(
-  repoPath: string,
-  connectionId?: string | null,
-  options: HostedReviewExecutionOptions = {}
-): Promise<boolean> {
-  if (connectionId) {
-    const provider = getSshGitProvider(connectionId)
-    if (!provider) {
-      throw new Error(
-        'Remote connection dropped. Click Reconnect on the SSH target before retrying.'
-      )
-    }
-    // Why: the relay restricts generic git.exec, so use the structured status RPC for SSH dirty checks.
-    // No shared-link exclusion here: remote worktree creation skips the symlink
-    // and shared-directory passes entirely, so a remote worktree never has one.
-    return (await provider.getStatus(repoPath)).entries.length > 0
-  }
-  // Why: `-z` keeps paths raw so the shared-link comparison below can't be
-  // defeated by Git quoting a path with spaces or non-ASCII bytes.
-  const { stdout } = await gitExecFileAsync(['status', '--porcelain', '-z'], {
-    cwd: repoPath,
-    ...getHostedReviewLocalGitOptions(options),
-    // Why: don't take Git's optional index lock while the user may be running fetch/pull/rebase in a terminal.
-    env: gitOptionalLocksDisabledEnv()
-  })
-  const records = parsePorcelainV1Records(stdout)
-  if (records.length === 0) {
-    return false
-  }
-  return await anyRecordIsUserDirt(repoPath, records, options.sharedLinkPaths ?? [])
-}
-
-/** True when any record is real user work rather than a shared symlink Orca put
- *  in the worktree.
- *
- *  Fails closed on purpose: anything not positively identified as an Orca-owned
- *  untracked symlink counts as dirty. A false "clean" would let a review be
- *  created off a branch missing the user's work. */
-async function anyRecordIsUserDirt(
-  worktreePath: string,
-  records: readonly PorcelainV1Record[],
-  sharedLinkPaths: readonly string[]
-): Promise<boolean> {
-  if (sharedLinkPaths.length === 0 || !records.some((record) => record.xy === '??')) {
-    return true
-  }
-  // Why: only entries that are configured AND really symlinks are excluded, so a
-  // regular file the user created at a configured name still blocks creation.
-  const sharedLinks = new Set(await findExistingWorktreeSymlinkPaths(worktreePath, sharedLinkPaths))
-  return records.some((record) => record.xy !== '??' || !sharedLinks.has(record.path))
-}
-
-async function getHostedReviewUpstreamStatus(
-  repoPath: string,
-  connectionId?: string | null,
-  options: HostedReviewExecutionOptions = {}
-): Promise<GitUpstreamStatus> {
-  if (!connectionId) {
-    return getUpstreamStatus(repoPath, undefined, getHostedReviewLocalGitOptions(options))
-  }
-  const provider = getSshGitProvider(connectionId)
-  if (!provider) {
-    throw new Error('Remote connection dropped. Click Reconnect on the SSH target before retrying.')
-  }
-  try {
-    // Why: the relay blocks generic git.exec, so use its dedicated upstream RPC for SSH divergence.
-    return await provider.getUpstreamStatus(repoPath)
-  } catch (error) {
-    if (isNoUpstreamError(error)) {
-      return { hasUpstream: false, ahead: 0, behind: 0 }
-    }
-    throw new Error(normalizeGitErrorMessage(error, 'upstream'))
-  }
-}
-
-function reviewCopy(provider: HostedReviewProvider): {
-  shortLabel: 'PR' | 'MR'
-  reviewLabel: 'pull request' | 'merge request'
-  providerName: string
-  authInstruction: string
-} {
-  if (provider === 'gitlab') {
-    return {
-      shortLabel: 'MR',
-      reviewLabel: 'merge request',
-      providerName: 'GitLab',
-      authInstruction: 'Run glab auth login'
-    }
-  }
-  if (provider === 'azure-devops') {
-    return {
-      shortLabel: 'PR',
-      reviewLabel: 'pull request',
-      providerName: 'Azure DevOps',
-      authInstruction: 'Set ORCA_AZURE_DEVOPS_TOKEN'
-    }
-  }
-  if (provider === 'gitea') {
-    return {
-      shortLabel: 'PR',
-      reviewLabel: 'pull request',
-      providerName: 'Gitea',
-      authInstruction: 'Set ORCA_GITEA_TOKEN'
-    }
-  }
-  if (provider === 'bitbucket') {
-    return {
-      shortLabel: 'PR',
-      reviewLabel: 'pull request',
-      providerName: 'Bitbucket',
-      authInstruction: 'Connect Bitbucket in Settings > Integrations'
-    }
-  }
-  return {
-    shortLabel: 'PR',
-    reviewLabel: 'pull request',
-    providerName: 'GitHub',
-    authInstruction: 'Run gh auth login'
-  }
-}
-
-async function isProviderAuthenticated(
-  provider: HostedReviewCreationProvider,
-  repoPath: string,
-  connectionId?: string | null,
-  options: HostedReviewExecutionOptions = {}
-): Promise<boolean> {
-  if (provider === 'gitlab') {
-    return isGitLabAuthenticated(repoPath, connectionId, options)
-  }
-  if (provider === 'azure-devops') {
-    return isAzureDevOpsReviewCreationAuthenticated()
-  }
-  if (provider === 'gitea') {
-    return isGiteaReviewCreationAuthenticated()
-  }
-  if (provider === 'bitbucket') {
-    // Why: falling through to the GitHub check made Create PR unusable for
-    // anyone with Bitbucket connected but no `gh auth login`.
-    return isBitbucketReviewCreationAuthenticated()
-  }
-  return isGitHubAuthenticated(repoPath, connectionId, options)
-}
-
-function blockedCreateResultForReason(
-  reason: NonNullable<HostedReviewCreationBlockedReason>,
-  provider: HostedReviewProvider,
-  submittedBase?: string | null
-): CreateHostedReviewResult | null {
-  const copy = reviewCopy(provider)
-  const baseLabel = submittedBase?.trim() ? `"${submittedBase.trim()}" ` : ''
-  const blockedCreateResultByReason = {
-    auth_required: {
-      ok: false,
-      code: 'auth_required',
-      error: `Create ${copy.shortLabel} failed: ${copy.providerName} is not authenticated. Next step: ${copy.authInstruction} in this environment.`
-    },
-    unsupported_provider: {
-      ok: false,
-      code: 'unsupported_provider',
-      error: `Creating ${copy.reviewLabel}s requires a ${copy.providerName} remote.`
-    },
-    dirty: {
-      ok: false,
-      code: 'validation',
-      error: `Create ${copy.shortLabel} failed: commit or discard local changes before creating a ${copy.reviewLabel}.`
-    },
-    detached_head: {
-      ok: false,
-      code: 'validation',
-      error: `Create ${copy.shortLabel} failed: switch to a branch before creating a ${copy.reviewLabel}.`
-    },
-    default_branch: {
-      ok: false,
-      code: 'validation',
-      error: `Create ${copy.shortLabel} failed: choose a feature branch before creating a ${copy.reviewLabel}.`
-    },
-    no_upstream: {
-      ok: false,
-      code: 'validation',
-      error: `Create ${copy.shortLabel} failed: publish this branch before creating a ${copy.reviewLabel}.`
-    },
-    needs_push: {
-      ok: false,
-      code: 'validation',
-      error: `Create ${copy.shortLabel} failed: push this branch before creating a ${copy.reviewLabel}.`
-    },
-    needs_sync: {
-      ok: false,
-      code: 'validation',
-      error: `Create ${copy.shortLabel} failed: sync this branch before creating a ${copy.reviewLabel}.`
-    },
-    fork_head_unsupported: {
-      ok: false,
-      code: 'validation',
-      error: `Create ${copy.shortLabel} failed: refresh source control status and try again.`
-    },
-    base_not_on_remote: {
-      ok: false,
-      code: 'validation',
-      error: `Create ${copy.shortLabel} failed: the base branch ${baseLabel}hasn't been pushed to the remote. Choose a pushed base or push it first.`
-    }
-  } satisfies Partial<
-    Record<NonNullable<HostedReviewCreationBlockedReason>, CreateHostedReviewResult>
-  >
-  return blockedCreateResultByReason[reason] ?? null
-}
-
-function blockedEligibilityToCreateResult(
-  eligibility: HostedReviewCreationEligibility,
-  submittedBase?: string | null
-): CreateHostedReviewResult | null {
-  if (eligibility.canCreate) {
-    return null
-  }
-  if (eligibility.review?.url) {
-    const copy = reviewCopy(eligibility.provider)
-    return {
-      ok: false,
-      code: 'already_exists',
-      error: `A ${copy.reviewLabel} already exists for this branch.`,
-      existingReview: eligibility.review
-    }
-  }
-  if (eligibility.blockedReason) {
-    return blockedCreateResultForReason(
-      eligibility.blockedReason,
-      eligibility.provider,
-      submittedBase
-    )
-  }
-  const copy = reviewCopy(eligibility.provider)
-  return {
-    ok: false,
-    code: 'validation',
-    error: `Create ${copy.shortLabel} failed: refresh source control status and try again.`
-  }
-}
-
 async function validateCurrentBranchCanCreateReview(
   repoPath: string,
   connectionId: string | null | undefined,

From ca6401a08fa6c225d1b93af55b9e41549db6affc Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sat, 29 Aug 2026 20:12:21 -0700
Subject: [PATCH 29/31] Split automation dispatch event handling (#17155)

* Split speech session lifecycle

* Split terminal output scheduler pipeline

* Split mobile browser pane modules

* Prune resolved max-lines suppressions

* Split pane tree equalization logic

* Extract mobile troubleshoot screen styles

* Split external automation manager

* Split main window service attachments

* Split hosted review creation checks

* Split automation dispatch event handling

* Fix F3-speech for #17123

* Fix F1-cycle for #17131
---
 config/max-lines-baseline.txt                 |   1 -
 .../hooks/automation-dispatch-completion.ts   | 266 +++++++
 .../src/hooks/automation-dispatch-handler.ts  | 239 ++++++
 .../hooks/automation-dispatch-workspace.ts    | 269 +++++++
 .../src/hooks/useAutomationDispatchEvents.ts  | 695 +-----------------
 5 files changed, 776 insertions(+), 694 deletions(-)
 create mode 100644 src/renderer/src/hooks/automation-dispatch-completion.ts
 create mode 100644 src/renderer/src/hooks/automation-dispatch-handler.ts
 create mode 100644 src/renderer/src/hooks/automation-dispatch-workspace.ts

diff --git a/config/max-lines-baseline.txt b/config/max-lines-baseline.txt
index fbc4a24ed38..59162f7e001 100644
--- a/config/max-lines-baseline.txt
+++ b/config/max-lines-baseline.txt
@@ -56,7 +56,6 @@ inline src/renderer/src/components/status-bar/WorkspaceSpaceManagerPanel.tsx
 inline src/renderer/src/components/terminal-pane/TerminalPane.tsx
 inline src/renderer/src/components/terminal-pane/remote-runtime-pty-transport.ts
 inline src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts
-inline src/renderer/src/hooks/useAutomationDispatchEvents.ts
 inline src/renderer/src/hooks/useSettingsNavigationMetadata.ts
 inline src/renderer/src/runtime/remote-runtime-terminal-multiplexer.ts
 inline src/renderer/src/runtime/runtime-file-client.ts
diff --git a/src/renderer/src/hooks/automation-dispatch-completion.ts b/src/renderer/src/hooks/automation-dispatch-completion.ts
new file mode 100644
index 00000000000..098d1167a38
--- /dev/null
+++ b/src/renderer/src/hooks/automation-dispatch-completion.ts
@@ -0,0 +1,266 @@
+import {
+  createAutomationRunOutputSnapshotBuffer,
+  selectAutomationRunOutputSnapshot
+} from '@/components/automations/automation-run-output-snapshot'
+import { useAppStore } from '@/store'
+import type {
+  AutomationDispatchResult,
+  AutomationPrecheckResult,
+  AutomationRun
+} from '../../../shared/automations-types'
+import type { AgentStateHistoryEntry, AgentStatusEntry } from '../../../shared/agent-status-types'
+import {
+  selectAutomationAgentStatusEntryChange,
+  UNCHANGED_AUTOMATION_AGENT_STATUS_ENTRY
+} from './automation-agent-status-entry-change'
+import type { Worktree } from '../../../shared/worktree/types'
+
+type MarkDispatchResult = (result: AutomationDispatchResult) => Promise<void>
+
+export function createAutomationDispatchCompletion(args: {
+  run: AutomationRun
+  worktree: Worktree
+  precheckResult: AutomationPrecheckResult | null
+  markDispatchResult: MarkDispatchResult
+  releaseTerminalOwnership: () => void
+  finalizeTerminalOwnership: () => boolean
+}) {
+  const outputSnapshotBuffer = createAutomationRunOutputSnapshotBuffer()
+  let latestAssistantMessage: string | null = null
+  const getOutputSnapshot = () =>
+    selectAutomationRunOutputSnapshot(latestAssistantMessage, outputSnapshotBuffer.snapshot())
+  let dispatchMarked = false
+  let pendingExitCode: number | null = null
+  let pendingDone = false
+  let completionMarked = false
+  let unsubscribeAgentStatus = (): void => {}
+  let unsubscribeSessionObserver = (): void => {}
+  let releaseReuseDispatchTab = (): void => {}
+  const cleanupRunObservers = (): void => {
+    unsubscribeAgentStatus()
+    unsubscribeSessionObserver()
+    releaseReuseDispatchTab()
+    unsubscribeAgentStatus = (): void => {}
+    unsubscribeSessionObserver = (): void => {}
+    releaseReuseDispatchTab = (): void => {}
+  }
+  const markCompletionResult = async (): Promise<void> => {
+    if (completionMarked) {
+      return
+    }
+    completionMarked = true
+    cleanupRunObservers()
+    try {
+      await args.markDispatchResult({
+        runId: args.run.id,
+        status: 'completed',
+        workspaceId: args.worktree.id,
+        workspaceDisplayName: args.worktree.displayName,
+        outputSnapshot: getOutputSnapshot(),
+        precheckResult: args.precheckResult,
+        error: null
+      })
+    } catch (error) {
+      args.releaseTerminalOwnership()
+      throw error
+    }
+    if (args.finalizeTerminalOwnership()) {
+      await clearRetiredRunTerminalIdentity()
+    }
+  }
+  const clearRetiredRunTerminalIdentity = async (): Promise<void> => {
+    // Why: the owned terminal was just retired, so the run's pane/pty
+    // pointers now reference a closed tab. Drop them (best-effort) so
+    // "View run" resolves to the workspace/snapshot instead of dead-ending
+    // on an unavailable terminal.
+    try {
+      await args.markDispatchResult({
+        runId: args.run.id,
+        status: 'completed',
+        terminalSessionId: null,
+        terminalPaneKey: null,
+        terminalPtyId: null
+      })
+    } catch (error) {
+      console.error('[automations] Failed to clear retired terminal identity:', error)
+    }
+  }
+  const markExitResult = async (code: number): Promise<void> => {
+    if (completionMarked) {
+      return
+    }
+    completionMarked = true
+    cleanupRunObservers()
+    try {
+      await args.markDispatchResult({
+        runId: args.run.id,
+        status: code === 0 ? 'completed' : 'dispatch_failed',
+        workspaceId: args.worktree.id,
+        workspaceDisplayName: args.worktree.displayName,
+        outputSnapshot: getOutputSnapshot(),
+        precheckResult: args.precheckResult,
+        error: code === 0 ? null : `Automation process exited with code ${code}.`
+      })
+    } catch (error) {
+      args.releaseTerminalOwnership()
+      throw error
+    }
+    if (code === 0) {
+      if (args.finalizeTerminalOwnership()) {
+        await clearRetiredRunTerminalIdentity()
+      }
+    } else {
+      args.releaseTerminalOwnership()
+    }
+  }
+  const settleLateResult = (result: Promise<void>): void => {
+    // Why: status/exit callbacks have no awaitable caller; the result
+    // path already releases ownership before propagating persistence errors.
+    void result.catch((error) => {
+      console.error('[automations] Failed to persist late automation result:', error)
+    })
+  }
+  const handleAgentDone = (): void => {
+    if (completionMarked) {
+      return
+    }
+    if (!dispatchMarked) {
+      pendingDone = true
+      return
+    }
+    settleLateResult(markCompletionResult())
+  }
+  const handleExit = (code: number): void => {
+    if (completionMarked) {
+      return
+    }
+    if (!dispatchMarked) {
+      pendingExitCode = code
+      return
+    }
+    settleLateResult(markExitResult(code))
+  }
+  const observeAgentStatus = (
+    targetPaneKey: string,
+    startedAfter: number,
+    options?: { requireWorkingAfterStart?: boolean }
+  ): void => {
+    let sawWorkingAfterStart = false
+    let observedStateHistory: AgentStateHistoryEntry[] = []
+    let observedEntry: AgentStatusEntry | undefined
+    const checkCurrentStatus = (): void => {
+      const entryChange = selectAutomationAgentStatusEntryChange(
+        useAppStore.getState().agentStatusByPaneKey,
+        targetPaneKey,
+        observedEntry
+      )
+      if (entryChange === UNCHANGED_AUTOMATION_AGENT_STATUS_ENTRY) {
+        return
+      }
+      const entry = entryChange
+      observedEntry = entry
+      if (!entry || entry.updatedAt < startedAfter) {
+        return
+      }
+      const historyOverlap = getAgentStateHistoryOverlap(observedStateHistory, entry.stateHistory)
+      // Why: sawWorkingAfterStart stays monotonic — a recreated entry
+      // (transport loss, PTY exit, cap eviction) arrives with an empty
+      // stateHistory, so clearing it here would strand reuseSession runs
+      // with nothing left to re-derive the working edge from.
+      for (const historicalState of entry.stateHistory.slice(historyOverlap)) {
+        if (historicalState.startedAt < startedAfter) {
+          continue
+        }
+        if (historicalState.state === 'working') {
+          sawWorkingAfterStart = true
+        }
+        if (
+          historicalState.state === 'done' &&
+          (!options?.requireWorkingAfterStart || sawWorkingAfterStart)
+        ) {
+          // Why: this `done` already rolled out of the live entry, so its output
+          // survives only in the entry-level completed slot.
+          latestAssistantMessage =
+            entry.lastCompletedAssistantMessage?.trim() || latestAssistantMessage
+          handleAgentDone()
+          return
+        }
+      }
+      observedStateHistory = [...entry.stateHistory]
+      if (entry.state === 'working') {
+        sawWorkingAfterStart = true
+      }
+      if (
+        entry.state === 'done' &&
+        // Why: a session-boundary done is the agent CONNECTING (Claude SessionStart
+        // fires at launch, before the argv prompt submits) — completing here would
+        // close the tab and record an empty run result.
+        entry.sessionBoundary !== true &&
+        (!options?.requireWorkingAfterStart || sawWorkingAfterStart)
+      ) {
+        latestAssistantMessage = entry.lastAssistantMessage?.trim() || latestAssistantMessage
+        handleAgentDone()
+      }
+    }
+    // Why: Codex/Claude completion normally arrives through the global
+    // hook IPC listener, not the hidden PTY OSC fallback.
+    unsubscribeAgentStatus = useAppStore.subscribe(checkCurrentStatus)
+    checkCurrentStatus()
+  }
+
+  return {
+    appendOutput: (chunk: string) => outputSnapshotBuffer.append(chunk),
+    captureAssistantMessage: (message: string | null | undefined) => {
+      latestAssistantMessage = message?.trim() || latestAssistantMessage
+    },
+    cleanupRunObservers,
+    handleAgentDone,
+    handleExit,
+    observeAgentStatus,
+    setReuseDispatchTabRelease: (release: () => void) => {
+      releaseReuseDispatchTab = release
+    },
+    setSessionObserver: (unsubscribe: () => void) => {
+      unsubscribeSessionObserver = unsubscribe
+    },
+    settlePendingAfterDispatch: async () => {
+      dispatchMarked = true
+      if (pendingDone) {
+        await markCompletionResult()
+      } else if (pendingExitCode !== null) {
+        await markExitResult(pendingExitCode)
+      }
+    }
+  }
+}
+
+function agentStateHistoryEntriesEqual(
+  left: AgentStateHistoryEntry,
+  right: AgentStateHistoryEntry
+): boolean {
+  return (
+    left.state === right.state &&
+    left.prompt === right.prompt &&
+    left.startedAt === right.startedAt &&
+    left.interrupted === right.interrupted
+  )
+}
+
+function getAgentStateHistoryOverlap(
+  previous: AgentStateHistoryEntry[],
+  current: AgentStateHistoryEntry[]
+): number {
+  for (let overlap = Math.min(previous.length, current.length); overlap > 0; overlap -= 1) {
+    const previousOffset = previous.length - overlap
+    if (
+      current
+        .slice(0, overlap)
+        .every((entry, index) =>
+          agentStateHistoryEntriesEqual(entry, previous[previousOffset + index])
+        )
+    ) {
+      return overlap
+    }
+  }
+  return 0
+}
diff --git a/src/renderer/src/hooks/automation-dispatch-handler.ts b/src/renderer/src/hooks/automation-dispatch-handler.ts
new file mode 100644
index 00000000000..6df1a64fb58
--- /dev/null
+++ b/src/renderer/src/hooks/automation-dispatch-handler.ts
@@ -0,0 +1,239 @@
+import { listAutomationRunsForTarget } from '@/components/automations/automation-host-client'
+import { translate } from '@/i18n/i18n'
+import { submitPromptToAgentPty } from '@/lib/agent-paste-draft'
+import { launchAgentBackgroundSession } from '@/lib/launch-agent-background-session'
+import { observeExistingAutomationSession } from '@/lib/automation-session-observer'
+import { findReusableAutomationSession } from '@/lib/automation-session-reuse'
+import type { AutomationTerminalOwnership } from '@/lib/automation-terminal-ownership'
+import { useAppStore } from '@/store'
+import type {
+  AutomationDispatchRequest,
+  AutomationDispatchResult
+} from '../../../shared/automations-types'
+import { createAutomationDispatchCompletion } from './automation-dispatch-completion'
+import {
+  prepareAutomationDispatchWorkspace,
+  resolveAutomationDispatchWorkspace
+} from './automation-dispatch-workspace'
+
+const activeReuseDispatchTabIds = new Set<string>()
+
+function acquireReuseDispatchTab(tabId: string): (() => void) | null {
+  if (activeReuseDispatchTabIds.has(tabId)) {
+    return null
+  }
+  activeReuseDispatchTabIds.add(tabId)
+  return () => activeReuseDispatchTabIds.delete(tabId)
+}
+
+export async function handleAutomationDispatchRequest({
+  automation,
+  run,
+  dispatchToken
+}: AutomationDispatchRequest): Promise<void> {
+  const markDispatchResult = async (result: AutomationDispatchResult): Promise<void> => {
+    // Deliberately no local emit: the write publishes its own host-scoped event
+    // (automation-run-writer.ts) before this reply returns, and an unscoped one
+    // here would arrive second and invalidate every host in the catalog.
+    await window.api.automations.markDispatchResult(result)
+  }
+  const state = useAppStore.getState()
+  const focusBeforeDispatch = {
+    activeView: state.activeView,
+    activeWorktreeId: state.activeWorktreeId,
+    activeTabId: state.activeTabId,
+    activeTabType: state.activeTabType
+  }
+  const resolved = resolveAutomationDispatchWorkspace(state, automation, run)
+  let terminalOwnership: AutomationTerminalOwnership | null = null
+  const releaseTerminalOwnership = (): void => {
+    const ownership = terminalOwnership
+    terminalOwnership = null
+    ownership?.release()
+  }
+  const finalizeTerminalOwnership = (): boolean => {
+    const ownership = terminalOwnership
+    terminalOwnership = null
+    return ownership?.finalize() ?? false
+  }
+
+  if (!resolved.repo) {
+    await markDispatchResult({
+      runId: run.id,
+      status: 'skipped_unavailable',
+      workspaceId: run.workspaceId,
+      workspaceDisplayName: run.workspaceDisplayName ?? null,
+      error: translate(
+        'auto.hooks.useAutomationDispatchEvents.386db94f3e',
+        'The target project is no longer available.'
+      )
+    })
+    return
+  }
+
+  try {
+    const worktree = await prepareAutomationDispatchWorkspace({
+      state,
+      automation,
+      run,
+      dispatchToken,
+      resolved: { ...resolved, repo: resolved.repo },
+      markDispatchResult
+    })
+    if (!worktree) {
+      return
+    }
+    const completion = createAutomationDispatchCompletion({
+      run,
+      worktree,
+      precheckResult: resolved.context.precheckResult,
+      markDispatchResult,
+      releaseTerminalOwnership,
+      finalizeTerminalOwnership
+    })
+    const dispatchStartedAt = Date.now()
+    if (automation.reuseSession) {
+      const reusableSession = findReusableAutomationSession({
+        automationId: automation.id,
+        agentId: automation.agentId,
+        worktreeId: worktree.id,
+        currentRunId: run.id,
+        // Why: the dispatch loop only ever executes for the desktop authority,
+        // so its history read addresses the local runtime explicitly.
+        runs: await listAutomationRunsForTarget({ kind: 'local' }, automation.id),
+        state: useAppStore.getState()
+      })
+      if (reusableSession) {
+        const releaseTab = acquireReuseDispatchTab(reusableSession.tabId)
+        if (releaseTab) {
+          completion.setReuseDispatchTabRelease(releaseTab)
+          try {
+            const submitted = await submitPromptToAgentPty({
+              tabId: reusableSession.tabId,
+              ptyId: reusableSession.ptyId,
+              content: automation.prompt
+            })
+            if (!submitted) {
+              completion.cleanupRunObservers()
+            } else {
+              let reuseSawWorking = false
+              const handleReusableAgentStatus = (payload: { state: string }): void => {
+                if (payload.state === 'working') {
+                  reuseSawWorking = true
+                  return
+                }
+                if (payload.state === 'done' && reuseSawWorking) {
+                  completion.handleAgentDone()
+                }
+              }
+              const reuseCompletionStartedAt = Date.now()
+              completion.setSessionObserver(
+                await observeExistingAutomationSession({
+                  ptyId: reusableSession.ptyId,
+                  paneKey: reusableSession.paneKey,
+                  runId: run.id,
+                  onData: completion.appendOutput,
+                  onAgentStatus: (payload) => {
+                    completion.captureAssistantMessage(payload.lastAssistantMessage)
+                    handleReusableAgentStatus(payload)
+                  },
+                  onExit: completion.handleExit
+                })
+              )
+              completion.observeAgentStatus(reusableSession.paneKey, reuseCompletionStartedAt, {
+                requireWorkingAfterStart: true
+              })
+              await markDispatchResult({
+                runId: run.id,
+                status: 'dispatched',
+                workspaceId: worktree.id,
+                workspaceDisplayName: worktree.displayName,
+                terminalSessionId: reusableSession.tabId,
+                terminalPaneKey: reusableSession.paneKey,
+                terminalPtyId: reusableSession.ptyId,
+                precheckResult: resolved.context.precheckResult,
+                error: null
+              })
+              await completion.settlePendingAfterDispatch()
+              return
+            }
+          } catch (error) {
+            completion.cleanupRunObservers()
+            throw error
+          }
+        }
+      }
+    }
+    const result = await launchAgentBackgroundSession({
+      agent: automation.agentId,
+      worktreeId: worktree.id,
+      prompt: automation.prompt,
+      launchSource: 'unknown',
+      title: run.title,
+      onData: completion.appendOutput,
+      onAgentStatus: (payload) => {
+        completion.captureAssistantMessage(payload.lastAssistantMessage)
+        // Why: session-boundary done = launch connect, not run completion (see observeAgentStatus).
+        if (payload.state !== 'done' || payload.sessionBoundary === true) {
+          return
+        }
+        completion.handleAgentDone()
+      },
+      onExit: (_ptyId, code) => {
+        completion.handleExit(code)
+      }
+    })
+    if (!result) {
+      throw new Error('Unable to build an agent launch plan.')
+    }
+    terminalOwnership = result.terminalOwnership
+    if (automation.reuseSession) {
+      // Why: the first fresh launch is the seed for later reuse and must
+      // survive completion under the same policy as an already-reused tab.
+      releaseTerminalOwnership()
+    }
+    const launchedTabId = result.tabId
+    completion.observeAgentStatus(result.paneKey, dispatchStartedAt)
+    try {
+      await markDispatchResult({
+        runId: run.id,
+        status: 'dispatched',
+        workspaceId: worktree.id,
+        workspaceDisplayName: worktree.displayName,
+        terminalSessionId: launchedTabId,
+        terminalPaneKey: result.paneKey,
+        terminalPtyId: result.ptyId,
+        precheckResult: resolved.context.precheckResult,
+        error: null
+      })
+      await completion.settlePendingAfterDispatch()
+    } catch (error) {
+      completion.cleanupRunObservers()
+      throw error
+    }
+    const currentState = useAppStore.getState()
+    // Why: Run Now and scheduled dispatches should create workspaces/tabs in
+    // the background; only an explicit row click should navigate there.
+    if (
+      focusBeforeDispatch.activeWorktreeId !== worktree.id &&
+      currentState.activeWorktreeId === worktree.id
+    ) {
+      currentState.setActiveView(focusBeforeDispatch.activeView)
+      currentState.setActiveWorktree(focusBeforeDispatch.activeWorktreeId)
+      if (focusBeforeDispatch.activeTabId) {
+        currentState.setActiveTab(focusBeforeDispatch.activeTabId)
+      }
+      currentState.setActiveTabType(focusBeforeDispatch.activeTabType)
+    }
+  } catch (error) {
+    releaseTerminalOwnership()
+    await markDispatchResult({
+      runId: run.id,
+      status: 'dispatch_failed',
+      workspaceId: resolved.context.workspaceId,
+      workspaceDisplayName: resolved.context.workspaceDisplayName,
+      precheckResult: resolved.context.precheckResult,
+      error: error instanceof Error ? error.message : String(error)
+    })
+  }
+}
diff --git a/src/renderer/src/hooks/automation-dispatch-workspace.ts b/src/renderer/src/hooks/automation-dispatch-workspace.ts
new file mode 100644
index 00000000000..f8980a56108
--- /dev/null
+++ b/src/renderer/src/hooks/automation-dispatch-workspace.ts
@@ -0,0 +1,269 @@
+import { launchWorktreeBackgroundTerminals } from '@/lib/launch-worktree-background-terminals'
+import { useAppStore } from '@/store'
+import { translate } from '@/i18n/i18n'
+import { createBrowserUuid } from '@/lib/browser-uuid'
+import { getResolvedExecutionHostIdForWorktree } from '@/lib/resolved-worktree-execution-host'
+import type {
+  Automation,
+  AutomationDispatchResult,
+  AutomationPrecheckResult,
+  AutomationRun
+} from '../../../shared/automations-types'
+import { getAutomationRunRepoId } from '../../../shared/automation-run-identity'
+import {
+  didAutomationPrecheckPass,
+  formatAutomationPrecheckFailure
+} from '../../../shared/automation-precheck'
+import {
+  getRepoExecutionHostId,
+  parseExecutionHostId,
+  toSshExecutionHostId
+} from '../../../shared/execution-host'
+import { resolveFolderWorkspaceHost } from '../../../shared/folder-workspace-execution-host'
+import type { Worktree } from '../../../shared/worktree/types'
+import { parseWorkspaceKey } from '../../../shared/workspace-scope'
+
+type AutomationDispatchStoreState = ReturnType<typeof useAppStore.getState>
+type MarkDispatchResult = (result: AutomationDispatchResult) => Promise<void>
+
+export type AutomationDispatchWorkspaceContext = {
+  workspaceId: string | null
+  workspaceDisplayName: string | null
+  precheckResult: AutomationPrecheckResult | null
+}
+
+export function resolveAutomationDispatchWorkspace(
+  state: AutomationDispatchStoreState,
+  automation: Automation,
+  run: AutomationRun
+) {
+  const runRepoId = getAutomationRunRepoId(automation)
+  const repo = state.repos.find((entry) => entry.id === runRepoId)
+  const automationWorkspaceScope = parseWorkspaceKey(automation.workspaceId ?? '')
+  const automationWorktree = automation.workspaceId
+    ? automationWorkspaceScope?.type === 'folder'
+      ? state.getKnownWorktreeById(automation.workspaceId)
+      : state.allWorktrees().find((entry) => entry.id === automation.workspaceId)
+    : null
+  const context: AutomationDispatchWorkspaceContext = {
+    workspaceId: automation.workspaceId,
+    workspaceDisplayName: automationWorktree?.displayName ?? run.workspaceDisplayName ?? null,
+    precheckResult: null
+  }
+  return { runRepoId, repo, automationWorkspaceScope, automationWorktree, context }
+}
+
+type ResolvedAutomationDispatchWorkspace = ReturnType<typeof resolveAutomationDispatchWorkspace>
+
+export async function prepareAutomationDispatchWorkspace(args: {
+  state: AutomationDispatchStoreState
+  automation: Automation
+  run: AutomationRun
+  dispatchToken: string
+  resolved: ResolvedAutomationDispatchWorkspace & {
+    repo: NonNullable<ResolvedAutomationDispatchWorkspace['repo']>
+  }
+  markDispatchResult: MarkDispatchResult
+}): Promise<Worktree | null> {
+  const { state, automation, run, dispatchToken, resolved, markDispatchResult } = args
+  const { repo, runRepoId, automationWorkspaceScope, automationWorktree, context } = resolved
+  const folderWorkspaceHost =
+    automationWorkspaceScope?.type === 'folder'
+      ? resolveFolderWorkspaceHost(state, automationWorkspaceScope.folderWorkspaceId)
+      : null
+  const folderWorkspaceConnectionId =
+    folderWorkspaceHost?.kind === 'ssh' ? folderWorkspaceHost.targetId : null
+  // A workspace whose host does not resolve to one place is refused, not guessed at.
+  const folderWorkspaceHostUnresolved =
+    folderWorkspaceHost !== null && folderWorkspaceHost.kind === 'ambiguous'
+  const folderWorkspaceHostId =
+    folderWorkspaceHost && automationWorktree
+      ? folderWorkspaceConnectionId
+        ? toSshExecutionHostId(folderWorkspaceConnectionId)
+        : folderWorkspaceHost.kind === 'local'
+          ? getResolvedExecutionHostIdForWorktree(state, automationWorktree.id)
+          : null
+      : null
+  const runHostId =
+    parseExecutionHostId(automation.runContext?.hostId)?.id ?? getRepoExecutionHostId(repo)
+  const workspaceMatchesRunTarget =
+    automationWorkspaceScope?.type === 'folder'
+      ? folderWorkspaceHostId !== null && folderWorkspaceHostId === runHostId
+      : !automation.runContext?.repoId ||
+        automationWorktree?.repoId === automation.runContext.repoId
+  if (automation.workspaceMode === 'existing' && automationWorktree && !workspaceMatchesRunTarget) {
+    await markDispatchResult({
+      runId: run.id,
+      status: 'skipped_unavailable',
+      workspaceId: automation.workspaceId,
+      workspaceDisplayName: context.workspaceDisplayName,
+      error: folderWorkspaceHostUnresolved
+        ? translate(
+            'auto.hooks.useAutomationDispatchEvents.workspaceHostUnresolved',
+            'The target workspace spans more than one host, so this run has no single host to use.'
+          )
+        : translate(
+            'auto.hooks.useAutomationDispatchEvents.3ad7d77f57',
+            'The target workspace is on a different host than this automation run target.'
+          )
+    })
+    return null
+  }
+  const sshTargetId =
+    automationWorkspaceScope?.type === 'folder'
+      ? (folderWorkspaceConnectionId ?? null)
+      : (repo.connectionId ?? null)
+  if (sshTargetId) {
+    const needsPrompt = await window.api.ssh.needsPassphrasePrompt({
+      targetId: sshTargetId
+    })
+    if (needsPrompt) {
+      await markDispatchResult({
+        runId: run.id,
+        status: 'skipped_needs_interactive_auth',
+        workspaceId: context.workspaceId,
+        workspaceDisplayName: context.workspaceDisplayName,
+        error: translate(
+          'auto.hooks.useAutomationDispatchEvents.16a21d6413',
+          'SSH reconnect requires interactive credentials.'
+        )
+      })
+      return null
+    }
+    const sshState = await window.api.ssh.getState({ targetId: sshTargetId })
+    if (sshState?.status !== 'connected') {
+      try {
+        const connected = await window.api.ssh.connect({ targetId: sshTargetId })
+        if (connected?.status !== 'connected') {
+          throw new Error('SSH target is unavailable.')
+        }
+      } catch (error) {
+        await markDispatchResult({
+          runId: run.id,
+          status: 'skipped_unavailable',
+          workspaceId: context.workspaceId,
+          workspaceDisplayName: context.workspaceDisplayName,
+          error: error instanceof Error ? error.message : String(error)
+        })
+        return null
+      }
+    }
+  }
+
+  if (automation.workspaceMode === 'existing' && !automationWorktree) {
+    await markDispatchResult({
+      runId: run.id,
+      status: 'skipped_unavailable',
+      workspaceId: automation.workspaceId,
+      workspaceDisplayName: context.workspaceDisplayName,
+      error: translate(
+        'auto.hooks.useAutomationDispatchEvents.59718b120b',
+        'The target workspace is no longer available.'
+      )
+    })
+    return null
+  }
+
+  if (run.trigger === 'scheduled' && automation.precheck) {
+    context.precheckResult = await window.api.automations.runPrecheck({
+      automationId: automation.id,
+      runId: run.id
+    })
+    if (context.precheckResult && !didAutomationPrecheckPass(context.precheckResult)) {
+      await markDispatchResult({
+        runId: run.id,
+        status: 'skipped_precheck',
+        workspaceId: context.workspaceId,
+        workspaceDisplayName: context.workspaceDisplayName,
+        precheckResult: context.precheckResult,
+        error: formatAutomationPrecheckFailure(context.precheckResult)
+      })
+      return null
+    }
+  }
+
+  const automationWorkspaceCreateRequestId = createBrowserUuid()
+  const createResult =
+    automation.workspaceMode === 'new_per_run'
+      ? await useAppStore.getState().createWorktree(
+          runRepoId,
+          buildAutomationWorkspaceName(run.title, run.scheduledFor),
+          automation.baseBranch ?? undefined,
+          automation.setupDecision ?? 'skip',
+          undefined,
+          'unknown',
+          run.title,
+          undefined,
+          undefined,
+          undefined,
+          // Why: the automation session below owns the prompt-bearing
+          // agent tab; createdWithAgent would reopen an empty fallback.
+          undefined,
+          undefined,
+          undefined,
+          undefined,
+          undefined,
+          undefined,
+          undefined,
+          undefined,
+          undefined,
+          undefined,
+          undefined,
+          undefined,
+          undefined,
+          undefined,
+          undefined,
+          {
+            automationProvenanceRequest: {
+              automationId: automation.id,
+              automationRunId: run.id,
+              dispatchToken,
+              createRequestId: automationWorkspaceCreateRequestId
+            }
+          }
+        )
+      : null
+  const worktree = createResult
+    ? createResult.worktree
+    : automation.workspaceId
+      ? automationWorktree
+      : null
+
+  if (!worktree) {
+    await markDispatchResult({
+      runId: run.id,
+      status: 'skipped_unavailable',
+      workspaceId: automation.workspaceId,
+      workspaceDisplayName: context.workspaceDisplayName,
+      error: translate(
+        'auto.hooks.useAutomationDispatchEvents.59718b120b',
+        'The target workspace is no longer available.'
+      )
+    })
+    return null
+  }
+  context.workspaceId = worktree.id
+  context.workspaceDisplayName = worktree.displayName
+  if (createResult?.setup || createResult?.defaultTabs) {
+    void launchWorktreeBackgroundTerminals({
+      worktreeId: worktree.id,
+      setup: createResult.setup,
+      defaultTabs: createResult.defaultTabs
+    }).catch((error) => {
+      // Why: setup/defaultTabs match normal worktree creation: they are
+      // best-effort terminal work and must not block the automation agent.
+      console.warn('[automations] Failed to launch workspace setup/default tabs:', error)
+    })
+  }
+  return worktree
+}
+
+function buildAutomationWorkspaceName(runTitle: string, scheduledFor: number): string {
+  const slug = runTitle
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 40)
+  const stamp = new Date(scheduledFor).toISOString().replace(/[-:]/g, '').slice(0, 13)
+  return `auto-${slug || 'run'}-${stamp}`
+}
diff --git a/src/renderer/src/hooks/useAutomationDispatchEvents.ts b/src/renderer/src/hooks/useAutomationDispatchEvents.ts
index e06eefa6e61..f4963a6dea7 100644
--- a/src/renderer/src/hooks/useAutomationDispatchEvents.ts
+++ b/src/renderer/src/hooks/useAutomationDispatchEvents.ts
@@ -1,700 +1,9 @@
-/* eslint-disable max-lines -- Why: automation dispatch is a single renderer lifecycle
- * coordinator spanning workspace creation, SSH readiness, terminal launch/reuse,
- * completion bookkeeping, and focus restoration. */
 import { useEffect } from 'react'
-import { launchAgentBackgroundSession } from '@/lib/launch-agent-background-session'
-import { submitPromptToAgentPty } from '@/lib/agent-paste-draft'
-import { findReusableAutomationSession } from '@/lib/automation-session-reuse'
-import { observeExistingAutomationSession } from '@/lib/automation-session-observer'
-import { launchWorktreeBackgroundTerminals } from '@/lib/launch-worktree-background-terminals'
-import { useAppStore } from '@/store'
-import type {
-  AutomationDispatchResult,
-  AutomationPrecheckResult
-} from '../../../shared/automations-types'
-import { getAutomationRunRepoId } from '../../../shared/automation-run-identity'
-import {
-  didAutomationPrecheckPass,
-  formatAutomationPrecheckFailure
-} from '../../../shared/automation-precheck'
-import {
-  createAutomationRunOutputSnapshotBuffer,
-  selectAutomationRunOutputSnapshot
-} from '@/components/automations/automation-run-output-snapshot'
-import { translate } from '@/i18n/i18n'
-import { createBrowserUuid } from '@/lib/browser-uuid'
-import type { AutomationTerminalOwnership } from '@/lib/automation-terminal-ownership'
-import { getResolvedExecutionHostIdForWorktree } from '@/lib/resolved-worktree-execution-host'
-import { listAutomationRunsForTarget } from '@/components/automations/automation-host-client'
-import {
-  getRepoExecutionHostId,
-  parseExecutionHostId,
-  toSshExecutionHostId
-} from '../../../shared/execution-host'
-import { parseWorkspaceKey } from '../../../shared/workspace-scope'
-import type { AgentStateHistoryEntry, AgentStatusEntry } from '../../../shared/agent-status-types'
-import { resolveFolderWorkspaceHost } from '../../../shared/folder-workspace-execution-host'
-import {
-  selectAutomationAgentStatusEntryChange,
-  UNCHANGED_AUTOMATION_AGENT_STATUS_ENTRY
-} from './automation-agent-status-entry-change'
-
-const activeReuseDispatchTabIds = new Set<string>()
-
-function acquireReuseDispatchTab(tabId: string): (() => void) | null {
-  if (activeReuseDispatchTabIds.has(tabId)) {
-    return null
-  }
-  activeReuseDispatchTabIds.add(tabId)
-  return () => activeReuseDispatchTabIds.delete(tabId)
-}
-
-function buildAutomationWorkspaceName(runTitle: string, scheduledFor: number): string {
-  const slug = runTitle
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-|-$/g, '')
-    .slice(0, 40)
-  const stamp = new Date(scheduledFor).toISOString().replace(/[-:]/g, '').slice(0, 13)
-  return `auto-${slug || 'run'}-${stamp}`
-}
-
-function agentStateHistoryEntriesEqual(
-  left: AgentStateHistoryEntry,
-  right: AgentStateHistoryEntry
-): boolean {
-  return (
-    left.state === right.state &&
-    left.prompt === right.prompt &&
-    left.startedAt === right.startedAt &&
-    left.interrupted === right.interrupted
-  )
-}
-
-function getAgentStateHistoryOverlap(
-  previous: AgentStateHistoryEntry[],
-  current: AgentStateHistoryEntry[]
-): number {
-  for (let overlap = Math.min(previous.length, current.length); overlap > 0; overlap -= 1) {
-    const previousOffset = previous.length - overlap
-    if (
-      current
-        .slice(0, overlap)
-        .every((entry, index) =>
-          agentStateHistoryEntriesEqual(entry, previous[previousOffset + index])
-        )
-    ) {
-      return overlap
-    }
-  }
-  return 0
-}
+import { handleAutomationDispatchRequest } from './automation-dispatch-handler'
 
 export function useAutomationDispatchEvents(): void {
   useEffect(() => {
-    const unsubscribe = window.api.automations.onDispatchRequested(
-      async ({ automation, run, dispatchToken }) => {
-        const markDispatchResult = async (result: AutomationDispatchResult): Promise<void> => {
-          // Deliberately no local emit: the write publishes its own host-scoped event
-          // (automation-run-writer.ts) before this reply returns, and an unscoped one
-          // here would arrive second and invalidate every host in the catalog.
-          await window.api.automations.markDispatchResult(result)
-        }
-        const state = useAppStore.getState()
-        const focusBeforeDispatch = {
-          activeView: state.activeView,
-          activeWorktreeId: state.activeWorktreeId,
-          activeTabId: state.activeTabId,
-          activeTabType: state.activeTabType
-        }
-        const runRepoId = getAutomationRunRepoId(automation)
-        const repo = state.repos.find((entry) => entry.id === runRepoId)
-        const automationWorkspaceScope = parseWorkspaceKey(automation.workspaceId ?? '')
-        const automationWorktree = automation.workspaceId
-          ? automationWorkspaceScope?.type === 'folder'
-            ? state.getKnownWorktreeById(automation.workspaceId)
-            : state.allWorktrees().find((entry) => entry.id === automation.workspaceId)
-          : null
-        let dispatchWorkspaceId = automation.workspaceId
-        let dispatchWorkspaceDisplayName =
-          automationWorktree?.displayName ?? run.workspaceDisplayName ?? null
-        let precheckResult: AutomationPrecheckResult | null = null
-        let terminalOwnership: AutomationTerminalOwnership | null = null
-        const releaseTerminalOwnership = (): void => {
-          const ownership = terminalOwnership
-          terminalOwnership = null
-          ownership?.release()
-        }
-        const finalizeTerminalOwnership = (): boolean => {
-          const ownership = terminalOwnership
-          terminalOwnership = null
-          return ownership?.finalize() ?? false
-        }
-
-        if (!repo) {
-          await markDispatchResult({
-            runId: run.id,
-            status: 'skipped_unavailable',
-            workspaceId: run.workspaceId,
-            workspaceDisplayName: run.workspaceDisplayName ?? null,
-            error: translate(
-              'auto.hooks.useAutomationDispatchEvents.386db94f3e',
-              'The target project is no longer available.'
-            )
-          })
-          return
-        }
-
-        try {
-          const folderWorkspaceHost =
-            automationWorkspaceScope?.type === 'folder'
-              ? resolveFolderWorkspaceHost(state, automationWorkspaceScope.folderWorkspaceId)
-              : null
-          const folderWorkspaceConnectionId =
-            folderWorkspaceHost?.kind === 'ssh' ? folderWorkspaceHost.targetId : null
-          // A workspace whose host does not resolve to one place is refused, not guessed at.
-          const folderWorkspaceHostUnresolved =
-            folderWorkspaceHost !== null && folderWorkspaceHost.kind === 'ambiguous'
-          const folderWorkspaceHostId =
-            folderWorkspaceHost && automationWorktree
-              ? folderWorkspaceConnectionId
-                ? toSshExecutionHostId(folderWorkspaceConnectionId)
-                : folderWorkspaceHost.kind === 'local'
-                  ? getResolvedExecutionHostIdForWorktree(state, automationWorktree.id)
-                  : null
-              : null
-          const runHostId =
-            parseExecutionHostId(automation.runContext?.hostId)?.id ?? getRepoExecutionHostId(repo)
-          const workspaceMatchesRunTarget =
-            automationWorkspaceScope?.type === 'folder'
-              ? folderWorkspaceHostId !== null && folderWorkspaceHostId === runHostId
-              : !automation.runContext?.repoId ||
-                automationWorktree?.repoId === automation.runContext.repoId
-          if (
-            automation.workspaceMode === 'existing' &&
-            automationWorktree &&
-            !workspaceMatchesRunTarget
-          ) {
-            await markDispatchResult({
-              runId: run.id,
-              status: 'skipped_unavailable',
-              workspaceId: automation.workspaceId,
-              workspaceDisplayName: dispatchWorkspaceDisplayName,
-              error: folderWorkspaceHostUnresolved
-                ? translate(
-                    'auto.hooks.useAutomationDispatchEvents.workspaceHostUnresolved',
-                    'The target workspace spans more than one host, so this run has no single host to use.'
-                  )
-                : translate(
-                    'auto.hooks.useAutomationDispatchEvents.3ad7d77f57',
-                    'The target workspace is on a different host than this automation run target.'
-                  )
-            })
-            return
-          }
-          const sshTargetId =
-            automationWorkspaceScope?.type === 'folder'
-              ? (folderWorkspaceConnectionId ?? null)
-              : (repo.connectionId ?? null)
-          if (sshTargetId) {
-            const needsPrompt = await window.api.ssh.needsPassphrasePrompt({
-              targetId: sshTargetId
-            })
-            if (needsPrompt) {
-              await markDispatchResult({
-                runId: run.id,
-                status: 'skipped_needs_interactive_auth',
-                workspaceId: dispatchWorkspaceId,
-                workspaceDisplayName: dispatchWorkspaceDisplayName,
-                error: translate(
-                  'auto.hooks.useAutomationDispatchEvents.16a21d6413',
-                  'SSH reconnect requires interactive credentials.'
-                )
-              })
-              return
-            }
-            const sshState = await window.api.ssh.getState({ targetId: sshTargetId })
-            if (sshState?.status !== 'connected') {
-              try {
-                const connected = await window.api.ssh.connect({ targetId: sshTargetId })
-                if (connected?.status !== 'connected') {
-                  throw new Error('SSH target is unavailable.')
-                }
-              } catch (error) {
-                await markDispatchResult({
-                  runId: run.id,
-                  status: 'skipped_unavailable',
-                  workspaceId: dispatchWorkspaceId,
-                  workspaceDisplayName: dispatchWorkspaceDisplayName,
-                  error: error instanceof Error ? error.message : String(error)
-                })
-                return
-              }
-            }
-          }
-
-          if (automation.workspaceMode === 'existing' && !automationWorktree) {
-            await markDispatchResult({
-              runId: run.id,
-              status: 'skipped_unavailable',
-              workspaceId: automation.workspaceId,
-              workspaceDisplayName: dispatchWorkspaceDisplayName,
-              error: translate(
-                'auto.hooks.useAutomationDispatchEvents.59718b120b',
-                'The target workspace is no longer available.'
-              )
-            })
-            return
-          }
-
-          if (run.trigger === 'scheduled' && automation.precheck) {
-            precheckResult = await window.api.automations.runPrecheck({
-              automationId: automation.id,
-              runId: run.id
-            })
-            if (precheckResult && !didAutomationPrecheckPass(precheckResult)) {
-              await markDispatchResult({
-                runId: run.id,
-                status: 'skipped_precheck',
-                workspaceId: dispatchWorkspaceId,
-                workspaceDisplayName: dispatchWorkspaceDisplayName,
-                precheckResult,
-                error: formatAutomationPrecheckFailure(precheckResult)
-              })
-              return
-            }
-          }
-
-          const automationWorkspaceCreateRequestId = createBrowserUuid()
-          const createResult =
-            automation.workspaceMode === 'new_per_run'
-              ? await useAppStore.getState().createWorktree(
-                  runRepoId,
-                  buildAutomationWorkspaceName(run.title, run.scheduledFor),
-                  automation.baseBranch ?? undefined,
-                  automation.setupDecision ?? 'skip',
-                  undefined,
-                  'unknown',
-                  run.title,
-                  undefined,
-                  undefined,
-                  undefined,
-                  // Why: the automation session below owns the prompt-bearing
-                  // agent tab; createdWithAgent would reopen an empty fallback.
-                  undefined,
-                  undefined,
-                  undefined,
-                  undefined,
-                  undefined,
-                  undefined,
-                  undefined,
-                  undefined,
-                  undefined,
-                  undefined,
-                  undefined,
-                  undefined,
-                  undefined,
-                  undefined,
-                  undefined,
-                  {
-                    automationProvenanceRequest: {
-                      automationId: automation.id,
-                      automationRunId: run.id,
-                      dispatchToken,
-                      createRequestId: automationWorkspaceCreateRequestId
-                    }
-                  }
-                )
-              : null
-          const worktree = createResult
-            ? createResult.worktree
-            : automation.workspaceId
-              ? automationWorktree
-              : null
-
-          if (!worktree) {
-            await markDispatchResult({
-              runId: run.id,
-              status: 'skipped_unavailable',
-              workspaceId: automation.workspaceId,
-              workspaceDisplayName: dispatchWorkspaceDisplayName,
-              error: translate(
-                'auto.hooks.useAutomationDispatchEvents.59718b120b',
-                'The target workspace is no longer available.'
-              )
-            })
-            return
-          }
-          dispatchWorkspaceId = worktree.id
-          dispatchWorkspaceDisplayName = worktree.displayName
-          if (createResult?.setup || createResult?.defaultTabs) {
-            void launchWorktreeBackgroundTerminals({
-              worktreeId: worktree.id,
-              setup: createResult.setup,
-              defaultTabs: createResult.defaultTabs
-            }).catch((error) => {
-              // Why: setup/defaultTabs match normal worktree creation: they are
-              // best-effort terminal work and must not block the automation agent.
-              console.warn('[automations] Failed to launch workspace setup/default tabs:', error)
-            })
-          }
-
-          const outputSnapshotBuffer = createAutomationRunOutputSnapshotBuffer()
-          let latestAssistantMessage: string | null = null
-          const getOutputSnapshot = () =>
-            selectAutomationRunOutputSnapshot(
-              latestAssistantMessage,
-              outputSnapshotBuffer.snapshot()
-            )
-          let dispatchMarked = false
-          let pendingExitCode: number | null = null
-          let pendingDone = false
-          let completionMarked = false
-          let unsubscribeAgentStatus = (): void => {}
-          let unsubscribeSessionObserver = (): void => {}
-          let releaseReuseDispatchTab = (): void => {}
-          const cleanupRunObservers = (): void => {
-            unsubscribeAgentStatus()
-            unsubscribeSessionObserver()
-            releaseReuseDispatchTab()
-            unsubscribeAgentStatus = (): void => {}
-            unsubscribeSessionObserver = (): void => {}
-            releaseReuseDispatchTab = (): void => {}
-          }
-          const markCompletionResult = async (): Promise<void> => {
-            if (completionMarked) {
-              return
-            }
-            completionMarked = true
-            cleanupRunObservers()
-            try {
-              await markDispatchResult({
-                runId: run.id,
-                status: 'completed',
-                workspaceId: worktree.id,
-                workspaceDisplayName: worktree.displayName,
-                outputSnapshot: getOutputSnapshot(),
-                precheckResult,
-                error: null
-              })
-            } catch (error) {
-              releaseTerminalOwnership()
-              throw error
-            }
-            if (finalizeTerminalOwnership()) {
-              await clearRetiredRunTerminalIdentity()
-            }
-          }
-          const clearRetiredRunTerminalIdentity = async (): Promise<void> => {
-            // Why: the owned terminal was just retired, so the run's pane/pty
-            // pointers now reference a closed tab. Drop them (best-effort) so
-            // "View run" resolves to the workspace/snapshot instead of dead-ending
-            // on an unavailable terminal.
-            try {
-              await markDispatchResult({
-                runId: run.id,
-                status: 'completed',
-                terminalSessionId: null,
-                terminalPaneKey: null,
-                terminalPtyId: null
-              })
-            } catch (error) {
-              console.error('[automations] Failed to clear retired terminal identity:', error)
-            }
-          }
-          const markExitResult = async (code: number): Promise<void> => {
-            if (completionMarked) {
-              return
-            }
-            completionMarked = true
-            cleanupRunObservers()
-            try {
-              await markDispatchResult({
-                runId: run.id,
-                status: code === 0 ? 'completed' : 'dispatch_failed',
-                workspaceId: worktree.id,
-                workspaceDisplayName: worktree.displayName,
-                outputSnapshot: getOutputSnapshot(),
-                precheckResult,
-                error: code === 0 ? null : `Automation process exited with code ${code}.`
-              })
-            } catch (error) {
-              releaseTerminalOwnership()
-              throw error
-            }
-            if (code === 0) {
-              if (finalizeTerminalOwnership()) {
-                await clearRetiredRunTerminalIdentity()
-              }
-            } else {
-              releaseTerminalOwnership()
-            }
-          }
-          const settleLateResult = (result: Promise<void>): void => {
-            // Why: status/exit callbacks have no awaitable caller; the result
-            // path already releases ownership before propagating persistence errors.
-            void result.catch((error) => {
-              console.error('[automations] Failed to persist late automation result:', error)
-            })
-          }
-          const handleAgentDone = (): void => {
-            if (completionMarked) {
-              return
-            }
-            if (!dispatchMarked) {
-              pendingDone = true
-              return
-            }
-            settleLateResult(markCompletionResult())
-          }
-          const observeAgentStatus = (
-            targetPaneKey: string,
-            startedAfter: number,
-            options?: { requireWorkingAfterStart?: boolean }
-          ): void => {
-            let sawWorkingAfterStart = false
-            let observedStateHistory: AgentStateHistoryEntry[] = []
-            let observedEntry: AgentStatusEntry | undefined
-            const checkCurrentStatus = (): void => {
-              const entryChange = selectAutomationAgentStatusEntryChange(
-                useAppStore.getState().agentStatusByPaneKey,
-                targetPaneKey,
-                observedEntry
-              )
-              if (entryChange === UNCHANGED_AUTOMATION_AGENT_STATUS_ENTRY) {
-                return
-              }
-              const entry = entryChange
-              observedEntry = entry
-              if (!entry || entry.updatedAt < startedAfter) {
-                return
-              }
-              const historyOverlap = getAgentStateHistoryOverlap(
-                observedStateHistory,
-                entry.stateHistory
-              )
-              // Why: sawWorkingAfterStart stays monotonic — a recreated entry
-              // (transport loss, PTY exit, cap eviction) arrives with an empty
-              // stateHistory, so clearing it here would strand reuseSession runs
-              // with nothing left to re-derive the working edge from.
-              for (const historicalState of entry.stateHistory.slice(historyOverlap)) {
-                if (historicalState.startedAt < startedAfter) {
-                  continue
-                }
-                if (historicalState.state === 'working') {
-                  sawWorkingAfterStart = true
-                }
-                if (
-                  historicalState.state === 'done' &&
-                  (!options?.requireWorkingAfterStart || sawWorkingAfterStart)
-                ) {
-                  // Why: this `done` already rolled out of the live entry, so its output
-                  // survives only in the entry-level completed slot.
-                  latestAssistantMessage =
-                    entry.lastCompletedAssistantMessage?.trim() || latestAssistantMessage
-                  handleAgentDone()
-                  return
-                }
-              }
-              observedStateHistory = [...entry.stateHistory]
-              if (entry.state === 'working') {
-                sawWorkingAfterStart = true
-              }
-              if (
-                entry.state === 'done' &&
-                // Why: a session-boundary done is the agent CONNECTING (Claude SessionStart
-                // fires at launch, before the argv prompt submits) — completing here would
-                // close the tab and record an empty run result.
-                entry.sessionBoundary !== true &&
-                (!options?.requireWorkingAfterStart || sawWorkingAfterStart)
-              ) {
-                latestAssistantMessage =
-                  entry.lastAssistantMessage?.trim() || latestAssistantMessage
-                handleAgentDone()
-              }
-            }
-            // Why: Codex/Claude completion normally arrives through the global
-            // hook IPC listener, not the hidden PTY OSC fallback.
-            unsubscribeAgentStatus = useAppStore.subscribe(checkCurrentStatus)
-            checkCurrentStatus()
-          }
-          const dispatchStartedAt = Date.now()
-          if (automation.reuseSession) {
-            const reusableSession = findReusableAutomationSession({
-              automationId: automation.id,
-              agentId: automation.agentId,
-              worktreeId: worktree.id,
-              currentRunId: run.id,
-              // Why: the dispatch loop only ever executes for the desktop authority,
-              // so its history read addresses the local runtime explicitly.
-              runs: await listAutomationRunsForTarget({ kind: 'local' }, automation.id),
-              state: useAppStore.getState()
-            })
-            if (reusableSession) {
-              const releaseTab = acquireReuseDispatchTab(reusableSession.tabId)
-              if (releaseTab) {
-                releaseReuseDispatchTab = releaseTab
-                try {
-                  const submitted = await submitPromptToAgentPty({
-                    tabId: reusableSession.tabId,
-                    ptyId: reusableSession.ptyId,
-                    content: automation.prompt
-                  })
-                  if (!submitted) {
-                    cleanupRunObservers()
-                  } else {
-                    let reuseSawWorking = false
-                    const handleReusableAgentStatus = (payload: { state: string }): void => {
-                      if (payload.state === 'working') {
-                        reuseSawWorking = true
-                        return
-                      }
-                      if (payload.state === 'done' && reuseSawWorking) {
-                        handleAgentDone()
-                      }
-                    }
-                    const reuseCompletionStartedAt = Date.now()
-                    unsubscribeSessionObserver = await observeExistingAutomationSession({
-                      ptyId: reusableSession.ptyId,
-                      paneKey: reusableSession.paneKey,
-                      runId: run.id,
-                      onData: (chunk) => {
-                        outputSnapshotBuffer.append(chunk)
-                      },
-                      onAgentStatus: (payload) => {
-                        latestAssistantMessage =
-                          payload.lastAssistantMessage?.trim() || latestAssistantMessage
-                        handleReusableAgentStatus(payload)
-                      },
-                      onExit: (code) => {
-                        if (completionMarked) {
-                          return
-                        }
-                        if (!dispatchMarked) {
-                          pendingExitCode = code
-                          return
-                        }
-                        settleLateResult(markExitResult(code))
-                      }
-                    })
-                    observeAgentStatus(reusableSession.paneKey, reuseCompletionStartedAt, {
-                      requireWorkingAfterStart: true
-                    })
-                    await markDispatchResult({
-                      runId: run.id,
-                      status: 'dispatched',
-                      workspaceId: worktree.id,
-                      workspaceDisplayName: worktree.displayName,
-                      terminalSessionId: reusableSession.tabId,
-                      terminalPaneKey: reusableSession.paneKey,
-                      terminalPtyId: reusableSession.ptyId,
-                      precheckResult,
-                      error: null
-                    })
-                    dispatchMarked = true
-                    if (pendingDone) {
-                      await markCompletionResult()
-                    } else if (pendingExitCode !== null) {
-                      await markExitResult(pendingExitCode)
-                    }
-                    return
-                  }
-                } catch (error) {
-                  cleanupRunObservers()
-                  throw error
-                }
-              }
-            }
-          }
-          const result = await launchAgentBackgroundSession({
-            agent: automation.agentId,
-            worktreeId: worktree.id,
-            prompt: automation.prompt,
-            launchSource: 'unknown',
-            title: run.title,
-            onData: (chunk) => {
-              outputSnapshotBuffer.append(chunk)
-            },
-            onAgentStatus: (payload) => {
-              latestAssistantMessage =
-                payload.lastAssistantMessage?.trim() || latestAssistantMessage
-              // Why: session-boundary done = launch connect, not run completion (see observeAgentStatus).
-              if (payload.state !== 'done' || payload.sessionBoundary === true) {
-                return
-              }
-              handleAgentDone()
-            },
-            onExit: (_ptyId, code) => {
-              if (completionMarked) {
-                return
-              }
-              if (!dispatchMarked) {
-                pendingExitCode = code
-                return
-              }
-              settleLateResult(markExitResult(code))
-            }
-          })
-          if (!result) {
-            throw new Error('Unable to build an agent launch plan.')
-          }
-          terminalOwnership = result.terminalOwnership
-          if (automation.reuseSession) {
-            // Why: the first fresh launch is the seed for later reuse and must
-            // survive completion under the same policy as an already-reused tab.
-            releaseTerminalOwnership()
-          }
-          const launchedTabId = result.tabId
-          observeAgentStatus(result.paneKey, dispatchStartedAt)
-          try {
-            await markDispatchResult({
-              runId: run.id,
-              status: 'dispatched',
-              workspaceId: worktree.id,
-              workspaceDisplayName: worktree.displayName,
-              terminalSessionId: launchedTabId,
-              terminalPaneKey: result.paneKey,
-              terminalPtyId: result.ptyId,
-              precheckResult,
-              error: null
-            })
-            dispatchMarked = true
-            if (pendingDone) {
-              await markCompletionResult()
-            } else if (pendingExitCode !== null) {
-              await markExitResult(pendingExitCode)
-            }
-          } catch (error) {
-            cleanupRunObservers()
-            throw error
-          }
-          const currentState = useAppStore.getState()
-          // Why: Run Now and scheduled dispatches should create workspaces/tabs in
-          // the background; only an explicit row click should navigate there.
-          if (
-            focusBeforeDispatch.activeWorktreeId !== worktree.id &&
-            currentState.activeWorktreeId === worktree.id
-          ) {
-            currentState.setActiveView(focusBeforeDispatch.activeView)
-            currentState.setActiveWorktree(focusBeforeDispatch.activeWorktreeId)
-            if (focusBeforeDispatch.activeTabId) {
-              currentState.setActiveTab(focusBeforeDispatch.activeTabId)
-            }
-            currentState.setActiveTabType(focusBeforeDispatch.activeTabType)
-          }
-        } catch (error) {
-          releaseTerminalOwnership()
-          await markDispatchResult({
-            runId: run.id,
-            status: 'dispatch_failed',
-            workspaceId: dispatchWorkspaceId,
-            workspaceDisplayName: dispatchWorkspaceDisplayName,
-            precheckResult,
-            error: error instanceof Error ? error.message : String(error)
-          })
-        }
-      }
-    )
+    const unsubscribe = window.api.automations.onDispatchRequested(handleAutomationDispatchRequest)
     void window.api.automations.rendererReady()
     return unsubscribe
   }, [])

From b51dfc21c60a5a9f536fa0048eebd2096809a366 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sat, 29 Aug 2026 20:13:44 -0700
Subject: [PATCH 30/31] Split settings navigation metadata (#17157)

* Split speech session lifecycle

* Split terminal output scheduler pipeline

* Split mobile browser pane modules

* Prune resolved max-lines suppressions

* Split pane tree equalization logic

* Extract mobile troubleshoot screen styles

* Split external automation manager

* Split main window service attachments

* Split hosted review creation checks

* Split automation dispatch event handling

* Split settings navigation metadata

* Fix F3-speech for #17123

* Fix F1-cycle for #17131

* Fix F4-navtest for #17157
---
 config/max-lines-baseline.txt                 |   1 -
 .../settings-navigation-build-options.ts      |  14 +
 ...settings-navigation-capability-sections.ts | 215 ++++++
 .../settings-navigation-interface-sections.ts |  90 +++
 .../settings-navigation-remote-sections.ts    | 205 ++++++
 .../settings-navigation-workflow-sections.ts  | 176 +++++
 .../useSettingsNavigationMetadata.test.ts     |  16 +-
 .../hooks/useSettingsNavigationMetadata.ts    | 671 +-----------------
 8 files changed, 748 insertions(+), 640 deletions(-)
 create mode 100644 src/renderer/src/hooks/settings-navigation-build-options.ts
 create mode 100644 src/renderer/src/hooks/settings-navigation-capability-sections.ts
 create mode 100644 src/renderer/src/hooks/settings-navigation-interface-sections.ts
 create mode 100644 src/renderer/src/hooks/settings-navigation-remote-sections.ts
 create mode 100644 src/renderer/src/hooks/settings-navigation-workflow-sections.ts

diff --git a/config/max-lines-baseline.txt b/config/max-lines-baseline.txt
index 59162f7e001..fc38baab7d1 100644
--- a/config/max-lines-baseline.txt
+++ b/config/max-lines-baseline.txt
@@ -56,7 +56,6 @@ inline src/renderer/src/components/status-bar/WorkspaceSpaceManagerPanel.tsx
 inline src/renderer/src/components/terminal-pane/TerminalPane.tsx
 inline src/renderer/src/components/terminal-pane/remote-runtime-pty-transport.ts
 inline src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts
-inline src/renderer/src/hooks/useSettingsNavigationMetadata.ts
 inline src/renderer/src/runtime/remote-runtime-terminal-multiplexer.ts
 inline src/renderer/src/runtime/runtime-file-client.ts
 inline src/renderer/src/runtime/sync-runtime-graph.ts
diff --git a/src/renderer/src/hooks/settings-navigation-build-options.ts b/src/renderer/src/hooks/settings-navigation-build-options.ts
new file mode 100644
index 00000000000..db2a4cedead
--- /dev/null
+++ b/src/renderer/src/hooks/settings-navigation-build-options.ts
@@ -0,0 +1,14 @@
+import type { Repo } from '../../../shared/repo-types'
+
+export type SettingsNavigationBuildOptions = {
+  isMac: boolean
+  isWindows: boolean
+  isLocalWindowsHost: boolean
+  isWindowsTerminalHost: boolean
+  isWebClient: boolean
+  managedBrowserCreationEnabled: boolean
+  mobileEmulatorCreationEnabled: boolean
+  isDev: boolean
+  isLinearConnected: boolean
+  repos: readonly Repo[]
+}
diff --git a/src/renderer/src/hooks/settings-navigation-capability-sections.ts b/src/renderer/src/hooks/settings-navigation-capability-sections.ts
new file mode 100644
index 00000000000..b207682844f
--- /dev/null
+++ b/src/renderer/src/hooks/settings-navigation-capability-sections.ts
@@ -0,0 +1,215 @@
+import { LinearIcon } from '@/components/icons/LinearIcon'
+import { getAccountsPaneSearchEntries } from '@/components/settings/accounts-search'
+import { getAgentsPaneSearchEntries } from '@/components/settings/agents-search'
+import { getComputerUsePaneSearchEntries } from '@/components/settings/computer-use-search'
+import { getGeneralPaneSearchEntries } from '@/components/settings/general-search'
+import { getIntegrationsPaneSearchEntries } from '@/components/settings/integrations-search'
+import { getLinearAgentSkillPaneSearchEntries } from '@/components/settings/linear-agent-skill-search'
+import { getMobileSettingsPaneSearchEntries } from '@/components/settings/mobile-settings-search'
+import { getOrcaAccountSettingsSearchEntries } from '@/components/settings/orca-account-settings-search'
+import { OrcaLogoSettingsIcon } from '@/components/settings/orca-logo-settings-icon'
+import { getOrchestrationPaneSearchEntries } from '@/components/settings/orchestration-search'
+import { getVoicePaneSearchEntries } from '@/components/settings/voice-pane-search'
+import { translate } from '@/i18n/i18n'
+import type { SettingsNavSection } from '@/lib/settings-navigation-types'
+import {
+  Blocks,
+  Bot,
+  CircleUserRound,
+  Mic,
+  MousePointerClick,
+  Network,
+  SlidersHorizontal,
+  Smartphone,
+  UserCog
+} from 'lucide-react'
+import type { SettingsNavigationBuildOptions } from './settings-navigation-build-options'
+
+export function buildCapabilitySettingsSections({
+  isLocalWindowsHost,
+  isWebClient,
+  isLinearConnected
+}: SettingsNavigationBuildOptions): SettingsNavSection[] {
+  const showDesktopOnlySettings = !isWebClient
+  return [
+    {
+      id: 'agents',
+      title: translate('auto.hooks.useSettingsNavigationMetadata.b49abbd2f7', 'Agents'),
+      description: translate(
+        'auto.hooks.useSettingsNavigationMetadata.4121f7a0a2',
+        'Manage AI agents, set a default, and customize commands.'
+      ),
+      icon: Bot,
+      searchEntries: getAgentsPaneSearchEntries({
+        includeAgentAwake: !isWebClient,
+        includeAgentRuntime: isLocalWindowsHost
+      }),
+      group: 'capabilities'
+    },
+    {
+      id: 'accounts',
+      title: translate(
+        'auto.hooks.useSettingsNavigationMetadata.f70ac54d38',
+        'AI Provider Accounts'
+      ),
+      description: translate(
+        'auto.hooks.useSettingsNavigationMetadata.b1c2f8b0ac',
+        'Optional account switching and usage setup for Claude, Codex, Gemini, OpenCode Go, MiniMax, and Grok.'
+      ),
+      icon: UserCog,
+      searchEntries: getAccountsPaneSearchEntries(),
+      group: 'capabilities',
+      badge: translate('auto.hooks.useSettingsNavigationMetadata.7c79d3b7bf', 'Optional')
+    },
+    {
+      id: 'orchestration',
+      title: translate('auto.hooks.useSettingsNavigationMetadata.58a868e8e4', 'Orchestration'),
+      description: translate(
+        'auto.hooks.useSettingsNavigationMetadata.cd50cec5d7',
+        'Coordinate multiple coding agents through Orca.'
+      ),
+      icon: Network,
+      searchEntries: getOrchestrationPaneSearchEntries({
+        includeNestedWorkerDepth: !isWebClient
+      }),
+      group: 'capabilities'
+    },
+    // Why: only surfaced once Linear is connected — a capability that needs a
+    // linked provider before the agent skill has anything to act on.
+    ...(isLinearConnected
+      ? [
+          {
+            id: 'linear',
+            title: translate('auto.hooks.useSettingsNavigationMetadata.linearTitle', 'Linear'),
+            description: translate(
+              'auto.hooks.useSettingsNavigationMetadata.linearDescription',
+              'How Linear works in Orca, setup checklist, agent skill, and example prompts.'
+            ),
+            icon: LinearIcon,
+            searchEntries: getLinearAgentSkillPaneSearchEntries(),
+            group: 'capabilities'
+          }
+        ]
+      : []),
+    ...(showDesktopOnlySettings
+      ? [
+          {
+            id: 'computer-use',
+            title: translate('auto.hooks.useSettingsNavigationMetadata.b35e92364b', 'Computer Use'),
+            description: translate(
+              'auto.hooks.useSettingsNavigationMetadata.0059bd17f3',
+              'Enable agents to control any app on your computer.'
+            ),
+            icon: MousePointerClick,
+            searchEntries: getComputerUsePaneSearchEntries(),
+            group: 'capabilities'
+          },
+          {
+            id: 'voice',
+            title: translate('auto.hooks.useSettingsNavigationMetadata.6a50cdcd7c', 'Voice'),
+            description: translate(
+              'auto.hooks.useSettingsNavigationMetadata.8ac3de82f5',
+              'Local speech-to-text dictation with on-device models.'
+            ),
+            icon: Mic,
+            searchEntries: getVoicePaneSearchEntries(),
+            group: 'capabilities'
+          }
+        ]
+      : [])
+  ]
+}
+
+export function buildSetupSettingsSections({
+  isLocalWindowsHost,
+  isWebClient
+}: SettingsNavigationBuildOptions): SettingsNavSection[] {
+  const showDesktopOnlySettings = !isWebClient
+  return [
+    ...(showDesktopOnlySettings
+      ? [
+          {
+            id: 'orca-account',
+            title: translate('auto.components.settings.orcaAccount.title', 'Orca Account'),
+            description: translate(
+              'auto.components.settings.orcaAccount.description',
+              'Share work instantly and reach your desktop from Orca Mobile wherever you are.'
+            ),
+            icon: CircleUserRound,
+            searchEntries: getOrcaAccountSettingsSearchEntries(),
+            group: 'setup'
+          }
+        ]
+      : []),
+    {
+      id: 'setup-guide',
+      title: translate(
+        'auto.hooks.useSettingsNavigationMetadata.ded9e9032f',
+        'Onboarding checklist'
+      ),
+      description: translate(
+        'auto.hooks.useSettingsNavigationMetadata.5f32ac08f3',
+        'Finish the onboarding checklist for core Orca workflows.'
+      ),
+      icon: OrcaLogoSettingsIcon,
+      searchEntries: [
+        {
+          title: translate(
+            'auto.hooks.useSettingsNavigationMetadata.ded9e9032f',
+            'Onboarding checklist'
+          ),
+          description: translate(
+            'auto.hooks.useSettingsNavigationMetadata.17005c73d4',
+            'Open the onboarding checklist for setup and milestone steps.'
+          ),
+          keywords: [
+            translate('auto.hooks.useSettingsNavigationMetadata.ea0b1bc7b8', 'setup guide'),
+            translate(
+              'auto.hooks.useSettingsNavigationMetadata.0505d0df29',
+              'get started with Orca'
+            ),
+            translate('auto.hooks.useSettingsNavigationMetadata.724c440e72', 'getting started')
+          ]
+        }
+      ],
+      group: 'setup'
+    },
+    {
+      id: 'general',
+      title: translate('auto.hooks.useSettingsNavigationMetadata.13241992bd', 'General'),
+      description: translate(
+        'auto.hooks.useSettingsNavigationMetadata.2cd4ea75da',
+        'Workspace defaults, app setup, and maintenance.'
+      ),
+      icon: SlidersHorizontal,
+      searchEntries: getGeneralPaneSearchEntries({ includeProjectRuntime: isLocalWindowsHost }),
+      group: 'setup'
+    },
+    {
+      id: 'integrations',
+      title: translate('auto.hooks.useSettingsNavigationMetadata.2b043783ef', 'Integrations'),
+      description: translate(
+        'auto.hooks.useSettingsNavigationMetadata.33a5e1d597',
+        'Connect GitHub, GitLab, Linear, and source-hosting services.'
+      ),
+      icon: Blocks,
+      searchEntries: getIntegrationsPaneSearchEntries(),
+      group: 'setup'
+    },
+    ...(showDesktopOnlySettings
+      ? [
+          {
+            id: 'mobile',
+            title: translate('auto.hooks.useSettingsNavigationMetadata.1cd25673df', 'Mobile'),
+            description: translate(
+              'auto.hooks.useSettingsNavigationMetadata.95a1886d94',
+              'Control terminals and agents from your phone.'
+            ),
+            icon: Smartphone,
+            searchEntries: getMobileSettingsPaneSearchEntries(),
+            group: 'setup'
+          }
+        ]
+      : [])
+  ]
+}
diff --git a/src/renderer/src/hooks/settings-navigation-interface-sections.ts b/src/renderer/src/hooks/settings-navigation-interface-sections.ts
new file mode 100644
index 00000000000..0208dd1f526
--- /dev/null
+++ b/src/renderer/src/hooks/settings-navigation-interface-sections.ts
@@ -0,0 +1,90 @@
+import { getAppearancePaneSearchEntries } from '@/components/settings/appearance-search'
+import { getInputPaneSearchEntries } from '@/components/settings/input-search'
+import { getNotificationsPaneSearchEntries } from '@/components/settings/notifications-search'
+import { getShortcutsPaneSearchEntries } from '@/components/settings/shortcuts-search'
+import { getStatsPaneSearchEntries } from '@/components/stats/stats-search'
+import { translate } from '@/i18n/i18n'
+import type { SettingsNavSection } from '@/lib/settings-navigation-types'
+import { BarChart3, Bell, Keyboard, Palette, TextCursorInput } from 'lucide-react'
+import type { SettingsNavigationBuildOptions } from './settings-navigation-build-options'
+
+export function buildInterfaceSettingsSections({
+  isMac,
+  isWindows,
+  isWebClient,
+  managedBrowserCreationEnabled,
+  mobileEmulatorCreationEnabled
+}: SettingsNavigationBuildOptions): SettingsNavSection[] {
+  const showDesktopOnlySettings = !isWebClient
+  return [
+    {
+      id: 'appearance',
+      title: translate('auto.hooks.useSettingsNavigationMetadata.93d88d20bf', 'Appearance'),
+      description: translate(
+        'auto.hooks.useSettingsNavigationMetadata.b11a5a48a2',
+        'Theme, zoom, app and terminal appearance, sidebars, and status bar.'
+      ),
+      icon: Palette,
+      searchEntries: getAppearancePaneSearchEntries({
+        showWarpImport: showDesktopOnlySettings,
+        showSystemTray: showDesktopOnlySettings && isWindows,
+        showMenuBarIcon: showDesktopOnlySettings && isMac
+      }),
+      group: 'interface'
+    },
+    {
+      id: 'input',
+      title: translate('auto.hooks.useSettingsNavigationMetadata.0c6ee88a5f', 'Input & Editing'),
+      description: translate(
+        'auto.hooks.useSettingsNavigationMetadata.1f452cbd4c',
+        'Selection and editing behavior.'
+      ),
+      icon: TextCursorInput,
+      searchEntries: getInputPaneSearchEntries(),
+      group: 'interface'
+    },
+    ...(showDesktopOnlySettings
+      ? [
+          {
+            id: 'notifications',
+            title: translate(
+              'auto.hooks.useSettingsNavigationMetadata.2eece16ad1',
+              'Notifications'
+            ),
+            description: translate(
+              'auto.hooks.useSettingsNavigationMetadata.7682607591',
+              'Native desktop notifications for agent and terminal events.'
+            ),
+            icon: Bell,
+            searchEntries: getNotificationsPaneSearchEntries(),
+            group: 'interface'
+          }
+        ]
+      : []),
+    {
+      id: 'shortcuts',
+      title: translate('auto.hooks.useSettingsNavigationMetadata.94295ebfb3', 'Shortcuts'),
+      description: translate(
+        'auto.hooks.useSettingsNavigationMetadata.dcd0d9b74f',
+        'Keyboard shortcuts for common actions.'
+      ),
+      icon: Keyboard,
+      searchEntries: getShortcutsPaneSearchEntries({
+        includeManagedBrowser: managedBrowserCreationEnabled,
+        includeMobileEmulator: mobileEmulatorCreationEnabled
+      }),
+      group: 'interface'
+    },
+    {
+      id: 'stats',
+      title: translate('auto.hooks.useSettingsNavigationMetadata.d72a58b5b9', 'Stats & Usage'),
+      description: translate(
+        'auto.hooks.useSettingsNavigationMetadata.b351014180',
+        'Orca stats plus Claude, Codex, OpenCode token analytics and Grok subscription usage.'
+      ),
+      icon: BarChart3,
+      searchEntries: getStatsPaneSearchEntries(),
+      group: 'interface'
+    }
+  ]
+}
diff --git a/src/renderer/src/hooks/settings-navigation-remote-sections.ts b/src/renderer/src/hooks/settings-navigation-remote-sections.ts
new file mode 100644
index 00000000000..5c53c3e0df9
--- /dev/null
+++ b/src/renderer/src/hooks/settings-navigation-remote-sections.ts
@@ -0,0 +1,205 @@
+import { getAdvancedPaneSearchEntries } from '@/components/settings/advanced-search'
+import { getDeveloperPermissionsPaneSearchEntries } from '@/components/settings/developer-permissions-search'
+import { getExperimentalPaneSearchEntries } from '@/components/settings/experimental-search'
+import { getPluginsPaneSearchEntries } from '@/components/settings/plugins-search'
+import { getPrivacyPaneSearchEntries } from '@/components/settings/privacy-search'
+import { getRepositoryPaneSearchEntries } from '@/components/settings/repository-search'
+import { buildSettingsProjectList } from '@/components/settings/settings-project-list'
+import { getSshPaneSearchEntries } from '@/components/settings/ssh-search'
+import { translate } from '@/i18n/i18n'
+import type { SettingsNavSection } from '@/lib/settings-navigation-types'
+import { getRepoKindLabel } from '../../../shared/repo-kind'
+import type { Repo } from '../../../shared/repo-types'
+import {
+  Blocks,
+  Bug,
+  Cable,
+  FlaskConical,
+  Lock,
+  Server,
+  ShieldCheck,
+  SlidersHorizontal,
+  Wrench
+} from 'lucide-react'
+import type { SettingsNavigationBuildOptions } from './settings-navigation-build-options'
+
+export function buildRemoteSettingsSections(
+  { isMac, isWindowsTerminalHost, isWebClient, isDev, repos }: SettingsNavigationBuildOptions,
+  runtimeEnvironmentsSearchEntry: SettingsNavSection['searchEntries'][number],
+  reposById: ReadonlyMap<string, Repo>
+): SettingsNavSection[] {
+  const showDesktopOnlySettings = !isWebClient
+  return [
+    ...(showDesktopOnlySettings
+      ? [
+          {
+            id: 'ssh',
+            title: translate('auto.hooks.useSettingsNavigationMetadata.94a5afe910', 'SSH Hosts'),
+            description: translate(
+              'auto.hooks.useSettingsNavigationMetadata.31e57d1c70',
+              'Use existing machines over SSH for files, terminals, Git, and workspaces.'
+            ),
+            icon: Cable,
+            searchEntries: getSshPaneSearchEntries(),
+            group: 'remote'
+          }
+        ]
+      : []),
+    {
+      id: 'servers',
+      title: translate(
+        'auto.hooks.useSettingsNavigationMetadata.de0c2907a1',
+        'Remote Orca Servers'
+      ),
+      description: isWebClient
+        ? 'Connect this browser to a saved Orca server.'
+        : 'Pair remote Orca runtimes for persistent sessions, richer remote state, and web or mobile handoff.',
+      icon: Server,
+      searchEntries: [runtimeEnvironmentsSearchEntry],
+      group: 'remote',
+      badge: translate('auto.hooks.useSettingsNavigationMetadata.40d80bad8a', 'Beta')
+    },
+    ...(showDesktopOnlySettings && isMac
+      ? [
+          {
+            id: 'developer-permissions',
+            title: translate(
+              'auto.hooks.useSettingsNavigationMetadata.d91ae31fbd',
+              'macOS Permissions'
+            ),
+            description: translate(
+              'auto.hooks.useSettingsNavigationMetadata.65ec7d1968',
+              'macOS privacy access for terminal-launched developer tools.'
+            ),
+            icon: ShieldCheck,
+            searchEntries: getDeveloperPermissionsPaneSearchEntries(),
+            group: 'security'
+          }
+        ]
+      : []),
+    {
+      id: 'privacy',
+      title: translate(
+        'auto.hooks.useSettingsNavigationMetadata.3618579df6',
+        'Privacy & Telemetry'
+      ),
+      description: translate(
+        'auto.hooks.useSettingsNavigationMetadata.8400cfe1c1',
+        'Anonymous usage data and telemetry controls.'
+      ),
+      icon: Lock,
+      searchEntries: getPrivacyPaneSearchEntries(),
+      group: 'security'
+    },
+    ...(showDesktopOnlySettings
+      ? [
+          {
+            id: 'advanced',
+            title: translate('auto.hooks.useSettingsNavigationMetadata.580a04cd81', 'Advanced'),
+            description: translate(
+              'auto.hooks.useSettingsNavigationMetadata.e338c507c1',
+              'Low-level compatibility settings for troubleshooting.'
+            ),
+            icon: Wrench,
+            searchEntries: getAdvancedPaneSearchEntries(),
+            group: 'advanced'
+          }
+        ]
+      : []),
+    // Why: dev tooling must not be reachable from packaged/web builds even if
+    // this pure metadata builder is called manually with isDev=true.
+    ...(showDesktopOnlySettings && import.meta.env.DEV && isDev
+      ? [
+          {
+            id: 'dev',
+            title: translate('auto.hooks.useSettingsNavigationMetadata.dev', 'Dev Tools'),
+            description: translate(
+              'auto.hooks.useSettingsNavigationMetadata.devDescription',
+              'Dev-only tools for exercising UI states.'
+            ),
+            // Why: distinct from the sibling Advanced section's Wrench so the two
+            // entries in the same 'advanced' group stay visually distinguishable.
+            icon: Bug,
+            searchEntries: getDevToolsPaneSearchEntries(),
+            group: 'advanced',
+            badge: translate('auto.hooks.useSettingsNavigationMetadata.devBadge', 'Dev')
+          }
+        ]
+      : []),
+    {
+      id: 'experimental',
+      title: translate('auto.hooks.useSettingsNavigationMetadata.225071c560', 'Experimental'),
+      description: translate(
+        'auto.hooks.useSettingsNavigationMetadata.4a728cd56b',
+        'New features that are still taking shape. Give them a try.'
+      ),
+      icon: FlaskConical,
+      searchEntries: getExperimentalPaneSearchEntries(),
+      group: 'experimental'
+    },
+    ...(showDesktopOnlySettings
+      ? [
+          {
+            id: 'plugins',
+            title: translate('auto.hooks.useSettingsNavigationMetadata.pluginsTitle', 'Plugins'),
+            description: translate(
+              'auto.hooks.useSettingsNavigationMetadata.pluginsDescription',
+              'Install and manage experimental Orca plugins.'
+            ),
+            icon: Blocks,
+            searchEntries: getPluginsPaneSearchEntries(),
+            group: 'experimental'
+          }
+        ]
+      : []),
+    // Why: one nav row per project, not per repo row — a project set up on
+    // multiple hosts (local + a Remote Orca Server, or two clones) collapses to
+    // a single entry. Derived from repos alone so this list matches the panes.
+    ...buildSettingsProjectList(repos).map(({ project, representativeRepoId, setups }) => {
+      const representativeRepo = reposById.get(representativeRepoId) ?? repos[0]
+      const hostSummary =
+        setups.length > 1
+          ? translate(
+              'auto.hooks.useSettingsNavigationMetadata.projectHostsSummary',
+              '{{value0}} hosts',
+              { value0: setups.length }
+            )
+          : (setups[0]?.path ?? representativeRepo.path)
+      return {
+        id: `repo-${representativeRepoId}`,
+        title: project.displayName,
+        description: `${getRepoKindLabel(project)} • ${hostSummary}`,
+        icon: SlidersHorizontal,
+        searchEntries: getRepositoryPaneSearchEntries(representativeRepo, {
+          windowsRuntimeSupported: isWindowsTerminalHost
+        }),
+        group: 'repositories'
+      }
+    })
+  ]
+}
+
+function getDevToolsPaneSearchEntries(): SettingsNavSection['searchEntries'] {
+  return [
+    {
+      title: translate(
+        'auto.hooks.useSettingsNavigationMetadata.devSearchNotificationPlayground',
+        'Notification playground'
+      ),
+      description: translate(
+        'auto.hooks.useSettingsNavigationMetadata.devSearchNotificationPlaygroundDescription',
+        'Trigger representative toast and notification UI states.'
+      ),
+      keywords: [
+        translate('auto.hooks.useSettingsNavigationMetadata.devSearchKeywordDev', 'dev'),
+        translate('auto.hooks.useSettingsNavigationMetadata.devSearchKeywordToast', 'toast'),
+        translate('auto.hooks.useSettingsNavigationMetadata.devSearchKeywordSonner', 'sonner'),
+        translate('auto.hooks.useSettingsNavigationMetadata.devSearchKeywordError', 'error'),
+        translate(
+          'auto.hooks.useSettingsNavigationMetadata.devSearchKeywordNotification',
+          'notification'
+        )
+      ]
+    }
+  ]
+}
diff --git a/src/renderer/src/hooks/settings-navigation-workflow-sections.ts b/src/renderer/src/hooks/settings-navigation-workflow-sections.ts
new file mode 100644
index 00000000000..9d3fbf9ad28
--- /dev/null
+++ b/src/renderer/src/hooks/settings-navigation-workflow-sections.ts
@@ -0,0 +1,176 @@
+import { getArtifactsSettingsSearchEntries } from '@/components/settings/artifacts-settings-search'
+import { getAutomationsSettingsSearchEntries } from '@/components/settings/automations-settings-search'
+import { getBrowserPaneCombinedSearchEntries } from '@/components/settings/browser-pane-search'
+import { getCommitMessageAiPaneSearchEntries } from '@/components/settings/commit-message-ai-search'
+import { getFloatingWorkspaceSearchEntries } from '@/components/settings/floating-workspace-search'
+import { getGitProviderApiBudgetSearchEntries } from '@/components/settings/git-provider-api-budget-search'
+import { getGitPaneSearchEntries } from '@/components/settings/git-search'
+import { getMobileEmulatorSearchEntries } from '@/components/settings/mobile-emulator-search'
+import { getQuickCommandsPaneSearchEntries } from '@/components/settings/quick-commands-search'
+import { getShareSkillsSettingsSearchEntries } from '@/components/settings/share-skills-settings-search'
+import { getTasksPaneSearchEntries } from '@/components/settings/tasks-search'
+import { translate } from '@/i18n/i18n'
+import type { SettingsNavSection } from '@/lib/settings-navigation-types'
+import {
+  BookOpen,
+  CalendarClock,
+  Files,
+  GitBranch,
+  Globe,
+  ListChecks,
+  PanelsTopLeft,
+  Play,
+  SquareTerminal,
+  TabletSmartphone
+} from 'lucide-react'
+import type { SettingsNavigationBuildOptions } from './settings-navigation-build-options'
+
+export function buildWorkflowSettingsSections(
+  { isWebClient }: SettingsNavigationBuildOptions,
+  terminalPaneSearchEntries: SettingsNavSection['searchEntries']
+): SettingsNavSection[] {
+  const showDesktopOnlySettings = !isWebClient
+  return [
+    {
+      id: 'automations',
+      title: translate('auto.hooks.useSettingsNavigationMetadata.automationsTitle', 'Automations'),
+      description: translate(
+        'auto.hooks.useSettingsNavigationMetadata.automationsDescription',
+        'Schedule agent work and choose whether Automations appears in the sidebar.'
+      ),
+      icon: CalendarClock,
+      searchEntries: getAutomationsSettingsSearchEntries(),
+      group: 'workflows'
+    },
+    {
+      id: 'artifacts',
+      title: translate('auto.hooks.useSettingsNavigationMetadata.artifactsTitle', 'Artifacts'),
+      description: translate(
+        'auto.hooks.useSettingsNavigationMetadata.artifactsDescription',
+        'Share HTML and Markdown files with your team and manage their public links.'
+      ),
+      icon: Files,
+      searchEntries: getArtifactsSettingsSearchEntries(),
+      group: 'workflows',
+      badge: translate('auto.hooks.useSettingsNavigationMetadata.40d80bad8a', 'Beta')
+    },
+    {
+      id: 'share-skills',
+      title: translate('auto.hooks.useSettingsNavigationMetadata.shareSkillsTitle', 'Share Skills'),
+      description: translate(
+        'auto.hooks.useSettingsNavigationMetadata.shareSkillsDescription',
+        'Share your skills with an unlisted link. Anyone who has it can install them.'
+      ),
+      // Why: the sidebar entry and the page header both use BookOpen for
+      // skills, so the settings row that opens them matches.
+      icon: BookOpen,
+      searchEntries: getShareSkillsSettingsSearchEntries(),
+      group: 'workflows',
+      badge: translate('auto.hooks.useSettingsNavigationMetadata.40d80bad8a', 'Beta')
+    },
+    {
+      id: 'git',
+      title: translate(
+        'auto.hooks.useSettingsNavigationMetadata.09607cb0fe',
+        'Git & Source Control'
+      ),
+      description: translate(
+        'auto.hooks.useSettingsNavigationMetadata.ab4b21b58e',
+        'Branch naming, base refs, and Git AI Author.'
+      ),
+      icon: GitBranch,
+      // Why: Git AI Author is rendered inside Git, so shared
+      // metadata must search both surfaces wherever Git appears.
+      searchEntries: [
+        ...getGitPaneSearchEntries(),
+        ...getCommitMessageAiPaneSearchEntries(),
+        ...getGitProviderApiBudgetSearchEntries()
+      ],
+      group: 'workflows'
+    },
+    {
+      id: 'tasks',
+      title: translate('auto.hooks.useSettingsNavigationMetadata.85f4fd7710', 'Task Sources'),
+      description: translate(
+        'auto.hooks.useSettingsNavigationMetadata.tasksDescription',
+        'Connect providers, install the Linear skill, and choose what appears in Tasks.'
+      ),
+      icon: ListChecks,
+      searchEntries: getTasksPaneSearchEntries(),
+      group: 'workflows'
+    },
+    {
+      id: 'terminal',
+      title: translate('auto.hooks.useSettingsNavigationMetadata.a9fb10afca', 'Terminal'),
+      description: translate(
+        'auto.hooks.useSettingsNavigationMetadata.c33bfd664c',
+        'Shells, renderer, sessions, and terminal behavior.'
+      ),
+      icon: SquareTerminal,
+      searchEntries: terminalPaneSearchEntries,
+      group: 'workflows'
+    },
+    {
+      id: 'quick-commands',
+      title: translate('auto.hooks.useSettingsNavigationMetadata.3fc3db144f', 'Quick Commands'),
+      description: translate(
+        'auto.hooks.useSettingsNavigationMetadata.42ae40842f',
+        'Saved terminal commands, scoped globally or per project.'
+      ),
+      icon: Play,
+      searchEntries: getQuickCommandsPaneSearchEntries(),
+      group: 'workflows'
+    },
+    ...(showDesktopOnlySettings
+      ? [
+          {
+            id: 'browser',
+            title: translate('auto.hooks.useSettingsNavigationMetadata.8c197f74a1', 'Browser'),
+            description: translate(
+              'auto.hooks.useSettingsNavigationMetadata.e815fd01bd',
+              'Home page, link routing, and session cookies.'
+            ),
+            icon: Globe,
+            searchEntries: getBrowserPaneCombinedSearchEntries(),
+            group: 'workflows'
+          }
+        ]
+      : []),
+    ...(showDesktopOnlySettings
+      ? [
+          {
+            id: 'mobile-emulator',
+            title: translate(
+              'auto.hooks.useSettingsNavigationMetadata.1e761cff2b',
+              'Mobile Emulator'
+            ),
+            description: translate(
+              'auto.hooks.useSettingsNavigationMetadata.3d65d3f1b9',
+              'Configure mobile emulator support for Orca and coding agents.'
+            ),
+            icon: TabletSmartphone,
+            searchEntries: getMobileEmulatorSearchEntries(),
+            group: 'workflows'
+          }
+        ]
+      : []),
+    {
+      id: 'floating-workspace',
+      title: translate('auto.hooks.useSettingsNavigationMetadata.65b19f5bde', 'Floating Workspace'),
+      description: showDesktopOnlySettings
+        ? translate(
+            'auto.hooks.useSettingsNavigationMetadata.2d0659f6f0',
+            'Global terminal, browser, and markdown tabs.'
+          )
+        : translate(
+            'auto.hooks.useSettingsNavigationMetadata.floatingWorkspaceWebDescription',
+            'Global terminal and markdown tabs.'
+          ),
+      icon: PanelsTopLeft,
+      searchEntries: getFloatingWorkspaceSearchEntries({
+        includeBrowser: showDesktopOnlySettings
+      }),
+      group: 'workflows'
+    }
+  ]
+}
diff --git a/src/renderer/src/hooks/useSettingsNavigationMetadata.test.ts b/src/renderer/src/hooks/useSettingsNavigationMetadata.test.ts
index 7cc5c009f9d..bf12b2c0c28 100644
--- a/src/renderer/src/hooks/useSettingsNavigationMetadata.test.ts
+++ b/src/renderer/src/hooks/useSettingsNavigationMetadata.test.ts
@@ -1,4 +1,4 @@
-import { readFileSync } from 'node:fs'
+import { readdirSync, readFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 import { describe, expect, it } from 'vitest'
 import { buildSettingsNavigationMetadata } from './useSettingsNavigationMetadata'
@@ -408,9 +408,17 @@ describe('settings navigation metadata', () => {
 
   it('does not import Settings page or pane UI modules from the metadata hook', () => {
     const testDir = import.meta.dirname
-    const hookSource = readFileSync(resolve(testDir, 'useSettingsNavigationMetadata.ts'), 'utf8')
-    const importLines = hookSource
-      .split('\n')
+    // Why: the section tables live in sibling settings-navigation-* modules, so reading only the
+    // hook would scan a file that no longer holds the imports this guard exists to police.
+    const sourceFiles = [
+      'useSettingsNavigationMetadata.ts',
+      ...readdirSync(testDir).filter(
+        (name) => name.startsWith('settings-navigation-') && name.endsWith('.ts')
+      )
+    ]
+    expect(sourceFiles.length).toBeGreaterThan(1)
+    const importLines = sourceFiles
+      .flatMap((name) => readFileSync(resolve(testDir, name), 'utf8').split('\n'))
       .filter((line) => line.trim().startsWith('import '))
       .join('\n')
 
diff --git a/src/renderer/src/hooks/useSettingsNavigationMetadata.ts b/src/renderer/src/hooks/useSettingsNavigationMetadata.ts
index 9983ba38f0a..4941233c2af 100644
--- a/src/renderer/src/hooks/useSettingsNavigationMetadata.ts
+++ b/src/renderer/src/hooks/useSettingsNavigationMetadata.ts
@@ -1,127 +1,38 @@
-/* oxlint-disable max-lines */
 import { useMemo } from 'react'
 import { useTranslation } from 'react-i18next'
 import { useShallow } from 'zustand/react/shallow'
 // Why: this registry mirrors the Settings sidebar in one neutral module so
 // Cmd+J and Settings visibility cannot drift. Keep it free of Settings pane UI
 // imports; the boundary is enforced by a focused architecture test.
-import {
-  BarChart3,
-  Bell,
-  Blocks,
-  Bot,
-  Bug,
-  Cable,
-  CalendarClock,
-  CircleUserRound,
-  FlaskConical,
-  GitBranch,
-  Globe,
-  Keyboard,
-  ListChecks,
-  Lock,
-  Mic,
-  MousePointerClick,
-  Network,
-  Palette,
-  PanelsTopLeft,
-  Play,
-  Server,
-  ShieldCheck,
-  SlidersHorizontal,
-  Smartphone,
-  TabletSmartphone,
-  SquareTerminal,
-  TextCursorInput,
-  Files,
-  BookOpen,
-  UserCog,
-  Wrench
-} from 'lucide-react'
-import { OrcaLogoSettingsIcon } from '@/components/settings/orca-logo-settings-icon'
-import { LinearIcon } from '@/components/icons/LinearIcon'
-import type { Repo } from '../../../shared/repo-types'
-import { getRepoKindLabel } from '../../../shared/repo-kind'
-import { useAppStore } from '@/store'
-import { isMacUserAgent, isWindowsUserAgent } from '@/components/terminal-pane/pane-helpers'
-import type { SettingsNavSection } from '@/lib/settings-navigation-types'
-import { getGeneralPaneSearchEntries } from '@/components/settings/general-search'
-import { getAgentsPaneSearchEntries } from '@/components/settings/agents-search'
-import { getAccountsPaneSearchEntries } from '@/components/settings/accounts-search'
-import { getIntegrationsPaneSearchEntries } from '@/components/settings/integrations-search'
-import { getGitPaneSearchEntries } from '@/components/settings/git-search'
-import { getGitProviderApiBudgetSearchEntries } from '@/components/settings/git-provider-api-budget-search'
-import { getCommitMessageAiPaneSearchEntries } from '@/components/settings/commit-message-ai-search'
-import { getTasksPaneSearchEntries } from '@/components/settings/tasks-search'
-import { getFloatingWorkspaceSearchEntries } from '@/components/settings/floating-workspace-search'
-import { getAppearancePaneSearchEntries } from '@/components/settings/appearance-search'
-import { getInputPaneSearchEntries } from '@/components/settings/input-search'
-import { getTerminalPaneSearchEntries } from '@/components/settings/terminal-search'
-import { getQuickCommandsPaneSearchEntries } from '@/components/settings/quick-commands-search'
-import { getBrowserPaneCombinedSearchEntries } from '@/components/settings/browser-pane-search'
-import { getNotificationsPaneSearchEntries } from '@/components/settings/notifications-search'
-import { getOrchestrationPaneSearchEntries } from '@/components/settings/orchestration-search'
-import { getArtifactsSettingsSearchEntries } from '@/components/settings/artifacts-settings-search'
-import { getShareSkillsSettingsSearchEntries } from '@/components/settings/share-skills-settings-search'
-import { getAutomationsSettingsSearchEntries } from '@/components/settings/automations-settings-search'
-import { getOrcaAccountSettingsSearchEntries } from '@/components/settings/orca-account-settings-search'
-import { getLinearAgentSkillPaneSearchEntries } from '@/components/settings/linear-agent-skill-search'
 import {
   getRuntimeEnvironmentsSearchEntry,
   getWebRuntimeEnvironmentsSearchEntry
 } from '@/components/settings/runtime-environments-search'
-import { getSshPaneSearchEntries } from '@/components/settings/ssh-search'
-import { getMobileSettingsPaneSearchEntries } from '@/components/settings/mobile-settings-search'
-import { getMobileEmulatorSearchEntries } from '@/components/settings/mobile-emulator-search'
-import { getComputerUsePaneSearchEntries } from '@/components/settings/computer-use-search'
-import { getVoicePaneSearchEntries } from '@/components/settings/voice-pane-search'
-import { getDeveloperPermissionsPaneSearchEntries } from '@/components/settings/developer-permissions-search'
-import { getPrivacyPaneSearchEntries } from '@/components/settings/privacy-search'
-import { getAdvancedPaneSearchEntries } from '@/components/settings/advanced-search'
-import { getShortcutsPaneSearchEntries } from '@/components/settings/shortcuts-search'
-import { getStatsPaneSearchEntries } from '@/components/stats/stats-search'
-import { getExperimentalPaneSearchEntries } from '@/components/settings/experimental-search'
-import { getPluginsPaneSearchEntries } from '@/components/settings/plugins-search'
-import { getRepositoryPaneSearchEntries } from '@/components/settings/repository-search'
-import { buildSettingsProjectList } from '@/components/settings/settings-project-list'
+import { getTerminalPaneSearchEntries } from '@/components/settings/terminal-search'
+import { isMacUserAgent, isWindowsUserAgent } from '@/components/terminal-pane/pane-helpers'
+import { useLinearProviderConnected } from '@/hooks/useLinearProviderConnected'
+import { getClientCreationActionPolicy } from '@/lib/client-creation-action-policy'
+import type { SettingsNavSection } from '@/lib/settings-navigation-types'
 import { isWebClientLocation } from '@/lib/web-client-location'
 import {
   isWindowsTerminalCapabilityHost,
   useWindowsTerminalCapabilities
 } from '@/lib/windows-terminal-capabilities'
-import { useWindowsTerminalCapabilityOwnerKey } from './useWindowsTerminalCapabilityOwnerKey'
 import { getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
-import { useLinearProviderConnected } from '@/hooks/useLinearProviderConnected'
-import { translate } from '@/i18n/i18n'
-import { getClientCreationActionPolicy } from '@/lib/client-creation-action-policy'
+import { useAppStore } from '@/store'
+import type { Repo } from '../../../shared/repo-types'
+import {
+  buildCapabilitySettingsSections,
+  buildSetupSettingsSections
+} from './settings-navigation-capability-sections'
+import type { SettingsNavigationBuildOptions } from './settings-navigation-build-options'
+import { buildInterfaceSettingsSections } from './settings-navigation-interface-sections'
+import { buildRemoteSettingsSections } from './settings-navigation-remote-sections'
+import { buildWorkflowSettingsSections } from './settings-navigation-workflow-sections'
+import { useWindowsTerminalCapabilityOwnerKey } from './useWindowsTerminalCapabilityOwnerKey'
 
 export { isWebClientLocation } from '@/lib/web-client-location'
 
-function getDevToolsPaneSearchEntries(): SettingsNavSection['searchEntries'] {
-  return [
-    {
-      title: translate(
-        'auto.hooks.useSettingsNavigationMetadata.devSearchNotificationPlayground',
-        'Notification playground'
-      ),
-      description: translate(
-        'auto.hooks.useSettingsNavigationMetadata.devSearchNotificationPlaygroundDescription',
-        'Trigger representative toast and notification UI states.'
-      ),
-      keywords: [
-        translate('auto.hooks.useSettingsNavigationMetadata.devSearchKeywordDev', 'dev'),
-        translate('auto.hooks.useSettingsNavigationMetadata.devSearchKeywordToast', 'toast'),
-        translate('auto.hooks.useSettingsNavigationMetadata.devSearchKeywordSonner', 'sonner'),
-        translate('auto.hooks.useSettingsNavigationMetadata.devSearchKeywordError', 'error'),
-        translate(
-          'auto.hooks.useSettingsNavigationMetadata.devSearchKeywordNotification',
-          'notification'
-        )
-      ]
-    }
-  ]
-}
-
 export function buildSettingsNavigationMetadata({
   isMac,
   isWindows,
@@ -145,7 +56,6 @@ export function buildSettingsNavigationMetadata({
   isLinearConnected?: boolean
   repos: readonly Repo[]
 }): SettingsNavSection[] {
-  const showDesktopOnlySettings = !isWebClient
   const terminalPaneSearchEntries = getTerminalPaneSearchEntries({
     isWindows,
     isWindowsTerminalHost,
@@ -160,537 +70,28 @@ export function buildSettingsNavigationMetadata({
       reposById.set(repo.id, repo)
     }
   }
+  const options: SettingsNavigationBuildOptions = {
+    isMac,
+    isWindows,
+    isLocalWindowsHost,
+    isWindowsTerminalHost,
+    isWebClient,
+    managedBrowserCreationEnabled,
+    mobileEmulatorCreationEnabled,
+    isDev,
+    isLinearConnected,
+    repos
+  }
 
+  // Why: this array's order must mirror SETTINGS_NAV_GROUPS so the Settings
+  // sidebar and the Cmd+J palette both read top-to-bottom in the same grouped
+  // order — keep each new entry beside its group's siblings.
   return [
-    // Why: this array's order must mirror SETTINGS_NAV_GROUPS so the Settings
-    // sidebar and the Cmd+J palette both read top-to-bottom in the same grouped
-    // order — keep each new entry beside its group's siblings.
-    {
-      id: 'agents',
-      title: translate('auto.hooks.useSettingsNavigationMetadata.b49abbd2f7', 'Agents'),
-      description: translate(
-        'auto.hooks.useSettingsNavigationMetadata.4121f7a0a2',
-        'Manage AI agents, set a default, and customize commands.'
-      ),
-      icon: Bot,
-      searchEntries: getAgentsPaneSearchEntries({
-        includeAgentAwake: !isWebClient,
-        includeAgentRuntime: isLocalWindowsHost
-      }),
-      group: 'capabilities'
-    },
-    {
-      id: 'accounts',
-      title: translate(
-        'auto.hooks.useSettingsNavigationMetadata.f70ac54d38',
-        'AI Provider Accounts'
-      ),
-      description: translate(
-        'auto.hooks.useSettingsNavigationMetadata.b1c2f8b0ac',
-        'Optional account switching and usage setup for Claude, Codex, Gemini, OpenCode Go, MiniMax, and Grok.'
-      ),
-      icon: UserCog,
-      searchEntries: getAccountsPaneSearchEntries(),
-      group: 'capabilities',
-      badge: translate('auto.hooks.useSettingsNavigationMetadata.7c79d3b7bf', 'Optional')
-    },
-    {
-      id: 'orchestration',
-      title: translate('auto.hooks.useSettingsNavigationMetadata.58a868e8e4', 'Orchestration'),
-      description: translate(
-        'auto.hooks.useSettingsNavigationMetadata.cd50cec5d7',
-        'Coordinate multiple coding agents through Orca.'
-      ),
-      icon: Network,
-      searchEntries: getOrchestrationPaneSearchEntries({
-        includeNestedWorkerDepth: !isWebClient
-      }),
-      group: 'capabilities'
-    },
-    // Why: only surfaced once Linear is connected — a capability that needs a
-    // linked provider before the agent skill has anything to act on.
-    ...(isLinearConnected
-      ? [
-          {
-            id: 'linear',
-            title: translate('auto.hooks.useSettingsNavigationMetadata.linearTitle', 'Linear'),
-            description: translate(
-              'auto.hooks.useSettingsNavigationMetadata.linearDescription',
-              'How Linear works in Orca, setup checklist, agent skill, and example prompts.'
-            ),
-            icon: LinearIcon,
-            searchEntries: getLinearAgentSkillPaneSearchEntries(),
-            group: 'capabilities'
-          }
-        ]
-      : []),
-    ...(showDesktopOnlySettings
-      ? [
-          {
-            id: 'computer-use',
-            title: translate('auto.hooks.useSettingsNavigationMetadata.b35e92364b', 'Computer Use'),
-            description: translate(
-              'auto.hooks.useSettingsNavigationMetadata.0059bd17f3',
-              'Enable agents to control any app on your computer.'
-            ),
-            icon: MousePointerClick,
-            searchEntries: getComputerUsePaneSearchEntries(),
-            group: 'capabilities'
-          },
-          {
-            id: 'voice',
-            title: translate('auto.hooks.useSettingsNavigationMetadata.6a50cdcd7c', 'Voice'),
-            description: translate(
-              'auto.hooks.useSettingsNavigationMetadata.8ac3de82f5',
-              'Local speech-to-text dictation with on-device models.'
-            ),
-            icon: Mic,
-            searchEntries: getVoicePaneSearchEntries(),
-            group: 'capabilities'
-          }
-        ]
-      : []),
-    ...(showDesktopOnlySettings
-      ? [
-          {
-            id: 'orca-account',
-            title: translate('auto.components.settings.orcaAccount.title', 'Orca Account'),
-            description: translate(
-              'auto.components.settings.orcaAccount.description',
-              'Share work instantly and reach your desktop from Orca Mobile wherever you are.'
-            ),
-            icon: CircleUserRound,
-            searchEntries: getOrcaAccountSettingsSearchEntries(),
-            group: 'setup'
-          }
-        ]
-      : []),
-    {
-      id: 'setup-guide',
-      title: translate(
-        'auto.hooks.useSettingsNavigationMetadata.ded9e9032f',
-        'Onboarding checklist'
-      ),
-      description: translate(
-        'auto.hooks.useSettingsNavigationMetadata.5f32ac08f3',
-        'Finish the onboarding checklist for core Orca workflows.'
-      ),
-      icon: OrcaLogoSettingsIcon,
-      searchEntries: [
-        {
-          title: translate(
-            'auto.hooks.useSettingsNavigationMetadata.ded9e9032f',
-            'Onboarding checklist'
-          ),
-          description: translate(
-            'auto.hooks.useSettingsNavigationMetadata.17005c73d4',
-            'Open the onboarding checklist for setup and milestone steps.'
-          ),
-          keywords: [
-            translate('auto.hooks.useSettingsNavigationMetadata.ea0b1bc7b8', 'setup guide'),
-            translate(
-              'auto.hooks.useSettingsNavigationMetadata.0505d0df29',
-              'get started with Orca'
-            ),
-            translate('auto.hooks.useSettingsNavigationMetadata.724c440e72', 'getting started')
-          ]
-        }
-      ],
-      group: 'setup'
-    },
-    {
-      id: 'general',
-      title: translate('auto.hooks.useSettingsNavigationMetadata.13241992bd', 'General'),
-      description: translate(
-        'auto.hooks.useSettingsNavigationMetadata.2cd4ea75da',
-        'Workspace defaults, app setup, and maintenance.'
-      ),
-      icon: SlidersHorizontal,
-      searchEntries: getGeneralPaneSearchEntries({ includeProjectRuntime: isLocalWindowsHost }),
-      group: 'setup'
-    },
-    {
-      id: 'integrations',
-      title: translate('auto.hooks.useSettingsNavigationMetadata.2b043783ef', 'Integrations'),
-      description: translate(
-        'auto.hooks.useSettingsNavigationMetadata.33a5e1d597',
-        'Connect GitHub, GitLab, Linear, and source-hosting services.'
-      ),
-      icon: Blocks,
-      searchEntries: getIntegrationsPaneSearchEntries(),
-      group: 'setup'
-    },
-    ...(showDesktopOnlySettings
-      ? [
-          {
-            id: 'mobile',
-            title: translate('auto.hooks.useSettingsNavigationMetadata.1cd25673df', 'Mobile'),
-            description: translate(
-              'auto.hooks.useSettingsNavigationMetadata.95a1886d94',
-              'Control terminals and agents from your phone.'
-            ),
-            icon: Smartphone,
-            searchEntries: getMobileSettingsPaneSearchEntries(),
-            group: 'setup'
-          }
-        ]
-      : []),
-    {
-      id: 'automations',
-      title: translate('auto.hooks.useSettingsNavigationMetadata.automationsTitle', 'Automations'),
-      description: translate(
-        'auto.hooks.useSettingsNavigationMetadata.automationsDescription',
-        'Schedule agent work and choose whether Automations appears in the sidebar.'
-      ),
-      icon: CalendarClock,
-      searchEntries: getAutomationsSettingsSearchEntries(),
-      group: 'workflows'
-    },
-    {
-      id: 'artifacts',
-      title: translate('auto.hooks.useSettingsNavigationMetadata.artifactsTitle', 'Artifacts'),
-      description: translate(
-        'auto.hooks.useSettingsNavigationMetadata.artifactsDescription',
-        'Share HTML and Markdown files with your team and manage their public links.'
-      ),
-      icon: Files,
-      searchEntries: getArtifactsSettingsSearchEntries(),
-      group: 'workflows',
-      badge: translate('auto.hooks.useSettingsNavigationMetadata.40d80bad8a', 'Beta')
-    },
-    {
-      id: 'share-skills',
-      title: translate('auto.hooks.useSettingsNavigationMetadata.shareSkillsTitle', 'Share Skills'),
-      description: translate(
-        'auto.hooks.useSettingsNavigationMetadata.shareSkillsDescription',
-        'Share your skills with an unlisted link. Anyone who has it can install them.'
-      ),
-      // Why: the sidebar entry and the page header both use BookOpen for
-      // skills, so the settings row that opens them matches.
-      icon: BookOpen,
-      searchEntries: getShareSkillsSettingsSearchEntries(),
-      group: 'workflows',
-      badge: translate('auto.hooks.useSettingsNavigationMetadata.40d80bad8a', 'Beta')
-    },
-    {
-      id: 'git',
-      title: translate(
-        'auto.hooks.useSettingsNavigationMetadata.09607cb0fe',
-        'Git & Source Control'
-      ),
-      description: translate(
-        'auto.hooks.useSettingsNavigationMetadata.ab4b21b58e',
-        'Branch naming, base refs, and Git AI Author.'
-      ),
-      icon: GitBranch,
-      // Why: Git AI Author is rendered inside Git, so shared
-      // metadata must search both surfaces wherever Git appears.
-      searchEntries: [
-        ...getGitPaneSearchEntries(),
-        ...getCommitMessageAiPaneSearchEntries(),
-        ...getGitProviderApiBudgetSearchEntries()
-      ],
-      group: 'workflows'
-    },
-    {
-      id: 'tasks',
-      title: translate('auto.hooks.useSettingsNavigationMetadata.85f4fd7710', 'Task Sources'),
-      description: translate(
-        'auto.hooks.useSettingsNavigationMetadata.tasksDescription',
-        'Connect providers, install the Linear skill, and choose what appears in Tasks.'
-      ),
-      icon: ListChecks,
-      searchEntries: getTasksPaneSearchEntries(),
-      group: 'workflows'
-    },
-    {
-      id: 'terminal',
-      title: translate('auto.hooks.useSettingsNavigationMetadata.a9fb10afca', 'Terminal'),
-      description: translate(
-        'auto.hooks.useSettingsNavigationMetadata.c33bfd664c',
-        'Shells, renderer, sessions, and terminal behavior.'
-      ),
-      icon: SquareTerminal,
-      searchEntries: terminalPaneSearchEntries,
-      group: 'workflows'
-    },
-    {
-      id: 'quick-commands',
-      title: translate('auto.hooks.useSettingsNavigationMetadata.3fc3db144f', 'Quick Commands'),
-      description: translate(
-        'auto.hooks.useSettingsNavigationMetadata.42ae40842f',
-        'Saved terminal commands, scoped globally or per project.'
-      ),
-      icon: Play,
-      searchEntries: getQuickCommandsPaneSearchEntries(),
-      group: 'workflows'
-    },
-    ...(showDesktopOnlySettings
-      ? [
-          {
-            id: 'browser',
-            title: translate('auto.hooks.useSettingsNavigationMetadata.8c197f74a1', 'Browser'),
-            description: translate(
-              'auto.hooks.useSettingsNavigationMetadata.e815fd01bd',
-              'Home page, link routing, and session cookies.'
-            ),
-            icon: Globe,
-            searchEntries: getBrowserPaneCombinedSearchEntries(),
-            group: 'workflows'
-          }
-        ]
-      : []),
-    ...(showDesktopOnlySettings
-      ? [
-          {
-            id: 'mobile-emulator',
-            title: translate(
-              'auto.hooks.useSettingsNavigationMetadata.1e761cff2b',
-              'Mobile Emulator'
-            ),
-            description: translate(
-              'auto.hooks.useSettingsNavigationMetadata.3d65d3f1b9',
-              'Configure mobile emulator support for Orca and coding agents.'
-            ),
-            icon: TabletSmartphone,
-            searchEntries: getMobileEmulatorSearchEntries(),
-            group: 'workflows'
-          }
-        ]
-      : []),
-    {
-      id: 'floating-workspace',
-      title: translate('auto.hooks.useSettingsNavigationMetadata.65b19f5bde', 'Floating Workspace'),
-      description: showDesktopOnlySettings
-        ? translate(
-            'auto.hooks.useSettingsNavigationMetadata.2d0659f6f0',
-            'Global terminal, browser, and markdown tabs.'
-          )
-        : translate(
-            'auto.hooks.useSettingsNavigationMetadata.floatingWorkspaceWebDescription',
-            'Global terminal and markdown tabs.'
-          ),
-      icon: PanelsTopLeft,
-      searchEntries: getFloatingWorkspaceSearchEntries({
-        includeBrowser: showDesktopOnlySettings
-      }),
-      group: 'workflows'
-    },
-    {
-      id: 'appearance',
-      title: translate('auto.hooks.useSettingsNavigationMetadata.93d88d20bf', 'Appearance'),
-      description: translate(
-        'auto.hooks.useSettingsNavigationMetadata.b11a5a48a2',
-        'Theme, zoom, app and terminal appearance, sidebars, and status bar.'
-      ),
-      icon: Palette,
-      searchEntries: getAppearancePaneSearchEntries({
-        showWarpImport: showDesktopOnlySettings,
-        showSystemTray: showDesktopOnlySettings && isWindows,
-        showMenuBarIcon: showDesktopOnlySettings && isMac
-      }),
-      group: 'interface'
-    },
-    {
-      id: 'input',
-      title: translate('auto.hooks.useSettingsNavigationMetadata.0c6ee88a5f', 'Input & Editing'),
-      description: translate(
-        'auto.hooks.useSettingsNavigationMetadata.1f452cbd4c',
-        'Selection and editing behavior.'
-      ),
-      icon: TextCursorInput,
-      searchEntries: getInputPaneSearchEntries(),
-      group: 'interface'
-    },
-    ...(showDesktopOnlySettings
-      ? [
-          {
-            id: 'notifications',
-            title: translate(
-              'auto.hooks.useSettingsNavigationMetadata.2eece16ad1',
-              'Notifications'
-            ),
-            description: translate(
-              'auto.hooks.useSettingsNavigationMetadata.7682607591',
-              'Native desktop notifications for agent and terminal events.'
-            ),
-            icon: Bell,
-            searchEntries: getNotificationsPaneSearchEntries(),
-            group: 'interface'
-          }
-        ]
-      : []),
-    {
-      id: 'shortcuts',
-      title: translate('auto.hooks.useSettingsNavigationMetadata.94295ebfb3', 'Shortcuts'),
-      description: translate(
-        'auto.hooks.useSettingsNavigationMetadata.dcd0d9b74f',
-        'Keyboard shortcuts for common actions.'
-      ),
-      icon: Keyboard,
-      searchEntries: getShortcutsPaneSearchEntries({
-        includeManagedBrowser: managedBrowserCreationEnabled,
-        includeMobileEmulator: mobileEmulatorCreationEnabled
-      }),
-      group: 'interface'
-    },
-    {
-      id: 'stats',
-      title: translate('auto.hooks.useSettingsNavigationMetadata.d72a58b5b9', 'Stats & Usage'),
-      description: translate(
-        'auto.hooks.useSettingsNavigationMetadata.b351014180',
-        'Orca stats plus Claude, Codex, OpenCode token analytics and Grok subscription usage.'
-      ),
-      icon: BarChart3,
-      searchEntries: getStatsPaneSearchEntries(),
-      group: 'interface'
-    },
-    ...(showDesktopOnlySettings
-      ? [
-          {
-            id: 'ssh',
-            title: translate('auto.hooks.useSettingsNavigationMetadata.94a5afe910', 'SSH Hosts'),
-            description: translate(
-              'auto.hooks.useSettingsNavigationMetadata.31e57d1c70',
-              'Use existing machines over SSH for files, terminals, Git, and workspaces.'
-            ),
-            icon: Cable,
-            searchEntries: getSshPaneSearchEntries(),
-            group: 'remote'
-          }
-        ]
-      : []),
-    {
-      id: 'servers',
-      title: translate(
-        'auto.hooks.useSettingsNavigationMetadata.de0c2907a1',
-        'Remote Orca Servers'
-      ),
-      description: isWebClient
-        ? 'Connect this browser to a saved Orca server.'
-        : 'Pair remote Orca runtimes for persistent sessions, richer remote state, and web or mobile handoff.',
-      icon: Server,
-      searchEntries: [runtimeEnvironmentsSearchEntry],
-      group: 'remote',
-      badge: translate('auto.hooks.useSettingsNavigationMetadata.40d80bad8a', 'Beta')
-    },
-    ...(showDesktopOnlySettings && isMac
-      ? [
-          {
-            id: 'developer-permissions',
-            title: translate(
-              'auto.hooks.useSettingsNavigationMetadata.d91ae31fbd',
-              'macOS Permissions'
-            ),
-            description: translate(
-              'auto.hooks.useSettingsNavigationMetadata.65ec7d1968',
-              'macOS privacy access for terminal-launched developer tools.'
-            ),
-            icon: ShieldCheck,
-            searchEntries: getDeveloperPermissionsPaneSearchEntries(),
-            group: 'security'
-          }
-        ]
-      : []),
-    {
-      id: 'privacy',
-      title: translate(
-        'auto.hooks.useSettingsNavigationMetadata.3618579df6',
-        'Privacy & Telemetry'
-      ),
-      description: translate(
-        'auto.hooks.useSettingsNavigationMetadata.8400cfe1c1',
-        'Anonymous usage data and telemetry controls.'
-      ),
-      icon: Lock,
-      searchEntries: getPrivacyPaneSearchEntries(),
-      group: 'security'
-    },
-    ...(showDesktopOnlySettings
-      ? [
-          {
-            id: 'advanced',
-            title: translate('auto.hooks.useSettingsNavigationMetadata.580a04cd81', 'Advanced'),
-            description: translate(
-              'auto.hooks.useSettingsNavigationMetadata.e338c507c1',
-              'Low-level compatibility settings for troubleshooting.'
-            ),
-            icon: Wrench,
-            searchEntries: getAdvancedPaneSearchEntries(),
-            group: 'advanced'
-          }
-        ]
-      : []),
-    // Why: dev tooling must not be reachable from packaged/web builds even if
-    // this pure metadata builder is called manually with isDev=true.
-    ...(showDesktopOnlySettings && import.meta.env.DEV && isDev
-      ? [
-          {
-            id: 'dev',
-            title: translate('auto.hooks.useSettingsNavigationMetadata.dev', 'Dev Tools'),
-            description: translate(
-              'auto.hooks.useSettingsNavigationMetadata.devDescription',
-              'Dev-only tools for exercising UI states.'
-            ),
-            // Why: distinct from the sibling Advanced section's Wrench so the two
-            // entries in the same 'advanced' group stay visually distinguishable.
-            icon: Bug,
-            searchEntries: getDevToolsPaneSearchEntries(),
-            group: 'advanced',
-            badge: translate('auto.hooks.useSettingsNavigationMetadata.devBadge', 'Dev')
-          }
-        ]
-      : []),
-    {
-      id: 'experimental',
-      title: translate('auto.hooks.useSettingsNavigationMetadata.225071c560', 'Experimental'),
-      description: translate(
-        'auto.hooks.useSettingsNavigationMetadata.4a728cd56b',
-        'New features that are still taking shape. Give them a try.'
-      ),
-      icon: FlaskConical,
-      searchEntries: getExperimentalPaneSearchEntries(),
-      group: 'experimental'
-    },
-    ...(showDesktopOnlySettings
-      ? [
-          {
-            id: 'plugins',
-            title: translate('auto.hooks.useSettingsNavigationMetadata.pluginsTitle', 'Plugins'),
-            description: translate(
-              'auto.hooks.useSettingsNavigationMetadata.pluginsDescription',
-              'Install and manage experimental Orca plugins.'
-            ),
-            icon: Blocks,
-            searchEntries: getPluginsPaneSearchEntries(),
-            group: 'experimental'
-          }
-        ]
-      : []),
-    // Why: one nav row per project, not per repo row — a project set up on
-    // multiple hosts (local + a Remote Orca Server, or two clones) collapses to
-    // a single entry. Derived from repos alone so this list matches the panes.
-    ...buildSettingsProjectList(repos).map(({ project, representativeRepoId, setups }) => {
-      const representativeRepo = reposById.get(representativeRepoId) ?? repos[0]
-      const hostSummary =
-        setups.length > 1
-          ? translate(
-              'auto.hooks.useSettingsNavigationMetadata.projectHostsSummary',
-              '{{value0}} hosts',
-              { value0: setups.length }
-            )
-          : (setups[0]?.path ?? representativeRepo.path)
-      return {
-        id: `repo-${representativeRepoId}`,
-        title: project.displayName,
-        description: `${getRepoKindLabel(project)} • ${hostSummary}`,
-        icon: SlidersHorizontal,
-        searchEntries: getRepositoryPaneSearchEntries(representativeRepo, {
-          windowsRuntimeSupported: isWindowsTerminalHost
-        }),
-        group: 'repositories'
-      }
-    })
+    ...buildCapabilitySettingsSections(options),
+    ...buildSetupSettingsSections(options),
+    ...buildWorkflowSettingsSections(options, terminalPaneSearchEntries),
+    ...buildInterfaceSettingsSections(options),
+    ...buildRemoteSettingsSections(options, runtimeEnvironmentsSearchEntry, reposById)
   ]
 }
 

From 953114c1c142414e3b7616a79b096f71d690b6ea Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Sat, 29 Aug 2026 20:14:12 -0700
Subject: [PATCH 31/31] Split daemon initialization lifecycle (#17161)

* Split speech session lifecycle

* Split terminal output scheduler pipeline

* Split mobile browser pane modules

* Prune resolved max-lines suppressions

* Split pane tree equalization logic

* Extract mobile troubleshoot screen styles

* Split external automation manager

* Split main window service attachments

* Split hosted review creation checks

* Split automation dispatch event handling

* Split settings navigation metadata

* Split daemon initialization lifecycle

* Fix F3-speech for #17123

* Fix F1-cycle for #17131

* Fix F4-navtest for #17157

* Fix F2-allowlist for #17161
---
 config/max-lines-baseline.txt                 |    1 -
 src/main/daemon/daemon-endpoint-adoption.ts   |  171 ++
 src/main/daemon/daemon-init.ts                | 1421 +----------------
 src/main/daemon/daemon-launched-child.ts      |  295 ++++
 src/main/daemon/daemon-legacy-adapters.ts     |   66 +
 .../daemon/daemon-out-of-process-launcher.ts  |  209 +++
 src/main/daemon/daemon-protocol-cleanup.ts    |   98 ++
 src/main/daemon/daemon-provider-init.ts       |  186 +++
 src/main/daemon/daemon-provider-restart.ts    |  161 ++
 src/main/daemon/daemon-provider-routing.ts    |   29 +
 src/main/daemon/daemon-provider-state.ts      |  137 ++
 .../daemon/daemon-replacement-preflight.ts    |  228 +++
 src/main/daemon/daemon-restart-state.ts       |   22 +
 .../child-process-import-allowlist.txt        |    5 +-
 14 files changed, 1626 insertions(+), 1403 deletions(-)
 create mode 100644 src/main/daemon/daemon-endpoint-adoption.ts
 create mode 100644 src/main/daemon/daemon-launched-child.ts
 create mode 100644 src/main/daemon/daemon-legacy-adapters.ts
 create mode 100644 src/main/daemon/daemon-out-of-process-launcher.ts
 create mode 100644 src/main/daemon/daemon-protocol-cleanup.ts
 create mode 100644 src/main/daemon/daemon-provider-init.ts
 create mode 100644 src/main/daemon/daemon-provider-restart.ts
 create mode 100644 src/main/daemon/daemon-provider-routing.ts
 create mode 100644 src/main/daemon/daemon-provider-state.ts
 create mode 100644 src/main/daemon/daemon-replacement-preflight.ts
 create mode 100644 src/main/daemon/daemon-restart-state.ts

diff --git a/config/max-lines-baseline.txt b/config/max-lines-baseline.txt
index fc38baab7d1..bac0d69e3c8 100644
--- a/config/max-lines-baseline.txt
+++ b/config/max-lines-baseline.txt
@@ -11,7 +11,6 @@ inline src/main/claude-accounts/runtime-auth-service.ts
 inline src/main/codex-accounts/runtime-home-service.ts
 inline src/main/codex-accounts/service.ts
 inline src/main/codex/hook-service.ts
-inline src/main/daemon/daemon-init.ts
 inline src/main/git/worktree.ts
 inline src/main/github/project-view.ts
 inline src/main/index.ts
diff --git a/src/main/daemon/daemon-endpoint-adoption.ts b/src/main/daemon/daemon-endpoint-adoption.ts
new file mode 100644
index 00000000000..4973fffeaee
--- /dev/null
+++ b/src/main/daemon/daemon-endpoint-adoption.ts
@@ -0,0 +1,171 @@
+import { readFileSync } from 'node:fs'
+import { DaemonClient } from './client'
+import type { DaemonEndpointIdentity } from './daemon-hello-protocol'
+import type { DaemonPtyAdapter } from './daemon-pty-adapter'
+import { readDaemonProcessIncarnation } from './daemon-ready-identity'
+import type { DaemonPidFile, DaemonProcessHandle, DaemonSpawner } from './daemon-spawner'
+import { replaceDaemonPidFile } from './daemon-spawner'
+
+export class DaemonEndpointOwnershipError extends Error {}
+
+/**
+ * The one method the ownership checks need from a connected client.
+ *
+ * Why: naming the capability instead of casting DaemonClient to Partial keeps a rename from
+ * silently turning the fence into a no-op — the compiler now rejects a client without it.
+ */
+type DaemonEndpointIdentityReader = {
+  getDaemonIdentity?: () => DaemonEndpointIdentity | null
+}
+
+function readDaemonEndpointIdentity(
+  client: DaemonEndpointIdentityReader
+): DaemonEndpointIdentity | null {
+  return client.getDaemonIdentity?.() ?? null
+}
+
+export async function holdDaemonAdoptionLease(
+  handle: DaemonProcessHandle,
+  socketPath: string,
+  tokenPath: string,
+  connectedClient?: DaemonClient,
+  expectedIdentity?: DaemonEndpointIdentity,
+  pidPath?: string
+): Promise<DaemonProcessHandle> {
+  const client = connectedClient ?? new DaemonClient({ socketPath, tokenPath })
+  try {
+    await client.ensureConnected()
+    if (expectedIdentity) {
+      const actualIdentity = readDaemonEndpointIdentity(client)
+      if (
+        !actualIdentity ||
+        actualIdentity.pid !== expectedIdentity.pid ||
+        actualIdentity.startedAtMs !== expectedIdentity.startedAtMs ||
+        actualIdentity.launchNonce !== expectedIdentity.launchNonce
+      ) {
+        throw new DaemonEndpointOwnershipError('Daemon endpoint ownership changed during startup')
+      }
+    }
+    await reconcileDaemonPidOwnership(client, pidPath)
+  } catch (error) {
+    client.disconnect()
+    throw error
+  }
+  handle.releaseAdoptionLease = () => client.disconnect()
+  return handle
+}
+
+export async function reconcileDaemonPidOwnership(
+  client: DaemonEndpointIdentityReader,
+  pidPath?: string
+): Promise<void> {
+  const endpointIdentity = readDaemonEndpointIdentity(client)
+  if (!pidPath || !endpointIdentity || pidRecordMatchesEndpoint(pidPath, endpointIdentity)) {
+    return
+  }
+  // Why: the mismatched record's metadata describes a different daemon and must not be copied
+  // onto this one. Re-derive it from the authenticated owner instead, so the repaired record
+  // keeps the fields freshness, host pinning and pid-recycle detection depend on.
+  const { pid, startedAtMs, launchNonce } = endpointIdentity
+  const ownerMetadata = await readDaemonOwnerMetadata(endpointIdentity)
+  if (!replaceDaemonPidFile(pidPath, { pid, startedAtMs, launchNonce, ...ownerMetadata })) {
+    // Why: fail open. A record that disagrees with the endpoint is a diagnosable nuisance;
+    // abandoning a healthy adoptable daemon over a failed file write costs the user every
+    // persistent terminal on the machine.
+    console.warn(
+      '[daemon] Could not repair daemon PID ownership; adopting the authenticated endpoint anyway'
+    )
+    return
+  }
+  console.warn('[daemon] Repaired daemon PID ownership to match the authenticated endpoint')
+}
+
+/**
+ * Recovers the owning daemon's launch metadata.
+ *
+ * Why: `entryPath`/`appVersion` gate bundle-freshness and (on Windows) which relocated daemon
+ * host directories are pinned against pruning, and the Linux pair gates pid-recycle detection.
+ * Publishing a repaired record without them makes a healthy daemon look permanently stale.
+ * The values come from the authenticated hello rather than the owner's command line: a command
+ * line is a single space-joined string, so any install path containing a space (`C:\Program
+ * Files\...`, `/Applications/Orca 2.app/...`) cannot be split back into argv unambiguously.
+ */
+async function readDaemonOwnerMetadata(
+  identity: DaemonEndpointIdentity
+): Promise<Partial<DaemonPidFile>> {
+  const metadata: Partial<DaemonPidFile> = {}
+  if (identity.entryPath) {
+    metadata.entryPath = identity.entryPath
+  }
+  if (identity.appVersion) {
+    metadata.appVersion = identity.appVersion
+  }
+  if (identity.spawnerExecPath) {
+    metadata.spawnerExecPath = identity.spawnerExecPath
+  }
+  const incarnation = await readDaemonProcessIncarnation(identity.pid)
+  if (incarnation) {
+    metadata.linuxStartTicks = incarnation.linuxStartTicks
+    metadata.bootId = incarnation.bootId
+  }
+  return metadata
+}
+
+function pidRecordMatchesEndpoint(pidPath: string, identity: DaemonEndpointIdentity): boolean {
+  try {
+    const record = JSON.parse(readFileSync(pidPath, 'utf8')) as {
+      pid?: unknown
+      startedAtMs?: unknown
+      launchNonce?: unknown
+    }
+    return (
+      record.pid === identity.pid &&
+      record.startedAtMs === identity.startedAtMs &&
+      record.launchNonce === identity.launchNonce
+    )
+  } catch {
+    return false
+  }
+}
+
+export function releaseDaemonAdoptionLease(handle: DaemonProcessHandle | null): void {
+  takeDaemonAdoptionLeaseRelease(handle)?.()
+}
+
+export function takeDaemonAdoptionLeaseRelease(
+  handle: DaemonProcessHandle | null
+): (() => void) | undefined {
+  const release = handle?.releaseAdoptionLease
+  if (!release || !handle) {
+    return undefined
+  }
+  delete handle.releaseAdoptionLease
+  return release
+}
+
+export async function cleanupFailedDaemonAdoption(
+  failedSpawner: DaemonSpawner,
+  current: DaemonPtyAdapter,
+  legacy: DaemonPtyAdapter[] = []
+): Promise<void> {
+  const handle = failedSpawner.getHandle()
+  const results = await Promise.allSettled([
+    Promise.resolve().then(() => releaseDaemonAdoptionLease(handle)),
+    ...legacy.map((entry) => entry.disconnectOnly()),
+    (async () => {
+      try {
+        // Why: other authenticated clients may win, so only daemon-side shutdownIfIdle can prove a failed adoption is killable.
+        await current.disconnectOnly()
+      } catch (error) {
+        current.dispose()
+        throw error
+      }
+    })()
+  ])
+  const failures = results.flatMap((result) =>
+    result.status === 'rejected' ? [result.reason] : []
+  )
+  if (failures.length > 0) {
+    throw new AggregateError(failures, 'Daemon adoption cleanup failed')
+  }
+}
diff --git a/src/main/daemon/daemon-init.ts b/src/main/daemon/daemon-init.ts
index 0c09836f7fe..918547d8b79 100644
--- a/src/main/daemon/daemon-init.ts
+++ b/src/main/daemon/daemon-init.ts
@@ -1,1401 +1,20 @@
-/* eslint-disable max-lines -- Why: owns the full daemon lifecycle (init, launch, adapter wiring,
-restart, teardown); the "swap the provider atomically" invariant keeps restart + singletons co-located. */
-import { randomUUID } from 'node:crypto'
-import { getAppEnvironment } from '../../shared/app-environment'
-import { readFileSync, unlinkSync } from 'node:fs'
-import { fork, type ChildProcess } from 'node:child_process'
-import {
-  DaemonSpawner,
-  getDaemonPidPath,
-  getDaemonSocketPath,
-  getDaemonTokenPath,
-  replaceDaemonPidFile,
-  unlinkOwnedDaemonPidFile,
-  type DaemonLauncher,
-  type DaemonPidFile,
-  type DaemonProcessHandle
-} from './daemon-spawner'
-import { DAEMON_EXIT_ENDPOINT_OCCUPIED } from './daemon-endpoint-ownership'
-import { DaemonPtyAdapter } from './daemon-pty-adapter'
-import type { DaemonRespawnReason } from './daemon-pty-runtime-state'
-import { DaemonPtyRouter } from './daemon-pty-router'
-import { DaemonClient } from './client'
-import {
-  CLEAN_DISCONNECT_PROTOCOL_VERSION,
-  PREVIOUS_DAEMON_PROTOCOL_VERSIONS,
-  PROTOCOL_VERSION,
-  type ListSessionsResult
-} from './types'
-import { getMacDaemonSystemResolverHealth, checkDaemonHealth } from './daemon-health'
-import {
-  getMacDaemonTccAttributionHealth,
-  type MacDaemonTccAttributionHealth
-} from './daemon-tcc-attribution'
-import { getDaemonLaunchIdentity } from './daemon-pid-identity'
-import { isDaemonStaleForCurrentBundle } from './daemon-bundle-staleness'
-import { killStaleDaemon } from './daemon-stale-kill'
-import { parseDaemonPidFile, type ParsedDaemonPid } from './daemon-pid-file-parse'
-import {
-  collectPinnedDaemonVersions,
-  materializeRelocatedDaemonHost,
-  pruneOldDaemonHosts
-} from './daemon-host-relocation'
-import { DegradedDaemonPtyProvider } from './degraded-daemon-pty-provider'
-import { trackDaemonReplaced, trackDaemonRetired } from './daemon-lifecycle-event'
-import type { DaemonReplaceReason } from '../../shared/daemon-lifecycle-telemetry'
-import {
-  getLocalPtyProvider,
-  setLocalPtyProvider,
-  unbindLocalProviderListeners,
-  rebindLocalProviderListeners
-} from '../ipc/pty'
-import { isStartupDiagnosticsEnabled, logStartupDiagnostic } from '../startup/startup-diagnostics'
-import {
-  confirmSeededClaudeLivePtys,
-  hasSeededUnconfirmedClaudePtys
-} from '../claude-accounts/live-pty-gate'
-import { parseDaemonReadyIdentity, readDaemonProcessIncarnation } from './daemon-ready-identity'
-import type { DaemonEndpointIdentity } from './daemon-hello-protocol'
-import {
-  daemonLogArgs,
-  getAliveDaemonSessionCount,
-  getDaemonEntryPath,
-  getDaemonHistoryDir as getHistoryDir,
-  getDaemonRuntimeDir as getRuntimeDir,
-  probeDaemonSocket as probeSocket,
-  resolvePackagedDarwinAppVersion
-} from './daemon-launch-paths'
-
-// Why: daemon init runs concurrent with window load, so an in-process t timestamp (not harness stderr timing) measures cold-start.
-function logDaemonMilestone(event: string, details: Record<string, unknown> = {}): void {
-  if (isStartupDiagnosticsEnabled()) {
-    logStartupDiagnostic(event, {
-      t: Math.round(performance.now()),
-      ...details
-    })
-  }
-}
-
-// Why: extra hello+listSessions probes (~5s each) giving a wedged-but-connectable daemon ~60s grace to answer and keep its live sessions before a permanent wedge (#8689) is replaced; raise only alongside the fail-open cap.
-export const WEDGED_DAEMON_GRACE_RETRIES = 11
-const DAEMON_SELF_SHUTDOWN_WAIT_MS = 5_000
-const DAEMON_CHILD_TERMINATION_GRACE_MS = 5_000
-const DAEMON_CHILD_FORCE_EXIT_WAIT_MS = 1_000
-
-class DaemonEndpointOwnershipError extends Error {}
-
-/**
- * The one method the ownership checks need from a connected client.
- *
- * Why: naming the capability instead of casting DaemonClient to Partial keeps a rename from
- * silently turning the fence into a no-op — the compiler now rejects a client without it.
- */
-type DaemonEndpointIdentityReader = {
-  getDaemonIdentity?: () => DaemonEndpointIdentity | null
-}
-
-function readDaemonEndpointIdentity(
-  client: DaemonEndpointIdentityReader
-): DaemonEndpointIdentity | null {
-  return client.getDaemonIdentity?.() ?? null
-}
-
-let spawner: DaemonSpawner | null = null
-type DaemonProvider = DaemonPtyRouter | DaemonPtyAdapter | DegradedDaemonPtyProvider
-
-let adapter: DaemonProvider | null = null
-// Why: coalesce concurrent restartDaemon() calls so two entries can't race the 7-step sequence against a half-spawned replacement.
-let restartInFlight: Promise<RestartDaemonResult> | null = null
-
-function createPreservedDaemonHandle(
-  runtimeDir: string,
-  protocolVersion = PROTOCOL_VERSION,
-  mode?: 'degraded-new-pty-fallback'
-): DaemonProcessHandle {
-  const handle: DaemonProcessHandle = {
-    shutdown: async () => {
-      await cleanupDaemonForProtocol(runtimeDir, protocolVersion)
-    }
-  }
-  if (mode) {
-    handle.mode = mode
-  }
-  return handle
-}
-
-async function holdDaemonAdoptionLease(
-  handle: DaemonProcessHandle,
-  socketPath: string,
-  tokenPath: string,
-  connectedClient?: DaemonClient,
-  expectedIdentity?: DaemonEndpointIdentity,
-  pidPath?: string
-): Promise<DaemonProcessHandle> {
-  const client = connectedClient ?? new DaemonClient({ socketPath, tokenPath })
-  try {
-    await client.ensureConnected()
-    if (expectedIdentity) {
-      const actualIdentity = readDaemonEndpointIdentity(client)
-      if (
-        !actualIdentity ||
-        actualIdentity.pid !== expectedIdentity.pid ||
-        actualIdentity.startedAtMs !== expectedIdentity.startedAtMs ||
-        actualIdentity.launchNonce !== expectedIdentity.launchNonce
-      ) {
-        throw new DaemonEndpointOwnershipError('Daemon endpoint ownership changed during startup')
-      }
-    }
-    await reconcileDaemonPidOwnership(client, pidPath)
-  } catch (error) {
-    client.disconnect()
-    throw error
-  }
-  handle.releaseAdoptionLease = () => client.disconnect()
-  return handle
-}
-
-async function reconcileDaemonPidOwnership(
-  client: DaemonEndpointIdentityReader,
-  pidPath?: string
-): Promise<void> {
-  const endpointIdentity = readDaemonEndpointIdentity(client)
-  if (!pidPath || !endpointIdentity || pidRecordMatchesEndpoint(pidPath, endpointIdentity)) {
-    return
-  }
-  // Why: the mismatched record's metadata describes a different daemon and must not be copied
-  // onto this one. Re-derive it from the authenticated owner instead, so the repaired record
-  // keeps the fields freshness, host pinning and pid-recycle detection depend on.
-  const { pid, startedAtMs, launchNonce } = endpointIdentity
-  const ownerMetadata = await readDaemonOwnerMetadata(endpointIdentity)
-  if (!replaceDaemonPidFile(pidPath, { pid, startedAtMs, launchNonce, ...ownerMetadata })) {
-    // Why: fail open. A record that disagrees with the endpoint is a diagnosable nuisance;
-    // abandoning a healthy adoptable daemon over a failed file write costs the user every
-    // persistent terminal on the machine.
-    console.warn(
-      '[daemon] Could not repair daemon PID ownership; adopting the authenticated endpoint anyway'
-    )
-    return
-  }
-  console.warn('[daemon] Repaired daemon PID ownership to match the authenticated endpoint')
-}
-
-/**
- * Recovers the owning daemon's launch metadata.
- *
- * Why: `entryPath`/`appVersion` gate bundle-freshness and (on Windows) which relocated daemon
- * host directories are pinned against pruning, and the Linux pair gates pid-recycle detection.
- * Publishing a repaired record without them makes a healthy daemon look permanently stale.
- * The values come from the authenticated hello rather than the owner's command line: a command
- * line is a single space-joined string, so any install path containing a space (`C:\Program
- * Files\...`, `/Applications/Orca 2.app/...`) cannot be split back into argv unambiguously.
- */
-async function readDaemonOwnerMetadata(
-  identity: DaemonEndpointIdentity
-): Promise<Partial<DaemonPidFile>> {
-  const metadata: Partial<DaemonPidFile> = {}
-  if (identity.entryPath) {
-    metadata.entryPath = identity.entryPath
-  }
-  if (identity.appVersion) {
-    metadata.appVersion = identity.appVersion
-  }
-  if (identity.spawnerExecPath) {
-    metadata.spawnerExecPath = identity.spawnerExecPath
-  }
-  const incarnation = await readDaemonProcessIncarnation(identity.pid)
-  if (incarnation) {
-    metadata.linuxStartTicks = incarnation.linuxStartTicks
-    metadata.bootId = incarnation.bootId
-  }
-  return metadata
-}
-
-function pidRecordMatchesEndpoint(pidPath: string, identity: DaemonEndpointIdentity): boolean {
-  try {
-    const record = JSON.parse(readFileSync(pidPath, 'utf8')) as {
-      pid?: unknown
-      startedAtMs?: unknown
-      launchNonce?: unknown
-    }
-    return (
-      record.pid === identity.pid &&
-      record.startedAtMs === identity.startedAtMs &&
-      record.launchNonce === identity.launchNonce
-    )
-  } catch {
-    return false
-  }
-}
-
-function releaseDaemonAdoptionLease(handle: DaemonProcessHandle | null): void {
-  takeDaemonAdoptionLeaseRelease(handle)?.()
-}
-
-function takeDaemonAdoptionLeaseRelease(
-  handle: DaemonProcessHandle | null
-): (() => void) | undefined {
-  const release = handle?.releaseAdoptionLease
-  if (!release || !handle) {
-    return undefined
-  }
-  delete handle.releaseAdoptionLease
-  return release
-}
-
-async function cleanupFailedDaemonAdoption(
-  failedSpawner: DaemonSpawner,
-  current: DaemonPtyAdapter,
-  legacy: DaemonPtyAdapter[] = []
-): Promise<void> {
-  const handle = failedSpawner.getHandle()
-  const results = await Promise.allSettled([
-    Promise.resolve().then(() => releaseDaemonAdoptionLease(handle)),
-    ...legacy.map((entry) => entry.disconnectOnly()),
-    (async () => {
-      try {
-        // Why: other authenticated clients may win, so only daemon-side shutdownIfIdle can prove a failed adoption is killable.
-        await current.disconnectOnly()
-      } catch (error) {
-        current.dispose()
-        throw error
-      }
-    })()
-  ])
-  const failures = results.flatMap((result) =>
-    result.status === 'rejected' ? [result.reason] : []
-  )
-  if (failures.length > 0) {
-    throw new AggregateError(failures, 'Daemon adoption cleanup failed')
-  }
-}
-
-async function terminateLaunchedDaemonChild(child: ChildProcess): Promise<void> {
-  try {
-    if (
-      (child.exitCode !== null && child.exitCode !== undefined) ||
-      (child.signalCode !== null && child.signalCode !== undefined)
-    ) {
-      return
-    }
-    await new Promise<void>((resolve, reject) => {
-      let gracefulTimer: ReturnType<typeof setTimeout>
-      let forcedTimer: ReturnType<typeof setTimeout> | undefined
-      let settled = false
-      const finish = (error?: unknown): void => {
-        if (settled) {
-          return
-        }
-        settled = true
-        clearTimeout(gracefulTimer)
-        if (forcedTimer) {
-          clearTimeout(forcedTimer)
-        }
-        child.off('exit', onExit)
-        if (error) {
-          reject(error)
-        } else {
-          resolve()
-        }
-      }
-      const onExit = (): void => finish()
-      child.on('exit', onExit)
-      gracefulTimer = setTimeout(() => {
-        if (child.pid) {
-          try {
-            process.kill(child.pid, 'SIGKILL')
-          } catch (error) {
-            finish(isNoSuchProcessError(error) ? undefined : error)
-            return
-          }
-        }
-        if (!settled) {
-          forcedTimer = setTimeout(
-            () => finish(new Error('Daemon did not exit after SIGKILL')),
-            DAEMON_CHILD_FORCE_EXIT_WAIT_MS
-          )
-        }
-      }, DAEMON_CHILD_TERMINATION_GRACE_MS)
-      if (child.pid) {
-        try {
-          process.kill(child.pid, 'SIGTERM')
-        } catch (error) {
-          finish(isNoSuchProcessError(error) ? undefined : error)
-        }
-      } else {
-        finish()
-      }
-    })
-  } finally {
-    if (child.connected) {
-      child.disconnect()
-    }
-    child.unref()
-  }
-}
-
-function isNoSuchProcessError(error: unknown): boolean {
-  return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ESRCH'
-}
-
-async function shouldPreserveDaemonWithLiveSessions(
-  socketPath: string,
-  tokenPath: string,
-  replacementLabel: string
-): Promise<boolean> {
-  const liveSessionCount = await getAliveDaemonSessionCount(socketPath, tokenPath)
-  if (liveSessionCount === 0) {
-    return false
-  }
-  console.warn(
-    liveSessionCount === null
-      ? `[daemon] Preserving daemon ${replacementLabel} because live session state could not be verified`
-      : `[daemon] Preserving daemon ${replacementLabel} because it owns ${liveSessionCount} live session${liveSessionCount === 1 ? '' : 's'}`
-  )
-  return true
-}
-
-// Why: the adapter decides a runtime resolver replacement, but the launcher completes it — and by
-// then the daemon has usually self-retired (dropping its last authenticated client is enough), so
-// there is nothing left to kill and the launcher's own confirmed-kill gate would report nothing.
-// The adapter hands the reason across so the launch it triggers reports what actually drove it.
-let attributedReplaceReason: DaemonReplaceReason | null = null
-
-function createOutOfProcessLauncher(
-  runtimeDir: string,
-  macosLoginSessionWatch = false
-): DaemonLauncher {
-  return async (socketPath, tokenPath, suppliedPidPath, suppliedLaunchNonce) => {
-    const entryPath = getDaemonEntryPath()
-    const pidPath = suppliedPidPath ?? getDaemonPidPath(runtimeDir)
-    const launchNonce = suppliedLaunchNonce ?? randomUUID()
-    // One-shot: whichever launch consumes it owns the attribution, so a later unrelated launch can't
-    // reuse it. The write in the respawn closure reaches here without an intervening await, which is
-    // what makes a bare module-scoped slot safe — keep it that way or a concurrent launch can steal it.
-    const attributedReason = attributedReplaceReason
-    attributedReplaceReason = null
-    let pendingReplacement:
-      | {
-          reason: Parameters<typeof trackDaemonReplaced>[0]
-          liveSessionCount: number | null
-        }
-      | undefined
-    let confirmedReplacement = false
-    let adoptionClient: DaemonClient | null = new DaemonClient({
-      socketPath,
-      tokenPath
-    })
-    try {
-      // Why: acquire the full pair before control-only probes so an expired inherited deadline can't fire in the probe-to-adoption gap.
-      await adoptionClient.ensureConnected()
-      await reconcileDaemonPidOwnership(adoptionClient, pidPath)
-    } catch {
-      adoptionClient.disconnect()
-      adoptionClient = null
-    }
-    const preserveDaemon = async (
-      mode?: 'degraded-new-pty-fallback'
-    ): Promise<DaemonProcessHandle> => {
-      const connectedClient = adoptionClient ?? undefined
-      adoptionClient = null
-      return holdDaemonAdoptionLease(
-        createPreservedDaemonHandle(runtimeDir, PROTOCOL_VERSION, mode),
-        socketPath,
-        tokenPath,
-        connectedClient,
-        undefined,
-        pidPath
-      )
-    }
-    try {
-      const health = await checkDaemonHealth(socketPath, tokenPath)
-      if (health === 'healthy') {
-        const resolverHealth = await getMacDaemonSystemResolverHealth(socketPath, tokenPath)
-        if (resolverHealth === 'unhealthy') {
-          const liveSessionCount = await getAliveDaemonSessionCount(socketPath, tokenPath)
-          if (liveSessionCount !== 0) {
-            console.warn(
-              liveSessionCount === null
-                ? '[daemon] Preserving daemon with unavailable macOS system resolver because live session state could not be verified'
-                : `[daemon] Preserving daemon with unavailable macOS system resolver because it owns ${liveSessionCount} live session${liveSessionCount === 1 ? '' : 's'}`
-            )
-            return preserveDaemon()
-          }
-          console.warn('[daemon] Replacing daemon with unavailable macOS system resolver')
-          pendingReplacement = {
-            reason: 'unhealthy_resolver',
-            liveSessionCount
-          }
-          confirmedReplacement = (await cleanupDaemonForProtocol(runtimeDir, PROTOCOL_VERSION))
-            .cleaned
-        } else {
-          // Why: a protocol-healthy daemon can outlive its launching app bundle (dev worktree rebuild, or packaged update replacing the app path).
-          const identity = await getDaemonLaunchIdentity(
-            runtimeDir,
-            socketPath,
-            tokenPath,
-            entryPath
-          )
-          const stalePackagedBundle =
-            getAppEnvironment().isPackaged() &&
-            (await isDaemonStaleForCurrentBundle(
-              runtimeDir,
-              socketPath,
-              tokenPath,
-              getAppEnvironment().getVersion()
-            ))
-          if (identity === 'mismatch' || stalePackagedBundle) {
-            // Why: replacing a healthy daemon kills its child PTYs; defer code freshness until no live sessions would be lost.
-            const replacementLabel = stalePackagedBundle
-              ? 'launched before the current app bundle was installed'
-              : 'launched from a different app path'
-            if (
-              await shouldPreserveDaemonWithLiveSessions(socketPath, tokenPath, replacementLabel)
-            ) {
-              return preserveDaemon()
-            }
-            console.warn(
-              stalePackagedBundle
-                ? '[daemon] Replacing daemon launched before the current app bundle was installed'
-                : '[daemon] Replacing daemon launched from a different app path'
-            )
-            // liveSessionCount is 0: shouldPreserveDaemonWithLiveSessions() only falls through at exactly 0.
-            pendingReplacement = {
-              reason: stalePackagedBundle ? 'stale_bundle' : 'different_app_path',
-              liveSessionCount: 0
-            }
-            confirmedReplacement = (await cleanupDaemonForProtocol(runtimeDir, PROTOCOL_VERSION))
-              .cleaned
-          } else {
-            const attributionHealth = await getMacDaemonTccAttributionHealth(
-              runtimeDir,
-              socketPath,
-              tokenPath
-            )
-            if (attributionHealth === 'severed') {
-              // Why: replacing with live sessions would kill them; Settings → Developer
-              // Permissions surfaces the Manage Sessions → Restart remedy instead.
-              const liveSessionCount = await getAliveDaemonSessionCount(socketPath, tokenPath)
-              if (liveSessionCount === 0) {
-                console.warn(
-                  '[daemon] Replacing daemon whose macOS TCC attribution is severed (spawning app binary no longer exists)'
-                )
-                pendingReplacement = { reason: 'severed_tcc_attribution', liveSessionCount }
-                confirmedReplacement = (
-                  await cleanupDaemonForProtocol(runtimeDir, PROTOCOL_VERSION)
-                ).cleaned
-              } else {
-                return preserveDaemon()
-              }
-            } else {
-              // Why: healthy daemon from a previous session answered a protocol ping — safe to reuse.
-              return preserveDaemon()
-            }
-          }
-        }
-      } else {
-        // Why: a busy machine can time out the health check on a live daemon; re-verify with a session list before killing its sessions.
-        let liveSessionCount = await getAliveDaemonSessionCount(socketPath, tokenPath)
-        // Why: a wedged-but-connectable daemon (Windows update relaunch) may still own live sessions, so grace-retry before replacing; a permanent wedge (#8689) exhausts the grace, and 'rejected' skips it (handshake refused = never adoptable).
-        let graceRetry = 0
-        while (
-          liveSessionCount === null &&
-          health !== 'rejected' &&
-          graceRetry < WEDGED_DAEMON_GRACE_RETRIES &&
-          (await probeSocket(socketPath))
-        ) {
-          liveSessionCount = await getAliveDaemonSessionCount(socketPath, tokenPath)
-          graceRetry++
-        }
-        if (liveSessionCount !== null && liveSessionCount > 0) {
-          if (health === 'pty-spawn-unhealthy') {
-            console.warn(
-              `[daemon] DEGRADED MODE: preserving daemon that failed the PTY spawn health check because it owns ${liveSessionCount} live session${liveSessionCount === 1 ? '' : 's'}. Existing sessions keep working; fresh terminals run on the local provider WITHOUT daemon persistence until you restart the daemon (Manage Sessions → Restart).`
-            )
-            return preserveDaemon('degraded-new-pty-fallback')
-          }
-          console.warn(
-            `[daemon] Preserving daemon that failed the health check because it owns ${liveSessionCount} live session${liveSessionCount === 1 ? '' : 's'}`
-          )
-          return preserveDaemon()
-        }
-        // Why: the sibling replace branches announce themselves, but this one used
-        // to kill a daemon silently — leaving no way to tell a replacement apart
-        // from an adoption after the fact. A cold start also lands here with
-        // nothing to replace, so only speak up once something actually answered:
-        // a probe that returned a count, a socket that survived a grace retry, or
-        // a refused hello.
-        if (liveSessionCount !== null || graceRetry > 0 || health === 'rejected') {
-          console.warn(
-            `[daemon] Replacing daemon that failed the health check (health=${health}, liveSessions=${liveSessionCount ?? 'unverifiable'}, graceRetries=${graceRetry})`
-          )
-        }
-        // Why: unlike the log above, telemetry gates on confirmedReplacement below — the
-        // post-kill truth — so a cold start that killed nothing never reports a replacement.
-        pendingReplacement = {
-          reason: 'failed_health_check',
-          liveSessionCount
-        }
-      }
-
-      // Why: a raw socket can outlive a broken daemon; kill by PID before respawn so the new daemon doesn't race the stale one.
-      adoptionClient?.disconnect()
-      adoptionClient = null
-      const killOutcome = await killStaleDaemon(runtimeDir, socketPath, tokenPath)
-      if (killOutcome.liveOwnerSurvived) {
-        // Why: forking beside a daemon we could not prove dead is precisely how the endpoint
-        // owner and the session host diverge. But refusing outright would leave the user with
-        // no daemon at all, and we have just proved something still answers the endpoint —
-        // so adopt it in degraded mode: existing sessions keep working, new PTYs run locally.
-        console.warn(
-          '[daemon] DEGRADED MODE: adopting a daemon that could not be confirmed stopped. Existing sessions keep working; fresh terminals run on the local provider WITHOUT daemon persistence until you restart the daemon (Manage Sessions → Restart).'
-        )
-        try {
-          return await preserveDaemon('degraded-new-pty-fallback')
-        } catch {
-          // It died between the probe and the adoption; the endpoint is genuinely free now.
-          throw new DaemonEndpointOwnershipError(
-            'Daemon replacement aborted: the existing daemon could not be confirmed stopped'
-          )
-        }
-      }
-      confirmedReplacement = killOutcome.killed || confirmedReplacement
-      // Why: rank by how well each reason is evidenced. A confirmed kill whose reason positively
-      // identified the daemon outranks the attribution, so a stale bundle caught here is not billed
-      // to the resolver. failed_health_check is the residual "couldn't tell" bucket though — it also
-      // absorbs wedges and crashes — so the adapter's attribution beats it. That case is not exotic:
-      // the same dead login session that fails the resolver also fails the PTY spawn probe, and with
-      // zero live sessions that lands here rather than in the degraded preserve above.
-      const identifiedReplacement =
-        pendingReplacement &&
-        confirmedReplacement &&
-        pendingReplacement.reason !== 'failed_health_check'
-          ? pendingReplacement
-          : null
-      if (identifiedReplacement) {
-        trackDaemonReplaced(identifiedReplacement.reason, identifiedReplacement.liveSessionCount)
-      } else if (attributedReason) {
-        trackDaemonReplaced(attributedReason, 0)
-      } else if (pendingReplacement && confirmedReplacement) {
-        trackDaemonReplaced(pendingReplacement.reason, pendingReplacement.liveSessionCount)
-      }
-
-      const userDataPath = getAppEnvironment().getPath('userData')
-      // Why: on win32 packaged, stage a daemon-host copy in userData so its image escapes the NSIS updater's kill zone; lazy so it's off first-paint. Fail-open: null → in-dir host.
-      const relocatedHost = materializeRelocatedDaemonHost()
-      // Fork the relocated entry when available; otherwise the install-dir entry.
-      const forkEntryPath = relocatedHost ? relocatedHost.entryPath : entryPath
-      const child = fork(
-        forkEntryPath,
-        [
-          '--socket',
-          socketPath,
-          '--token',
-          tokenPath,
-          '--pid-record',
-          pidPath,
-          '--launch-nonce',
-          launchNonce,
-          '--entry-path',
-          entryPath,
-          '--app-version',
-          getAppEnvironment().getVersion(),
-          '--spawner-exec-path',
-          process.execPath,
-          ...(macosLoginSessionWatch ? ['--login-session-watch'] : []),
-          ...daemonLogArgs()
-        ],
-        {
-          // Why: detached daemons outlive dev worktrees; userData keeps process.cwd() valid after a repo/worktree is deleted.
-          cwd: userDataPath,
-          // Why: detached+unref outlives Electron; stdout 'ignore' (else blocks exit), stderr 'pipe' captures startup crashes lost in v1.4.129-rc.1.
-          detached: true,
-          stdio: ['ignore', 'ignore', 'pipe', 'ipc'],
-          // Why: run the byte-identical relocated Orca.exe so the image path sits outside the updater's kill zone.
-          ...(relocatedHost ? { execPath: relocatedHost.execPath } : {}),
-          // Why: run the fork as plain Node so Electron's GPU/display init can't interfere with node-pty's posix_spawn of the spawn-helper.
-          env: {
-            ...process.env,
-            ELECTRON_RUN_AS_NODE: '1',
-            // Why: the detached plain-Node daemon has no AppEnvironment, but shell rcfiles must live outside swept tmp.
-            ORCA_USER_DATA_PATH: userDataPath
-          }
-        }
-      )
-
-      // Why: keep only the startup-window stderr tail so a crash cause is visible without unbounded memory.
-      const STARTUP_STDERR_MAX_BYTES = 8192
-      let startupStderr = ''
-      let collectingStderr = true
-      const onStartupStderr = (chunk: Buffer): void => {
-        if (!collectingStderr) {
-          return
-        }
-        startupStderr += chunk.toString('utf8')
-        if (startupStderr.length > STARTUP_STDERR_MAX_BYTES) {
-          startupStderr = startupStderr.slice(-STARTUP_STDERR_MAX_BYTES)
-        }
-      }
-      child.stderr?.on('data', onStartupStderr)
-      // Why: release the detached daemon's stderr once up/failed — a live piped stream refs the parent loop and blocks Electron exit.
-      const releaseStderr = (): void => {
-        collectingStderr = false
-        child.stderr?.off('data', onStartupStderr)
-        child.stderr?.destroy()
-      }
-
-      // Wait for the daemon to signal readiness via IPC
-      let launchedIdentity: DaemonEndpointIdentity | null = null
-      let endpointUnavailableReason: string | null = null
-      const startupSignal = new Promise<void>((resolve, reject) => {
-        let timer: ReturnType<typeof setTimeout> | undefined
-        let settled = false
-        function cleanupStartupListeners(): void {
-          if (timer) {
-            clearTimeout(timer)
-          }
-          child.off('message', onReadyMessage)
-          child.off('error', onStartupError)
-          child.off('exit', onStartupExit)
-        }
-        async function fail(error: Error): Promise<void> {
-          if (settled) {
-            return
-          }
-          settled = true
-          cleanupStartupListeners()
-          // Why: attach the captured stderr tail to the thrown error and log it so a startup crash isn't just "exited with code 1".
-          const stderrTail = startupStderr.trim()
-          if (stderrTail) {
-            console.warn(`[daemon] startup failed; captured stderr tail:\n${stderrTail}`)
-          }
-          releaseStderr()
-          const startupError = stderrTail
-            ? new Error(`${error.message}\nDaemon stderr (tail):\n${stderrTail}`)
-            : error
-          try {
-            await terminateLaunchedDaemonChild(child)
-          } catch (cleanupError) {
-            reject(
-              new AggregateError(
-                [startupError, cleanupError],
-                'Daemon startup and child cleanup both failed'
-              )
-            )
-            return
-          }
-          if (Number.isSafeInteger(child.pid) && (child.pid as number) > 0) {
-            unlinkOwnedDaemonPidFile(pidPath, child.pid as number, launchNonce)
-          }
-          reject(startupError)
-        }
-        function onReadyMessage(msg: unknown): void {
-          if (
-            msg &&
-            typeof msg === 'object' &&
-            (msg as { type?: string }).type === 'endpoint-unavailable'
-          ) {
-            // Why: the child lost the endpoint race rather than crashing. Record it so the
-            // launcher can adopt the winner instead of reporting a generic startup failure.
-            endpointUnavailableReason = (msg as { reason?: string }).reason ?? 'occupied'
-            void fail(new Error(`Daemon could not take the endpoint: ${endpointUnavailableReason}`))
-            return
-          }
-          if (msg && typeof msg === 'object' && (msg as { type?: string }).type === 'ready') {
-            if (settled) {
-              return
-            }
-            const readyIdentity = parseDaemonReadyIdentity(msg)
-            if (!Number.isSafeInteger(child.pid) || (child.pid as number) <= 0 || !readyIdentity) {
-              void fail(new Error('Daemon readiness identity is incomplete'))
-              return
-            }
-            launchedIdentity = {
-              pid: child.pid as number,
-              ...readyIdentity,
-              launchNonce
-            }
-            settled = true
-            // Why: daemon is detached after readiness; detach startup listeners so the launch promise closure isn't retained.
-            cleanupStartupListeners()
-            // Why: release IPC/stderr and unref so Electron can exit without waiting; the daemon keeps running detached.
-            releaseStderr()
-            child.disconnect()
-            child.unref()
-            resolve()
-          }
-        }
-
-        function onStartupError(err: Error): void {
-          void fail(err)
-        }
-
-        function onStartupExit(code: number | null): void {
-          if (code === DAEMON_EXIT_ENDPOINT_OCCUPIED) {
-            // Why here and not only on the IPC message: the exit is the event this wait settles
-            // on, so keying off it cannot lose to a notification still in the channel.
-            endpointUnavailableReason = 'occupied'
-          }
-          void fail(new Error(`Daemon exited during startup with code ${code}`))
-        }
-
-        timer = setTimeout(() => {
-          void fail(new Error('Daemon startup timed out'))
-        }, 10000)
-
-        child.on('message', onReadyMessage)
-        child.on('error', onStartupError)
-        child.on('exit', onStartupExit)
-      })
-
-      try {
-        await startupSignal
-      } catch (error) {
-        if (endpointUnavailableReason !== 'occupied') {
-          throw error
-        }
-        // Why adopt rather than retry: another daemon proved it owns the endpoint and is
-        // answering on it. Forking again would lose the same race, and reporting a startup
-        // failure strands this app on local non-persistent PTYs beside a healthy daemon.
-        console.warn(
-          '[daemon] Endpoint was taken by another daemon during startup — adopting it instead'
-        )
-        // Why pidPath: adopting reconciles the PID record against the identity the daemon
-        // reports over hello, repairing a record that names the wrong incarnation. Every other
-        // adoption path passes it; this one skipped it, so the incumbent we adopt here was the
-        // only one whose record never got that repair.
-        return await holdDaemonAdoptionLease(
-          createPreservedDaemonHandle(runtimeDir),
-          socketPath,
-          tokenPath,
-          undefined,
-          undefined,
-          pidPath
-        )
-      }
-
-      try {
-        if (!launchedIdentity) {
-          throw new Error('Daemon readiness identity is incomplete')
-        }
-        return await holdDaemonAdoptionLease(
-          {
-            shutdown: () => terminateLaunchedDaemonChild(child)
-          },
-          socketPath,
-          tokenPath,
-          undefined,
-          launchedIdentity,
-          pidPath
-        )
-      } catch (error) {
-        if (error instanceof DaemonEndpointOwnershipError) {
-          await terminateLaunchedDaemonChild(child)
-          unlinkOwnedDaemonPidFile(pidPath, child.pid as number, launchNonce)
-          throw error
-        }
-        // Why: another client may have adopted this live process; keep its pid record until exit, but remove one published after an early exit.
-        let pidRecordRemoved = false
-        const removeExitedPidRecord = (): void => {
-          if (pidRecordRemoved) {
-            return
-          }
-          pidRecordRemoved = true
-          unlinkOwnedDaemonPidFile(pidPath, child.pid as number, launchNonce)
-        }
-        child.once('exit', removeExitedPidRecord)
-        if (
-          (child.exitCode !== null && child.exitCode !== undefined) ||
-          (child.signalCode !== null && child.signalCode !== undefined)
-        ) {
-          child.off('exit', removeExitedPidRecord)
-          removeExitedPidRecord()
-        }
-        throw error
-      }
-    } catch (error) {
-      adoptionClient?.disconnect()
-      adoptionClient = null
-      // Why: the launcher may now fork onto an endpoint it could not classify, because the
-      // publisher is the real guard — and that guard works by refusing to overwrite what it
-      // cannot prove dead, so the child exits instead of splitting the brain. Correct, but
-      // giving up here costs the user every persistent session for the whole run. Something
-      // answering the endpoint now is a daemon worth adopting, not a reason to fall back to
-      // local PTYs.
-      if (await probeSocket(socketPath)) {
-        console.warn(
-          '[daemon] DEGRADED MODE: adopting the daemon that owns the endpoint after a replacement could not publish onto it. Existing sessions keep working; fresh terminals run on the local provider WITHOUT daemon persistence until you restart the daemon (Manage Sessions → Restart).'
-        )
-        try {
-          return await preserveDaemon('degraded-new-pty-fallback')
-        } catch {
-          // It stopped answering between the probe and the adoption; report the launch failure.
-        }
-      }
-      throw error
-    }
-  }
-}
-
-export async function initDaemonPtyProvider(
-  signal?: AbortSignal,
-  options: { macosLoginSessionWatch?: boolean } = {}
-): Promise<void> {
-  logDaemonMilestone('daemon-init-start')
-  // Why: e2e coverage for the startup PTY gate (#5232) needs a daemon init that deterministically outlasts the first-window timeout.
-  const e2eInitDelayMs = Number(process.env.ORCA_E2E_DAEMON_INIT_DELAY_MS)
-  if (Number.isFinite(e2eInitDelayMs) && e2eInitDelayMs > 0) {
-    await new Promise((resolve) => setTimeout(resolve, e2eInitDelayMs))
-  }
-  const runtimeDir = getRuntimeDir()
-
-  const newSpawner = new DaemonSpawner({
-    runtimeDir,
-    launcher: createOutOfProcessLauncher(runtimeDir, options.macosLoginSessionWatch ?? false)
-  })
-
-  // Why: assign the module-level spawner/adapter only after both succeed, so a failed ensureRunning() leaves no stale spawner.
-  const info = await newSpawner.ensureRunning()
-  // Why: reclaim superseded daemon-host copies on EVERY launch (spawns are rare), keeping current + live-daemon-pinned versions.
-  pruneOldDaemonHosts(collectPinnedDaemonVersions(runtimeDir))
-  const launchMode = newSpawner.getHandle()?.mode
-  logDaemonMilestone('daemon-current-ready')
-  if (signal?.aborted) {
-    // Why: fail-open may already have spawned fallback PTYs; don't install late, but retire an empty daemon (live sessions reject it and survive).
-    const abortedStartupAdapter = new DaemonPtyAdapter({
-      socketPath: info.socketPath,
-      tokenPath: info.tokenPath,
-      pidPath: getDaemonPidPath(runtimeDir),
-      profileScope: runtimeDir,
-      runtimeDir
-    })
-    releaseDaemonAdoptionLease(newSpawner.getHandle())
-    await abortedStartupAdapter.disconnectOnly()
-    return
-  }
-
-  const newAdapter = new DaemonPtyAdapter({
-    socketPath: info.socketPath,
-    tokenPath: info.tokenPath,
-    pidPath: getDaemonPidPath(runtimeDir),
-    profileScope: runtimeDir,
-    runtimeDir,
-    packagedAppVersion: resolvePackagedDarwinAppVersion(),
-    historyPath: getHistoryDir(),
-    // Why: on daemon death, ensureConnected() detects the dead socket and calls this to fork a replacement before retrying.
-    respawn: async (reason: DaemonRespawnReason) => {
-      // Why: attribute rather than emit — the launcher below is the one that completes the
-      // replacement, and emitting here would fire before the outcome is known.
-      // Caveat: a wedged-but-alive daemon (#8689) can still report died_respawn here and
-      // failed_health_check from the launcher — the app cannot tell wedged from dead at this point.
-      if (reason === 'daemon_died') {
-        console.warn('[daemon] Daemon process died — respawning')
-        // Why: a manual restart tears the daemon down under a still-live adapter, so a pane
-        // respawning on its synthetic exit would bill a user action to the crash bucket.
-        if (!restartInFlight) {
-          trackDaemonRetired('died_respawn')
-        }
-      } else {
-        // Must reach the launcher below without an await in between; see the consume site.
-        attributedReplaceReason = reason
-      }
-      newSpawner.resetHandle()
-      await newSpawner.ensureRunning()
-      return takeDaemonAdoptionLeaseRelease(newSpawner.getHandle())
-    }
-  })
-  let legacyAdapters: DaemonPtyAdapter[] = []
-  let routedAdapter: DaemonProvider = newAdapter
-  try {
-    // Why: the launcher's temporary pair closes only after this permanent pair is established, leaving no adoption gap.
-    await newAdapter.establishLifecycleLease()
-    releaseDaemonAdoptionLease(newSpawner.getHandle())
-
-    legacyAdapters = await createLegacyDaemonAdapters(runtimeDir)
-    routedAdapter =
-      launchMode === 'degraded-new-pty-fallback'
-        ? new DegradedDaemonPtyProvider({
-            current: newAdapter,
-            legacy: legacyAdapters,
-            fallback: getLocalPtyProvider(),
-            probeCurrentDaemonSpawn: async () =>
-              (await checkDaemonHealth(info.socketPath, info.tokenPath)) === 'healthy'
-          })
-        : legacyAdapters.length > 0
-          ? new DaemonPtyRouter({
-              current: newAdapter,
-              legacy: legacyAdapters
-            })
-          : newAdapter
-    if (routedAdapter instanceof DegradedDaemonPtyProvider) {
-      // Why: preserved daemon can't create fresh terminals; discover its live session ids so only they route to it (fresh panes fall back locally).
-      await routedAdapter.discoverDaemonSessions()
-    } else if (routedAdapter instanceof DaemonPtyRouter) {
-      await routedAdapter.discoverLegacySessions()
-    }
-    if (signal?.aborted) {
-      // Why: same late-swap guard after legacy discovery; release uninstalled adapter leases without killing live sessions.
-      await routedAdapter.disconnectOnly()
-      return
-    }
-  } catch (error) {
-    try {
-      await cleanupFailedDaemonAdoption(newSpawner, newAdapter, legacyAdapters)
-    } catch (cleanupError) {
-      throw new AggregateError([error, cleanupError], 'Daemon adoption and cleanup both failed')
-    }
-    throw error
-  }
-  spawner = newSpawner
-  adapter = routedAdapter
-  setLocalPtyProvider(routedAdapter)
-  // Why: the first window may register PTY listeners before daemon init finishes; rebind so daemon PTYs still fan out events.
-  rebindLocalProviderListeners()
-  logDaemonMilestone('daemon-init-done', {
-    legacyAdapters: legacyAdapters.length
-  })
-  await reconcileSeededClaudeLivePtys(routedAdapter)
-}
-
-// Why: release gate ids only for daemon-confirmed-dead sessions; keep seeds on listing failure since releasing early can rotate a live CLI's refresh token.
-async function reconcileSeededClaudeLivePtys(provider: DaemonProvider): Promise<void> {
-  if (!hasSeededUnconfirmedClaudePtys()) {
-    return
-  }
-  try {
-    const adapters =
-      provider instanceof DaemonPtyRouter || provider instanceof DegradedDaemonPtyProvider
-        ? provider.getAllAdapters()
-        : [provider]
-    const results = await Promise.allSettled(adapters.map((entry) => entry.listSessions()))
-    if (results.some((result) => result.status === 'rejected')) {
-      console.warn('[daemon] Keeping seeded Claude live-PTY gate — session listing failed')
-      return
-    }
-    confirmSeededClaudeLivePtys(
-      results.flatMap((result) =>
-        result.status === 'fulfilled' ? result.value.map((session) => session.sessionId) : []
-      )
-    )
-  } catch (error) {
-    // Why: gate bookkeeping must never fail daemon init; stale seeds only defer a usage refresh until next restart.
-    console.warn('[daemon] Failed to reconcile seeded Claude live-PTY gate:', error)
-  }
-}
-
-// Why: a narrow getter (not a raw export) keeps the "swap on restart" invariant in one place (replaceDaemonProvider).
-/**
- * Whether the installed provider is a daemon that will own FRESH terminals too.
- *
- * Why not `getDaemonProvider() !== null`: DegradedDaemonPtyProvider routes the daemon's
- * EXISTING sessions to the daemon but spawns new ones on the in-process local provider, so
- * those die with this process. A host that answered "I can recover persistent local PTYs"
- * from that state would be advertising recovery for terminals that cannot be recovered.
- */
-export function daemonOwnsFreshPersistentPtys(): boolean {
-  return adapter !== null && !(adapter instanceof DegradedDaemonPtyProvider)
-}
-
-/** Endpoint coordinates of the daemon this process installed, for out-of-band health probes. */
-export type DaemonEndpointFacts = {
-  runtimeDir: string
-  socketPath: string
-  tokenPath: string
-  pidPath: string
-  protocolVersion: number
-}
-
-export function getDaemonEndpointFacts(): DaemonEndpointFacts | null {
-  if (!adapter) {
-    return null
-  }
-  const runtimeDir = getRuntimeDir()
-  return {
-    runtimeDir,
-    socketPath: getDaemonSocketPath(runtimeDir),
-    tokenPath: getDaemonTokenPath(runtimeDir),
-    pidPath: getDaemonPidPath(runtimeDir),
-    protocolVersion: PROTOCOL_VERSION
-  }
-}
-
-/**
- * What the live daemon's own PID record says about the build it was forked from.
- *
- * Why the record and not this process's version: the daemon deliberately outlives the
- * runtime, so after an update the two can legitimately disagree — and a health surface that
- * reported orcad's version for both would hide exactly that.
- */
-export function readDaemonPidRecord(): ParsedDaemonPid | null {
-  const facts = getDaemonEndpointFacts()
-  if (!facts) {
-    return null
-  }
-  try {
-    return parseDaemonPidFile(readFileSync(facts.pidPath, 'utf8'))
-  } catch {
-    return null
-  }
-}
-
-export function getDaemonProvider(): DaemonProvider | null {
-  return adapter
-}
-
-// Why: computed from the pid record on demand (not cached at adoption) so the Settings
-// remedy surface always reflects the daemon actually serving terminals right now.
-export async function getCurrentDaemonMacTccAttributionHealth(): Promise<MacDaemonTccAttributionHealth> {
-  const runtimeDir = getRuntimeDir()
-  return getMacDaemonTccAttributionHealth(
-    runtimeDir,
-    getDaemonSocketPath(runtimeDir),
-    getDaemonTokenPath(runtimeDir)
-  )
-}
-
-/** Returns null unless every daemon generation supplied an authoritative inventory. */
-export async function listLiveDaemonPtyIds(): Promise<string[] | null> {
-  if (!adapter) {
-    return null
-  }
-  const adapters =
-    adapter instanceof DaemonPtyRouter || adapter instanceof DegradedDaemonPtyProvider
-      ? adapter.getAllAdapters()
-      : [adapter]
-  const inventories = await Promise.allSettled(
-    adapters.map((daemonAdapter) => daemonAdapter.listProcesses())
-  )
-  if (inventories.some((inventory) => inventory.status === 'rejected')) {
-    return null
-  }
-  return inventories.flatMap((inventory) =>
-    inventory.status === 'fulfilled' ? inventory.value.map((process) => process.id) : []
-  )
-}
-
-// Why: keep the module-level adapter and ipc/pty.ts's localProvider in sync so app-quit can't dispose a stale reference.
-export function replaceDaemonProvider(newAdapter: DaemonProvider): void {
-  adapter = newAdapter
-  setLocalPtyProvider(newAdapter)
-}
-
-function getCurrentDaemonAdapter(provider: DaemonProvider): DaemonPtyAdapter {
-  if (provider instanceof DaemonPtyRouter || provider instanceof DegradedDaemonPtyProvider) {
-    return provider.getCurrentAdapter()
-  }
-  return provider
-}
-
-function getLegacyDaemonAdapters(provider: DaemonProvider): DaemonPtyAdapter[] {
-  if (provider instanceof DaemonPtyRouter || provider instanceof DegradedDaemonPtyProvider) {
-    return [...provider.getLegacyAdapters()]
-  }
-  return []
-}
-
-function disposeProviderSubscriptionsOnly(provider: DaemonProvider): void {
-  if (provider instanceof DaemonPtyRouter) {
-    provider.disposeRouterOnly()
-    return
-  }
-  if (provider instanceof DegradedDaemonPtyProvider) {
-    provider.disposeProviderOnly()
-  }
-}
-
-export type RestartDaemonResult = {
-  killedCount: number
-}
-
-// Why: the 7-step restart sequence from docs/daemon-staleness-ux.md §Phase 1; current-protocol only (legacy adapters preserved).
-export async function restartDaemon(): Promise<RestartDaemonResult> {
-  if (restartInFlight) {
-    return restartInFlight
-  }
-  restartInFlight = runRestartDaemon().finally(() => {
-    restartInFlight = null
-  })
-  return restartInFlight
-}
-
-async function runRestartDaemon(): Promise<RestartDaemonResult> {
-  const currentSpawner = spawner
-  const currentAdapter = adapter
-  if (!currentSpawner || !currentAdapter) {
-    throw new Error('restartDaemon called before initDaemonPtyProvider')
-  }
-
-  const runtimeDir = getRuntimeDir()
-  // An operator asking for a restart is the deliberate "try again" that clears crash-loop
-  // containment; without this a wedged host could never be recovered from the UI.
-  currentSpawner.resetRespawnWindow()
-  const currentOnly = getCurrentDaemonAdapter(currentAdapter)
-  const legacyAdapters = getLegacyDaemonAdapters(currentAdapter)
-
-  // Step 1: synthesize pty:exit for every active session BEFORE teardown — the daemon's shutdown path never fans onExit to clients (session.ts:246-252), so the renderer would otherwise never see exits.
-  const fallbackKilledCount =
-    currentAdapter instanceof DegradedDaemonPtyProvider
-      ? await currentAdapter.shutdownFallbackSessions()
-      : 0
-  const currentDaemonSessionIds =
-    currentAdapter instanceof DegradedDaemonPtyProvider
-      ? currentAdapter.getCurrentDaemonSessionIds()
-      : []
-  const killedCount =
-    new Set([...currentOnly.getActiveSessionIds(), ...currentDaemonSessionIds]).size +
-    fallbackKilledCount
-  currentOnly.fanoutSyntheticExits(-1)
-  if (currentAdapter instanceof DegradedDaemonPtyProvider) {
-    currentAdapter.fanoutCurrentDaemonSyntheticExits(-1)
-  }
-
-  // Step 2: detach renderer listeners — after step 1 (so synthesized exits land) and before step 6 (no stale binding).
-  unbindLocalProviderListeners()
-
-  // Step 3: kill the current-protocol daemon process; legacy adapters untouched.
-  let info: Awaited<ReturnType<DaemonSpawner['ensureRunning']>>
-  try {
-    await cleanupDaemonForProtocol(runtimeDir, PROTOCOL_VERSION)
-
-    // Step 4: reuse the existing spawner so the respawn closure baked into long-lived adapters stays valid (do NOT new one).
-    currentSpawner.resetHandle()
-    info = await currentSpawner.ensureRunning()
-  } catch (error) {
-    // Why: old provider stays authoritative until the final swap; rebind since relaunch failed after teardown.
-    rebindLocalProviderListeners()
-    throw error
-  }
-
-  // Step 5: build a fresh current adapter against the respawned daemon.
-  const newCurrent = new DaemonPtyAdapter({
-    socketPath: info.socketPath,
-    tokenPath: info.tokenPath,
-    pidPath: getDaemonPidPath(runtimeDir),
-    profileScope: runtimeDir,
-    runtimeDir,
-    packagedAppVersion: resolvePackagedDarwinAppVersion(),
-    historyPath: getHistoryDir(),
-    respawn: async (reason: DaemonRespawnReason) => {
-      // Why: attribute rather than emit — the launcher below is the one that completes the
-      // replacement, and emitting here would fire before the outcome is known.
-      // Caveat: a wedged-but-alive daemon (#8689) can still report died_respawn here and
-      // failed_health_check from the launcher — the app cannot tell wedged from dead at this point.
-      if (reason === 'daemon_died') {
-        console.warn('[daemon] Daemon process died — respawning')
-        // Why: a manual restart tears the daemon down under a still-live adapter, so a pane
-        // respawning on its synthetic exit would bill a user action to the crash bucket.
-        if (!restartInFlight) {
-          trackDaemonRetired('died_respawn')
-        }
-      } else {
-        // Must reach the launcher below without an await in between; see the consume site.
-        attributedReplaceReason = reason
-      }
-      currentSpawner.resetHandle()
-      await currentSpawner.ensureRunning()
-      return takeDaemonAdoptionLeaseRelease(currentSpawner.getHandle())
-    }
-  })
-  let newProvider: DaemonProvider = newCurrent
-  try {
-    // Temporary launcher lease overlaps this permanent pair so a manual restart can't strand a newly spawned daemon during adoption.
-    await newCurrent.establishLifecycleLease()
-    releaseDaemonAdoptionLease(currentSpawner.getHandle())
-
-    // Re-wrap in a router only if legacy adapters exist; they're preserved by reference and still route to their pre-upgrade daemons.
-    newProvider =
-      legacyAdapters.length > 0
-        ? new DaemonPtyRouter({ current: newCurrent, legacy: legacyAdapters })
-        : newCurrent
-    if (newProvider instanceof DaemonPtyRouter) {
-      await newProvider.discoverLegacySessions()
-    }
-  } catch (error) {
-    let cleanupError: unknown
-    try {
-      if (newProvider instanceof DaemonPtyRouter) {
-        newProvider.disposeRouterOnly()
-      }
-      await cleanupFailedDaemonAdoption(currentSpawner, newCurrent)
-    } catch (caught) {
-      cleanupError = caught
-    }
-    // Previous provider stays module-authoritative until the swap; restore its renderer bindings when adoption fails.
-    rebindLocalProviderListeners()
-    if (cleanupError) {
-      throw new AggregateError([error, cleanupError], 'Daemon restart and cleanup both failed')
-    }
-    throw error
-  }
-
-  // Drain the old router's subscriptions via the router-only variant (plain dispose() would tear down the shared legacy adapters), after the new provider exists (no unhandled events) and before the swap (atomic for the renderer).
-  disposeProviderSubscriptionsOnly(currentAdapter)
-
-  // Step 6: swap module state (adapter + localProvider) atomically.
-  replaceDaemonProvider(newProvider)
-
-  // Step 7: rebind renderer listeners against the new provider.
-  rebindLocalProviderListeners()
-
-  return { killedCount }
-}
-
-// Disconnect without killing: the daemon survives app quit so sessions stay warm for reattach.
-// Leave history sessions marked "unclean" so a daemon crash while Orca is closed stays recoverable.
-export async function disconnectDaemon(): Promise<void> {
-  await adapter?.disconnectOnly()
-  adapter = null
-}
-
-/** Kill the daemon and all its sessions. Use for full cleanup only. */
-export async function shutdownDaemon(): Promise<void> {
-  adapter?.dispose()
-  adapter = null
-  await spawner?.shutdown()
-  spawner = null
-}
-
-export type OrphanedDaemonCleanupResult = {
-  /** True when a live daemon socket was found and torn down; false when none was running. */
-  cleaned: boolean
-  /** Number of live PTY sessions killed during cleanup (surfaced to the user). */
-  killedCount: number
-}
-
-export async function cleanupDaemonForProtocol(
-  runtimeDir: string,
-  protocolVersion: number
-): Promise<OrphanedDaemonCleanupResult> {
-  const socketPath = getDaemonSocketPath(runtimeDir, protocolVersion)
-  const tokenPath = getDaemonTokenPath(runtimeDir, protocolVersion)
-  const pidPath = getDaemonPidPath(runtimeDir, protocolVersion)
-
-  const alive = await probeSocket(socketPath)
-  if (!alive) {
-    if (protocolVersion >= CLEAN_DISCONNECT_PROTOCOL_VERSION) {
-      // Endpoint absence doesn't prove the PID record belongs to the current protocol; leave artifact cleanup to the owning daemon.
-      return { cleaned: false, killedCount: 0 }
-    }
-    try {
-      unlinkSync(pidPath)
-    } catch {
-      // Best-effort
-    }
-    return { cleaned: false, killedCount: 0 }
-  }
-
-  const client = new DaemonClient({ socketPath, tokenPath, protocolVersion })
-  let killedCount = 0
-  let didRequestShutdown = false
-  let didKillStaleDaemon = false
-  try {
-    await client.ensureConnected()
-    const sessions = await client
-      .request<ListSessionsResult>('listSessions', undefined)
-      .catch(() => ({ sessions: [] }))
-    killedCount = sessions.sessions.filter((s) => s.isAlive).length
-
-    // Use the single-shot `shutdown` RPC (kills all sessions then exits) to avoid racing per-session `kill` calls against the daemon exiting.
-    await client.request('shutdown', { killSessions: true }).catch(() => {
-      // Daemon exits immediately after the RPC, so the socket may close before the reply arrives; treat as success.
-    })
-    didRequestShutdown = true
-  } catch {
-    // Previous-protocol daemons may be wedged or too old for the RPC path; fall back to PID cleanup (only unlinks a live socket after proving the process is killed).
-    const killOutcome = await killStaleDaemon(runtimeDir, socketPath, tokenPath, protocolVersion)
-    didKillStaleDaemon = killOutcome.killed
-    if (killOutcome.liveOwnerSurvived) {
-      // Why: something still owns the endpoint. Returning as if it were cleaned lets restart
-      // fork a replacement that cannot publish onto the held name, leaving the user with no
-      // daemon instead of the one still running.
-      throw new DaemonEndpointOwnershipError(
-        'Daemon cleanup aborted: the existing daemon could not be confirmed stopped'
-      )
-    }
-  } finally {
-    client.disconnect()
-  }
-
-  if (didRequestShutdown && protocolVersion >= CLEAN_DISCONNECT_PROTOCOL_VERSION) {
-    if (!(await waitForDaemonEndpointExit(socketPath))) {
-      // Never fork a replacement while the old incarnation may still own the endpoint or be disposing terminal children.
-      throw new Error('Timed out waiting for daemon self-shutdown')
-    }
-    return { cleaned: true, killedCount }
-  }
-
-  try {
-    unlinkSync(pidPath)
-  } catch {
-    // Best-effort
-  }
-
-  return { cleaned: didRequestShutdown || didKillStaleDaemon, killedCount }
-}
-
-async function waitForDaemonEndpointExit(socketPath: string): Promise<boolean> {
-  const deadline = Date.now() + DAEMON_SELF_SHUTDOWN_WAIT_MS
-  while (Date.now() < deadline) {
-    if (!(await probeSocket(socketPath))) {
-      return true
-    }
-    await new Promise((resolve) => setTimeout(resolve, 50))
-  }
-  return !(await probeSocket(socketPath))
-}
-
-function legacyDaemonProcessMayBeAlive(runtimeDir: string, protocolVersion: number): boolean {
-  try {
-    const parsed = parseDaemonPidFile(
-      readFileSync(getDaemonPidPath(runtimeDir, protocolVersion), 'utf8')
-    )
-    if (!parsed) {
-      return false
-    }
-    process.kill(parsed.pid, 0)
-    return true
-  } catch {
-    return false
-  }
-}
-
-// Why: callers that own an isolated runtime namespace must keep discovery history out of app userData.
-export async function createLegacyDaemonAdapters(
-  runtimeDir: string,
-  historyPath = getHistoryDir()
-): Promise<DaemonPtyAdapter[]> {
-  const adapters: DaemonPtyAdapter[] = []
-  for (const protocolVersion of PREVIOUS_DAEMON_PROTOCOL_VERSIONS) {
-    const socketPath = getDaemonSocketPath(runtimeDir, protocolVersion)
-    const tokenPath = getDaemonTokenPath(runtimeDir, protocolVersion)
-    if (!(await probeSocket(socketPath))) {
-      // Why: a recycled stale pid later turns an identity check into a PowerShell spawn, so delete leaked pid/token files — but only when the pid-process is provably gone (a live daemon can transiently fail the probe, and dropping its token makes its sessions permanently unadoptable).
-      if (!legacyDaemonProcessMayBeAlive(runtimeDir, protocolVersion)) {
-        for (const stalePath of [
-          getDaemonPidPath(runtimeDir, protocolVersion),
-          getDaemonTokenPath(runtimeDir, protocolVersion)
-        ]) {
-          try {
-            unlinkSync(stalePath)
-          } catch {
-            // Best-effort
-          }
-        }
-      }
-      continue
-    }
-    // Keep old-protocol PTYs routed to their original daemon during upgrade; legacy adapters never respawn (new code would recreate stale env semantics).
-    // historyPath is still needed for cleanup — without it a later v4 session reusing the same ID could false-restore stale scrollback.bin.
-    adapters.push(
-      new DaemonPtyAdapter({
-        socketPath,
-        tokenPath,
-        pidPath: getDaemonPidPath(runtimeDir, protocolVersion),
-        profileScope: runtimeDir,
-        runtimeDir,
-        protocolVersion,
-        historyPath
-      })
-    )
-  }
-  return adapters
-}
+export { createLegacyDaemonAdapters } from './daemon-legacy-adapters'
+export { initDaemonPtyProvider } from './daemon-provider-init'
+export { restartDaemon, type RestartDaemonResult } from './daemon-provider-restart'
+export {
+  daemonOwnsFreshPersistentPtys,
+  disconnectDaemon,
+  getCurrentDaemonMacTccAttributionHealth,
+  getDaemonEndpointFacts,
+  getDaemonProvider,
+  listLiveDaemonPtyIds,
+  readDaemonPidRecord,
+  replaceDaemonProvider,
+  shutdownDaemon,
+  type DaemonEndpointFacts
+} from './daemon-provider-state'
+export {
+  cleanupDaemonForProtocol,
+  type OrphanedDaemonCleanupResult
+} from './daemon-protocol-cleanup'
+export { WEDGED_DAEMON_GRACE_RETRIES } from './daemon-replacement-preflight'
diff --git a/src/main/daemon/daemon-launched-child.ts b/src/main/daemon/daemon-launched-child.ts
new file mode 100644
index 00000000000..f9f245897f6
--- /dev/null
+++ b/src/main/daemon/daemon-launched-child.ts
@@ -0,0 +1,295 @@
+import { fork, type ChildProcess } from 'node:child_process'
+import { getAppEnvironment } from '../../shared/app-environment'
+import { DAEMON_EXIT_ENDPOINT_OCCUPIED } from './daemon-endpoint-ownership'
+import type { DaemonEndpointIdentity } from './daemon-hello-protocol'
+import { daemonLogArgs } from './daemon-launch-paths'
+import { parseDaemonReadyIdentity } from './daemon-ready-identity'
+import { unlinkOwnedDaemonPidFile } from './daemon-spawner'
+
+const DAEMON_CHILD_TERMINATION_GRACE_MS = 5_000
+const DAEMON_CHILD_FORCE_EXIT_WAIT_MS = 1_000
+const STARTUP_STDERR_MAX_BYTES = 8192
+
+export class DaemonEndpointUnavailableError extends Error {
+  constructor(
+    readonly reason: string,
+    options?: ErrorOptions
+  ) {
+    super(`Daemon could not take the endpoint: ${reason}`, options)
+  }
+}
+
+export type LaunchedDaemonChild = {
+  child: ChildProcess
+  identity: DaemonEndpointIdentity
+}
+
+type LaunchDaemonChildOptions = {
+  entryPath: string
+  forkEntryPath: string
+  relocatedExecPath?: string
+  userDataPath: string
+  socketPath: string
+  tokenPath: string
+  pidPath: string
+  launchNonce: string
+  macosLoginSessionWatch: boolean
+}
+
+export async function launchDaemonChild(
+  options: LaunchDaemonChildOptions
+): Promise<LaunchedDaemonChild> {
+  const {
+    entryPath,
+    forkEntryPath,
+    relocatedExecPath,
+    userDataPath,
+    socketPath,
+    tokenPath,
+    pidPath,
+    launchNonce,
+    macosLoginSessionWatch
+  } = options
+  const child = fork(
+    forkEntryPath,
+    [
+      '--socket',
+      socketPath,
+      '--token',
+      tokenPath,
+      '--pid-record',
+      pidPath,
+      '--launch-nonce',
+      launchNonce,
+      '--entry-path',
+      entryPath,
+      '--app-version',
+      getAppEnvironment().getVersion(),
+      '--spawner-exec-path',
+      process.execPath,
+      ...(macosLoginSessionWatch ? ['--login-session-watch'] : []),
+      ...daemonLogArgs()
+    ],
+    {
+      // Why: detached daemons outlive dev worktrees; userData keeps process.cwd() valid after a repo/worktree is deleted.
+      cwd: userDataPath,
+      // Why: detached+unref outlives Electron; stdout 'ignore' (else blocks exit), stderr 'pipe' captures startup crashes lost in v1.4.129-rc.1.
+      detached: true,
+      stdio: ['ignore', 'ignore', 'pipe', 'ipc'],
+      // Why: run the byte-identical relocated Orca.exe so the image path sits outside the updater's kill zone.
+      ...(relocatedExecPath ? { execPath: relocatedExecPath } : {}),
+      // Why: run the fork as plain Node so Electron's GPU/display init can't interfere with node-pty's posix_spawn of the spawn-helper.
+      env: {
+        ...process.env,
+        ELECTRON_RUN_AS_NODE: '1',
+        // Why: the detached plain-Node daemon has no AppEnvironment, but shell rcfiles must live outside swept tmp.
+        ORCA_USER_DATA_PATH: userDataPath
+      }
+    }
+  )
+
+  // Why: keep only the startup-window stderr tail so a crash cause is visible without unbounded memory.
+  let startupStderr = ''
+  let collectingStderr = true
+  const onStartupStderr = (chunk: Buffer): void => {
+    if (!collectingStderr) {
+      return
+    }
+    startupStderr += chunk.toString('utf8')
+    if (startupStderr.length > STARTUP_STDERR_MAX_BYTES) {
+      startupStderr = startupStderr.slice(-STARTUP_STDERR_MAX_BYTES)
+    }
+  }
+  child.stderr?.on('data', onStartupStderr)
+  // Why: release the detached daemon's stderr once up/failed — a live piped stream refs the parent loop and blocks Electron exit.
+  const releaseStderr = (): void => {
+    collectingStderr = false
+    child.stderr?.off('data', onStartupStderr)
+    child.stderr?.destroy()
+  }
+
+  // Wait for the daemon to signal readiness via IPC
+  let launchedIdentity: DaemonEndpointIdentity | null = null
+  let endpointUnavailableReason: string | null = null
+  const startupSignal = new Promise<void>((resolve, reject) => {
+    let timer: ReturnType<typeof setTimeout> | undefined
+    let settled = false
+    function cleanupStartupListeners(): void {
+      if (timer) {
+        clearTimeout(timer)
+      }
+      child.off('message', onReadyMessage)
+      child.off('error', onStartupError)
+      child.off('exit', onStartupExit)
+    }
+    async function fail(error: Error): Promise<void> {
+      if (settled) {
+        return
+      }
+      settled = true
+      cleanupStartupListeners()
+      // Why: attach the captured stderr tail to the thrown error and log it so a startup crash isn't just "exited with code 1".
+      const stderrTail = startupStderr.trim()
+      if (stderrTail) {
+        console.warn(`[daemon] startup failed; captured stderr tail:\n${stderrTail}`)
+      }
+      releaseStderr()
+      const startupError = stderrTail
+        ? new Error(`${error.message}\nDaemon stderr (tail):\n${stderrTail}`)
+        : error
+      try {
+        await terminateLaunchedDaemonChild(child)
+      } catch (cleanupError) {
+        reject(
+          new AggregateError(
+            [startupError, cleanupError],
+            'Daemon startup and child cleanup both failed'
+          )
+        )
+        return
+      }
+      if (Number.isSafeInteger(child.pid) && (child.pid as number) > 0) {
+        unlinkOwnedDaemonPidFile(pidPath, child.pid as number, launchNonce)
+      }
+      reject(startupError)
+    }
+    function onReadyMessage(msg: unknown): void {
+      if (
+        msg &&
+        typeof msg === 'object' &&
+        (msg as { type?: string }).type === 'endpoint-unavailable'
+      ) {
+        // Why: the child lost the endpoint race rather than crashing. Record it so the
+        // launcher can adopt the winner instead of reporting a generic startup failure.
+        endpointUnavailableReason = (msg as { reason?: string }).reason ?? 'occupied'
+        void fail(new Error(`Daemon could not take the endpoint: ${endpointUnavailableReason}`))
+        return
+      }
+      if (msg && typeof msg === 'object' && (msg as { type?: string }).type === 'ready') {
+        if (settled) {
+          return
+        }
+        const readyIdentity = parseDaemonReadyIdentity(msg)
+        if (!Number.isSafeInteger(child.pid) || (child.pid as number) <= 0 || !readyIdentity) {
+          void fail(new Error('Daemon readiness identity is incomplete'))
+          return
+        }
+        launchedIdentity = {
+          pid: child.pid as number,
+          ...readyIdentity,
+          launchNonce
+        }
+        settled = true
+        // Why: daemon is detached after readiness; detach startup listeners so the launch promise closure isn't retained.
+        cleanupStartupListeners()
+        // Why: release IPC/stderr and unref so Electron can exit without waiting; the daemon keeps running detached.
+        releaseStderr()
+        child.disconnect()
+        child.unref()
+        resolve()
+      }
+    }
+
+    function onStartupError(err: Error): void {
+      void fail(err)
+    }
+
+    function onStartupExit(code: number | null): void {
+      if (code === DAEMON_EXIT_ENDPOINT_OCCUPIED) {
+        // Why here and not only on the IPC message: the exit is the event this wait settles
+        // on, so keying off it cannot lose to a notification still in the channel.
+        endpointUnavailableReason = 'occupied'
+      }
+      void fail(new Error(`Daemon exited during startup with code ${code}`))
+    }
+
+    timer = setTimeout(() => {
+      void fail(new Error('Daemon startup timed out'))
+    }, 10000)
+
+    child.on('message', onReadyMessage)
+    child.on('error', onStartupError)
+    child.on('exit', onStartupExit)
+  })
+
+  try {
+    await startupSignal
+  } catch (error) {
+    if (endpointUnavailableReason === 'occupied') {
+      throw new DaemonEndpointUnavailableError('occupied', { cause: error })
+    }
+    throw error
+  }
+  if (!launchedIdentity) {
+    throw new Error('Daemon readiness identity is incomplete')
+  }
+  return { child, identity: launchedIdentity }
+}
+
+export async function terminateLaunchedDaemonChild(child: ChildProcess): Promise<void> {
+  try {
+    if (
+      (child.exitCode !== null && child.exitCode !== undefined) ||
+      (child.signalCode !== null && child.signalCode !== undefined)
+    ) {
+      return
+    }
+    await new Promise<void>((resolve, reject) => {
+      let gracefulTimer: ReturnType<typeof setTimeout>
+      let forcedTimer: ReturnType<typeof setTimeout> | undefined
+      let settled = false
+      const finish = (error?: unknown): void => {
+        if (settled) {
+          return
+        }
+        settled = true
+        clearTimeout(gracefulTimer)
+        if (forcedTimer) {
+          clearTimeout(forcedTimer)
+        }
+        child.off('exit', onExit)
+        if (error) {
+          reject(error)
+        } else {
+          resolve()
+        }
+      }
+      const onExit = (): void => finish()
+      child.on('exit', onExit)
+      gracefulTimer = setTimeout(() => {
+        if (child.pid) {
+          try {
+            process.kill(child.pid, 'SIGKILL')
+          } catch (error) {
+            finish(isNoSuchProcessError(error) ? undefined : error)
+            return
+          }
+        }
+        if (!settled) {
+          forcedTimer = setTimeout(
+            () => finish(new Error('Daemon did not exit after SIGKILL')),
+            DAEMON_CHILD_FORCE_EXIT_WAIT_MS
+          )
+        }
+      }, DAEMON_CHILD_TERMINATION_GRACE_MS)
+      if (child.pid) {
+        try {
+          process.kill(child.pid, 'SIGTERM')
+        } catch (error) {
+          finish(isNoSuchProcessError(error) ? undefined : error)
+        }
+      } else {
+        finish()
+      }
+    })
+  } finally {
+    if (child.connected) {
+      child.disconnect()
+    }
+    child.unref()
+  }
+}
+
+function isNoSuchProcessError(error: unknown): boolean {
+  return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ESRCH'
+}
diff --git a/src/main/daemon/daemon-legacy-adapters.ts b/src/main/daemon/daemon-legacy-adapters.ts
new file mode 100644
index 00000000000..160ddd64c64
--- /dev/null
+++ b/src/main/daemon/daemon-legacy-adapters.ts
@@ -0,0 +1,66 @@
+import { readFileSync, unlinkSync } from 'node:fs'
+import {
+  getDaemonHistoryDir as getHistoryDir,
+  probeDaemonSocket as probeSocket
+} from './daemon-launch-paths'
+import { parseDaemonPidFile } from './daemon-pid-file-parse'
+import { DaemonPtyAdapter } from './daemon-pty-adapter'
+import { getDaemonPidPath, getDaemonSocketPath, getDaemonTokenPath } from './daemon-spawner'
+import { PREVIOUS_DAEMON_PROTOCOL_VERSIONS } from './types'
+
+function legacyDaemonProcessMayBeAlive(runtimeDir: string, protocolVersion: number): boolean {
+  try {
+    const parsed = parseDaemonPidFile(
+      readFileSync(getDaemonPidPath(runtimeDir, protocolVersion), 'utf8')
+    )
+    if (!parsed) {
+      return false
+    }
+    process.kill(parsed.pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+// Why: callers that own an isolated runtime namespace must keep discovery history out of app userData.
+export async function createLegacyDaemonAdapters(
+  runtimeDir: string,
+  historyPath = getHistoryDir()
+): Promise<DaemonPtyAdapter[]> {
+  const adapters: DaemonPtyAdapter[] = []
+  for (const protocolVersion of PREVIOUS_DAEMON_PROTOCOL_VERSIONS) {
+    const socketPath = getDaemonSocketPath(runtimeDir, protocolVersion)
+    const tokenPath = getDaemonTokenPath(runtimeDir, protocolVersion)
+    if (!(await probeSocket(socketPath))) {
+      // Why: a recycled stale pid later turns an identity check into a PowerShell spawn, so delete leaked pid/token files — but only when the pid-process is provably gone (a live daemon can transiently fail the probe, and dropping its token makes its sessions permanently unadoptable).
+      if (!legacyDaemonProcessMayBeAlive(runtimeDir, protocolVersion)) {
+        for (const stalePath of [
+          getDaemonPidPath(runtimeDir, protocolVersion),
+          getDaemonTokenPath(runtimeDir, protocolVersion)
+        ]) {
+          try {
+            unlinkSync(stalePath)
+          } catch {
+            // Best-effort
+          }
+        }
+      }
+      continue
+    }
+    // Keep old-protocol PTYs routed to their original daemon during upgrade; legacy adapters never respawn (new code would recreate stale env semantics).
+    // historyPath is still needed for cleanup — without it a later v4 session reusing the same ID could false-restore stale scrollback.bin.
+    adapters.push(
+      new DaemonPtyAdapter({
+        socketPath,
+        tokenPath,
+        pidPath: getDaemonPidPath(runtimeDir, protocolVersion),
+        profileScope: runtimeDir,
+        runtimeDir,
+        protocolVersion,
+        historyPath
+      })
+    )
+  }
+  return adapters
+}
diff --git a/src/main/daemon/daemon-out-of-process-launcher.ts b/src/main/daemon/daemon-out-of-process-launcher.ts
new file mode 100644
index 00000000000..e5b14aa8cb0
--- /dev/null
+++ b/src/main/daemon/daemon-out-of-process-launcher.ts
@@ -0,0 +1,209 @@
+import { randomUUID } from 'node:crypto'
+import { getAppEnvironment } from '../../shared/app-environment'
+import type { DaemonReplaceReason } from '../../shared/daemon-lifecycle-telemetry'
+import { DaemonClient } from './client'
+import {
+  DaemonEndpointOwnershipError,
+  holdDaemonAdoptionLease,
+  reconcileDaemonPidOwnership
+} from './daemon-endpoint-adoption'
+import {
+  DaemonEndpointUnavailableError,
+  launchDaemonChild,
+  terminateLaunchedDaemonChild
+} from './daemon-launched-child'
+import { getDaemonEntryPath, probeDaemonSocket as probeSocket } from './daemon-launch-paths'
+import { materializeRelocatedDaemonHost } from './daemon-host-relocation'
+import { cleanupDaemonForProtocol } from './daemon-protocol-cleanup'
+import {
+  getDaemonPidPath,
+  type DaemonLauncher,
+  type DaemonProcessHandle,
+  unlinkOwnedDaemonPidFile
+} from './daemon-spawner'
+import { PROTOCOL_VERSION } from './types'
+import { prepareDaemonReplacement } from './daemon-replacement-preflight'
+
+// Why: the adapter decides a runtime resolver replacement, but the launcher completes it — and by
+// then the daemon has usually self-retired (dropping its last authenticated client is enough), so
+// there is nothing left to kill and the launcher's own confirmed-kill gate would report nothing.
+// The adapter hands the reason across so the launch it triggers reports what actually drove it.
+let attributedReplaceReason: DaemonReplaceReason | null = null
+
+export function attributeNextDaemonReplacement(reason: DaemonReplaceReason): void {
+  attributedReplaceReason = reason
+}
+
+function createPreservedDaemonHandle(
+  runtimeDir: string,
+  protocolVersion = PROTOCOL_VERSION,
+  mode?: 'degraded-new-pty-fallback'
+): DaemonProcessHandle {
+  const handle: DaemonProcessHandle = {
+    shutdown: async () => {
+      await cleanupDaemonForProtocol(runtimeDir, protocolVersion)
+    }
+  }
+  if (mode) {
+    handle.mode = mode
+  }
+  return handle
+}
+
+export function createOutOfProcessLauncher(
+  runtimeDir: string,
+  macosLoginSessionWatch = false
+): DaemonLauncher {
+  return async (socketPath, tokenPath, suppliedPidPath, suppliedLaunchNonce) => {
+    const entryPath = getDaemonEntryPath()
+    const pidPath = suppliedPidPath ?? getDaemonPidPath(runtimeDir)
+    const launchNonce = suppliedLaunchNonce ?? randomUUID()
+    // One-shot: whichever launch consumes it owns the attribution, so a later unrelated launch can't
+    // reuse it. The write in the respawn closure reaches here without an intervening await, which is
+    // what makes a bare module-scoped slot safe — keep it that way or a concurrent launch can steal it.
+    const attributedReason = attributedReplaceReason
+    attributedReplaceReason = null
+    let adoptionClient: DaemonClient | null = new DaemonClient({
+      socketPath,
+      tokenPath
+    })
+    try {
+      // Why: acquire the full pair before control-only probes so an expired inherited deadline can't fire in the probe-to-adoption gap.
+      await adoptionClient.ensureConnected()
+      await reconcileDaemonPidOwnership(adoptionClient, pidPath)
+    } catch {
+      adoptionClient.disconnect()
+      adoptionClient = null
+    }
+    const releaseAdoptionClient = (): void => {
+      adoptionClient?.disconnect()
+      adoptionClient = null
+    }
+    const preserveDaemon = async (
+      mode?: 'degraded-new-pty-fallback'
+    ): Promise<DaemonProcessHandle> => {
+      const connectedClient = adoptionClient ?? undefined
+      adoptionClient = null
+      return holdDaemonAdoptionLease(
+        createPreservedDaemonHandle(runtimeDir, PROTOCOL_VERSION, mode),
+        socketPath,
+        tokenPath,
+        connectedClient,
+        undefined,
+        pidPath
+      )
+    }
+    try {
+      const preservedHandle = await prepareDaemonReplacement({
+        runtimeDir,
+        socketPath,
+        tokenPath,
+        entryPath,
+        attributedReason,
+        releaseAdoptionClient,
+        preserveDaemon
+      })
+      if (preservedHandle) {
+        return preservedHandle
+      }
+
+      const userDataPath = getAppEnvironment().getPath('userData')
+      // Why: on win32 packaged, stage a daemon-host copy in userData so its image escapes the NSIS updater's kill zone; lazy so it's off first-paint. Fail-open: null → in-dir host.
+      const relocatedHost = materializeRelocatedDaemonHost()
+      // Fork the relocated entry when available; otherwise the install-dir entry.
+      const forkEntryPath = relocatedHost ? relocatedHost.entryPath : entryPath
+      let launched
+      try {
+        launched = await launchDaemonChild({
+          entryPath,
+          forkEntryPath,
+          relocatedExecPath: relocatedHost?.execPath,
+          userDataPath,
+          socketPath,
+          tokenPath,
+          pidPath,
+          launchNonce,
+          macosLoginSessionWatch
+        })
+      } catch (error) {
+        if (!(error instanceof DaemonEndpointUnavailableError) || error.reason !== 'occupied') {
+          throw error
+        }
+        // Why adopt rather than retry: another daemon proved it owns the endpoint and is
+        // answering on it. Forking again would lose the same race, and reporting a startup
+        // failure strands this app on local non-persistent PTYs beside a healthy daemon.
+        console.warn(
+          '[daemon] Endpoint was taken by another daemon during startup — adopting it instead'
+        )
+        // Why pidPath: adopting reconciles the PID record against the identity the daemon
+        // reports over hello, repairing a record that names the wrong incarnation. Every other
+        // adoption path passes it; this one skipped it, so the incumbent we adopt here was the
+        // only one whose record never got that repair.
+        return await holdDaemonAdoptionLease(
+          createPreservedDaemonHandle(runtimeDir),
+          socketPath,
+          tokenPath,
+          undefined,
+          undefined,
+          pidPath
+        )
+      }
+
+      try {
+        return await holdDaemonAdoptionLease(
+          {
+            shutdown: () => terminateLaunchedDaemonChild(launched.child)
+          },
+          socketPath,
+          tokenPath,
+          undefined,
+          launched.identity,
+          pidPath
+        )
+      } catch (error) {
+        if (error instanceof DaemonEndpointOwnershipError) {
+          await terminateLaunchedDaemonChild(launched.child)
+          unlinkOwnedDaemonPidFile(pidPath, launched.child.pid as number, launchNonce)
+          throw error
+        }
+        // Why: another client may have adopted this live process; keep its pid record until exit, but remove one published after an early exit.
+        let pidRecordRemoved = false
+        const removeExitedPidRecord = (): void => {
+          if (pidRecordRemoved) {
+            return
+          }
+          pidRecordRemoved = true
+          unlinkOwnedDaemonPidFile(pidPath, launched.child.pid as number, launchNonce)
+        }
+        launched.child.once('exit', removeExitedPidRecord)
+        if (
+          (launched.child.exitCode !== null && launched.child.exitCode !== undefined) ||
+          (launched.child.signalCode !== null && launched.child.signalCode !== undefined)
+        ) {
+          launched.child.off('exit', removeExitedPidRecord)
+          removeExitedPidRecord()
+        }
+        throw error
+      }
+    } catch (error) {
+      releaseAdoptionClient()
+      // Why: the launcher may now fork onto an endpoint it could not classify, because the
+      // publisher is the real guard — and that guard works by refusing to overwrite what it
+      // cannot prove dead, so the child exits instead of splitting the brain. Correct, but
+      // giving up here costs the user every persistent session for the whole run. Something
+      // answering the endpoint now is a daemon worth adopting, not a reason to fall back to
+      // local PTYs.
+      if (await probeSocket(socketPath)) {
+        console.warn(
+          '[daemon] DEGRADED MODE: adopting the daemon that owns the endpoint after a replacement could not publish onto it. Existing sessions keep working; fresh terminals run on the local provider WITHOUT daemon persistence until you restart the daemon (Manage Sessions → Restart).'
+        )
+        try {
+          return await preserveDaemon('degraded-new-pty-fallback')
+        } catch {
+          // It stopped answering between the probe and the adoption; report the launch failure.
+        }
+      }
+      throw error
+    }
+  }
+}
diff --git a/src/main/daemon/daemon-protocol-cleanup.ts b/src/main/daemon/daemon-protocol-cleanup.ts
new file mode 100644
index 00000000000..69808ac5716
--- /dev/null
+++ b/src/main/daemon/daemon-protocol-cleanup.ts
@@ -0,0 +1,98 @@
+import { unlinkSync } from 'node:fs'
+import { DaemonClient } from './client'
+import { DaemonEndpointOwnershipError } from './daemon-endpoint-adoption'
+import { probeDaemonSocket as probeSocket } from './daemon-launch-paths'
+import { getDaemonPidPath, getDaemonSocketPath, getDaemonTokenPath } from './daemon-spawner'
+import { killStaleDaemon } from './daemon-stale-kill'
+import { CLEAN_DISCONNECT_PROTOCOL_VERSION, type ListSessionsResult } from './types'
+
+const DAEMON_SELF_SHUTDOWN_WAIT_MS = 5_000
+
+export type OrphanedDaemonCleanupResult = {
+  /** True when a live daemon socket was found and torn down; false when none was running. */
+  cleaned: boolean
+  /** Number of live PTY sessions killed during cleanup (surfaced to the user). */
+  killedCount: number
+}
+
+export async function cleanupDaemonForProtocol(
+  runtimeDir: string,
+  protocolVersion: number
+): Promise<OrphanedDaemonCleanupResult> {
+  const socketPath = getDaemonSocketPath(runtimeDir, protocolVersion)
+  const tokenPath = getDaemonTokenPath(runtimeDir, protocolVersion)
+  const pidPath = getDaemonPidPath(runtimeDir, protocolVersion)
+
+  const alive = await probeSocket(socketPath)
+  if (!alive) {
+    if (protocolVersion >= CLEAN_DISCONNECT_PROTOCOL_VERSION) {
+      // Endpoint absence doesn't prove the PID record belongs to the current protocol; leave artifact cleanup to the owning daemon.
+      return { cleaned: false, killedCount: 0 }
+    }
+    try {
+      unlinkSync(pidPath)
+    } catch {
+      // Best-effort
+    }
+    return { cleaned: false, killedCount: 0 }
+  }
+
+  const client = new DaemonClient({ socketPath, tokenPath, protocolVersion })
+  let killedCount = 0
+  let didRequestShutdown = false
+  let didKillStaleDaemon = false
+  try {
+    await client.ensureConnected()
+    const sessions = await client
+      .request<ListSessionsResult>('listSessions', undefined)
+      .catch(() => ({ sessions: [] }))
+    killedCount = sessions.sessions.filter((s) => s.isAlive).length
+
+    // Use the single-shot `shutdown` RPC (kills all sessions then exits) to avoid racing per-session `kill` calls against the daemon exiting.
+    await client.request('shutdown', { killSessions: true }).catch(() => {
+      // Daemon exits immediately after the RPC, so the socket may close before the reply arrives; treat as success.
+    })
+    didRequestShutdown = true
+  } catch {
+    // Previous-protocol daemons may be wedged or too old for the RPC path; fall back to PID cleanup (only unlinks a live socket after proving the process is killed).
+    const killOutcome = await killStaleDaemon(runtimeDir, socketPath, tokenPath, protocolVersion)
+    didKillStaleDaemon = killOutcome.killed
+    if (killOutcome.liveOwnerSurvived) {
+      // Why: something still owns the endpoint. Returning as if it were cleaned lets restart
+      // fork a replacement that cannot publish onto the held name, leaving the user with no
+      // daemon instead of the one still running.
+      throw new DaemonEndpointOwnershipError(
+        'Daemon cleanup aborted: the existing daemon could not be confirmed stopped'
+      )
+    }
+  } finally {
+    client.disconnect()
+  }
+
+  if (didRequestShutdown && protocolVersion >= CLEAN_DISCONNECT_PROTOCOL_VERSION) {
+    if (!(await waitForDaemonEndpointExit(socketPath))) {
+      // Never fork a replacement while the old incarnation may still own the endpoint or be disposing terminal children.
+      throw new Error('Timed out waiting for daemon self-shutdown')
+    }
+    return { cleaned: true, killedCount }
+  }
+
+  try {
+    unlinkSync(pidPath)
+  } catch {
+    // Best-effort
+  }
+
+  return { cleaned: didRequestShutdown || didKillStaleDaemon, killedCount }
+}
+
+async function waitForDaemonEndpointExit(socketPath: string): Promise<boolean> {
+  const deadline = Date.now() + DAEMON_SELF_SHUTDOWN_WAIT_MS
+  while (Date.now() < deadline) {
+    if (!(await probeSocket(socketPath))) {
+      return true
+    }
+    await new Promise((resolve) => setTimeout(resolve, 50))
+  }
+  return !(await probeSocket(socketPath))
+}
diff --git a/src/main/daemon/daemon-provider-init.ts b/src/main/daemon/daemon-provider-init.ts
new file mode 100644
index 00000000000..1881e276e97
--- /dev/null
+++ b/src/main/daemon/daemon-provider-init.ts
@@ -0,0 +1,186 @@
+import { getLocalPtyProvider, rebindLocalProviderListeners } from '../ipc/pty'
+import {
+  confirmSeededClaudeLivePtys,
+  hasSeededUnconfirmedClaudePtys
+} from '../claude-accounts/live-pty-gate'
+import { isStartupDiagnosticsEnabled, logStartupDiagnostic } from '../startup/startup-diagnostics'
+import { checkDaemonHealth } from './daemon-health'
+import { collectPinnedDaemonVersions, pruneOldDaemonHosts } from './daemon-host-relocation'
+import {
+  cleanupFailedDaemonAdoption,
+  releaseDaemonAdoptionLease,
+  takeDaemonAdoptionLeaseRelease
+} from './daemon-endpoint-adoption'
+import { createLegacyDaemonAdapters } from './daemon-legacy-adapters'
+import {
+  getDaemonHistoryDir as getHistoryDir,
+  getDaemonRuntimeDir as getRuntimeDir,
+  resolvePackagedDarwinAppVersion
+} from './daemon-launch-paths'
+import {
+  attributeNextDaemonReplacement,
+  createOutOfProcessLauncher
+} from './daemon-out-of-process-launcher'
+import type { DaemonProvider } from './daemon-provider-routing'
+import { installDaemonProvider } from './daemon-provider-state'
+import { DegradedDaemonPtyProvider } from './degraded-daemon-pty-provider'
+import { trackDaemonRetired } from './daemon-lifecycle-event'
+import { DaemonPtyAdapter } from './daemon-pty-adapter'
+import type { DaemonRespawnReason } from './daemon-pty-runtime-state'
+import { DaemonPtyRouter } from './daemon-pty-router'
+import { isDaemonRestartInFlight } from './daemon-restart-state'
+import { DaemonSpawner, getDaemonPidPath } from './daemon-spawner'
+
+// Why: daemon init runs concurrent with window load, so an in-process t timestamp (not harness stderr timing) measures cold-start.
+function logDaemonMilestone(event: string, details: Record<string, unknown> = {}): void {
+  if (isStartupDiagnosticsEnabled()) {
+    logStartupDiagnostic(event, {
+      t: Math.round(performance.now()),
+      ...details
+    })
+  }
+}
+
+export async function initDaemonPtyProvider(
+  signal?: AbortSignal,
+  options: { macosLoginSessionWatch?: boolean } = {}
+): Promise<void> {
+  logDaemonMilestone('daemon-init-start')
+  // Why: e2e coverage for the startup PTY gate (#5232) needs a daemon init that deterministically outlasts the first-window timeout.
+  const e2eInitDelayMs = Number(process.env.ORCA_E2E_DAEMON_INIT_DELAY_MS)
+  if (Number.isFinite(e2eInitDelayMs) && e2eInitDelayMs > 0) {
+    await new Promise((resolve) => setTimeout(resolve, e2eInitDelayMs))
+  }
+  const runtimeDir = getRuntimeDir()
+
+  const newSpawner = new DaemonSpawner({
+    runtimeDir,
+    launcher: createOutOfProcessLauncher(runtimeDir, options.macosLoginSessionWatch ?? false)
+  })
+
+  // Why: assign the module-level spawner/adapter only after both succeed, so a failed ensureRunning() leaves no stale spawner.
+  const info = await newSpawner.ensureRunning()
+  // Why: reclaim superseded daemon-host copies on EVERY launch (spawns are rare), keeping current + live-daemon-pinned versions.
+  pruneOldDaemonHosts(collectPinnedDaemonVersions(runtimeDir))
+  const launchMode = newSpawner.getHandle()?.mode
+  logDaemonMilestone('daemon-current-ready')
+  if (signal?.aborted) {
+    // Why: fail-open may already have spawned fallback PTYs; don't install late, but retire an empty daemon (live sessions reject it and survive).
+    const abortedStartupAdapter = new DaemonPtyAdapter({
+      socketPath: info.socketPath,
+      tokenPath: info.tokenPath,
+      pidPath: getDaemonPidPath(runtimeDir),
+      profileScope: runtimeDir,
+      runtimeDir
+    })
+    releaseDaemonAdoptionLease(newSpawner.getHandle())
+    await abortedStartupAdapter.disconnectOnly()
+    return
+  }
+
+  const newAdapter = new DaemonPtyAdapter({
+    socketPath: info.socketPath,
+    tokenPath: info.tokenPath,
+    pidPath: getDaemonPidPath(runtimeDir),
+    profileScope: runtimeDir,
+    runtimeDir,
+    packagedAppVersion: resolvePackagedDarwinAppVersion(),
+    historyPath: getHistoryDir(),
+    // Why: on daemon death, ensureConnected() detects the dead socket and calls this to fork a replacement before retrying.
+    respawn: async (reason: DaemonRespawnReason) => {
+      // Why: attribute rather than emit — the launcher below is the one that completes the
+      // replacement, and emitting here would fire before the outcome is known.
+      // Caveat: a wedged-but-alive daemon (#8689) can still report died_respawn here and
+      // failed_health_check from the launcher — the app cannot tell wedged from dead at this point.
+      if (reason === 'daemon_died') {
+        console.warn('[daemon] Daemon process died — respawning')
+        // Why: a manual restart tears the daemon down under a still-live adapter, so a pane
+        // respawning on its synthetic exit would bill a user action to the crash bucket.
+        if (!isDaemonRestartInFlight()) {
+          trackDaemonRetired('died_respawn')
+        }
+      } else {
+        // Must reach the launcher below without an await in between; see the consume site.
+        attributeNextDaemonReplacement(reason)
+      }
+      newSpawner.resetHandle()
+      await newSpawner.ensureRunning()
+      return takeDaemonAdoptionLeaseRelease(newSpawner.getHandle())
+    }
+  })
+  let legacyAdapters: DaemonPtyAdapter[] = []
+  let routedAdapter: DaemonProvider = newAdapter
+  try {
+    // Why: the launcher's temporary pair closes only after this permanent pair is established, leaving no adoption gap.
+    await newAdapter.establishLifecycleLease()
+    releaseDaemonAdoptionLease(newSpawner.getHandle())
+
+    legacyAdapters = await createLegacyDaemonAdapters(runtimeDir)
+    routedAdapter =
+      launchMode === 'degraded-new-pty-fallback'
+        ? new DegradedDaemonPtyProvider({
+            current: newAdapter,
+            legacy: legacyAdapters,
+            fallback: getLocalPtyProvider(),
+            probeCurrentDaemonSpawn: async () =>
+              (await checkDaemonHealth(info.socketPath, info.tokenPath)) === 'healthy'
+          })
+        : legacyAdapters.length > 0
+          ? new DaemonPtyRouter({
+              current: newAdapter,
+              legacy: legacyAdapters
+            })
+          : newAdapter
+    if (routedAdapter instanceof DegradedDaemonPtyProvider) {
+      // Why: preserved daemon can't create fresh terminals; discover its live session ids so only they route to it (fresh panes fall back locally).
+      await routedAdapter.discoverDaemonSessions()
+    } else if (routedAdapter instanceof DaemonPtyRouter) {
+      await routedAdapter.discoverLegacySessions()
+    }
+    if (signal?.aborted) {
+      // Why: same late-swap guard after legacy discovery; release uninstalled adapter leases without killing live sessions.
+      await routedAdapter.disconnectOnly()
+      return
+    }
+  } catch (error) {
+    try {
+      await cleanupFailedDaemonAdoption(newSpawner, newAdapter, legacyAdapters)
+    } catch (cleanupError) {
+      throw new AggregateError([error, cleanupError], 'Daemon adoption and cleanup both failed')
+    }
+    throw error
+  }
+  installDaemonProvider(newSpawner, routedAdapter)
+  // Why: the first window may register PTY listeners before daemon init finishes; rebind so daemon PTYs still fan out events.
+  rebindLocalProviderListeners()
+  logDaemonMilestone('daemon-init-done', {
+    legacyAdapters: legacyAdapters.length
+  })
+  await reconcileSeededClaudeLivePtys(routedAdapter)
+}
+
+// Why: release gate ids only for daemon-confirmed-dead sessions; keep seeds on listing failure since releasing early can rotate a live CLI's refresh token.
+async function reconcileSeededClaudeLivePtys(provider: DaemonProvider): Promise<void> {
+  if (!hasSeededUnconfirmedClaudePtys()) {
+    return
+  }
+  try {
+    const adapters =
+      provider instanceof DaemonPtyRouter || provider instanceof DegradedDaemonPtyProvider
+        ? provider.getAllAdapters()
+        : [provider]
+    const results = await Promise.allSettled(adapters.map((entry) => entry.listSessions()))
+    if (results.some((result) => result.status === 'rejected')) {
+      console.warn('[daemon] Keeping seeded Claude live-PTY gate — session listing failed')
+      return
+    }
+    confirmSeededClaudeLivePtys(
+      results.flatMap((result) =>
+        result.status === 'fulfilled' ? result.value.map((session) => session.sessionId) : []
+      )
+    )
+  } catch (error) {
+    // Why: gate bookkeeping must never fail daemon init; stale seeds only defer a usage refresh until next restart.
+    console.warn('[daemon] Failed to reconcile seeded Claude live-PTY gate:', error)
+  }
+}
diff --git a/src/main/daemon/daemon-provider-restart.ts b/src/main/daemon/daemon-provider-restart.ts
new file mode 100644
index 00000000000..7cc2ffa7fd1
--- /dev/null
+++ b/src/main/daemon/daemon-provider-restart.ts
@@ -0,0 +1,161 @@
+import { rebindLocalProviderListeners, unbindLocalProviderListeners } from '../ipc/pty'
+import { DegradedDaemonPtyProvider } from './degraded-daemon-pty-provider'
+import {
+  cleanupFailedDaemonAdoption,
+  releaseDaemonAdoptionLease,
+  takeDaemonAdoptionLeaseRelease
+} from './daemon-endpoint-adoption'
+import {
+  getDaemonHistoryDir as getHistoryDir,
+  getDaemonRuntimeDir as getRuntimeDir,
+  resolvePackagedDarwinAppVersion
+} from './daemon-launch-paths'
+import { trackDaemonRetired } from './daemon-lifecycle-event'
+import { attributeNextDaemonReplacement } from './daemon-out-of-process-launcher'
+import {
+  disposeProviderSubscriptionsOnly,
+  getCurrentDaemonAdapter,
+  getLegacyDaemonAdapters,
+  type DaemonProvider
+} from './daemon-provider-routing'
+import { getDaemonProvider, getDaemonSpawner, replaceDaemonProvider } from './daemon-provider-state'
+import { DaemonPtyAdapter } from './daemon-pty-adapter'
+import type { DaemonRespawnReason } from './daemon-pty-runtime-state'
+import { DaemonPtyRouter } from './daemon-pty-router'
+import { cleanupDaemonForProtocol } from './daemon-protocol-cleanup'
+import {
+  isDaemonRestartInFlight,
+  runCoalescedDaemonRestart,
+  type RestartDaemonResult
+} from './daemon-restart-state'
+import { getDaemonPidPath, type DaemonSpawner } from './daemon-spawner'
+import { PROTOCOL_VERSION } from './types'
+
+export type { RestartDaemonResult } from './daemon-restart-state'
+
+// Why: the 7-step restart sequence from docs/daemon-staleness-ux.md §Phase 1; current-protocol only (legacy adapters preserved).
+export async function restartDaemon(): Promise<RestartDaemonResult> {
+  return runCoalescedDaemonRestart(runRestartDaemon)
+}
+
+async function runRestartDaemon(): Promise<RestartDaemonResult> {
+  const currentSpawner = getDaemonSpawner()
+  const currentAdapter = getDaemonProvider()
+  if (!currentSpawner || !currentAdapter) {
+    throw new Error('restartDaemon called before initDaemonPtyProvider')
+  }
+
+  const runtimeDir = getRuntimeDir()
+  // An operator asking for a restart is the deliberate "try again" that clears crash-loop
+  // containment; without this a wedged host could never be recovered from the UI.
+  currentSpawner.resetRespawnWindow()
+  const currentOnly = getCurrentDaemonAdapter(currentAdapter)
+  const legacyAdapters = getLegacyDaemonAdapters(currentAdapter)
+
+  // Step 1: synthesize pty:exit for every active session BEFORE teardown — the daemon's shutdown path never fans onExit to clients (session.ts:246-252), so the renderer would otherwise never see exits.
+  const fallbackKilledCount =
+    currentAdapter instanceof DegradedDaemonPtyProvider
+      ? await currentAdapter.shutdownFallbackSessions()
+      : 0
+  const currentDaemonSessionIds =
+    currentAdapter instanceof DegradedDaemonPtyProvider
+      ? currentAdapter.getCurrentDaemonSessionIds()
+      : []
+  const killedCount =
+    new Set([...currentOnly.getActiveSessionIds(), ...currentDaemonSessionIds]).size +
+    fallbackKilledCount
+  currentOnly.fanoutSyntheticExits(-1)
+  if (currentAdapter instanceof DegradedDaemonPtyProvider) {
+    currentAdapter.fanoutCurrentDaemonSyntheticExits(-1)
+  }
+
+  // Step 2: detach renderer listeners — after step 1 (so synthesized exits land) and before step 6 (no stale binding).
+  unbindLocalProviderListeners()
+
+  // Step 3: kill the current-protocol daemon process; legacy adapters untouched.
+  let info: Awaited<ReturnType<DaemonSpawner['ensureRunning']>>
+  try {
+    await cleanupDaemonForProtocol(runtimeDir, PROTOCOL_VERSION)
+
+    // Step 4: reuse the existing spawner so the respawn closure baked into long-lived adapters stays valid (do NOT new one).
+    currentSpawner.resetHandle()
+    info = await currentSpawner.ensureRunning()
+  } catch (error) {
+    // Why: old provider stays authoritative until the final swap; rebind since relaunch failed after teardown.
+    rebindLocalProviderListeners()
+    throw error
+  }
+
+  // Step 5: build a fresh current adapter against the respawned daemon.
+  const newCurrent = new DaemonPtyAdapter({
+    socketPath: info.socketPath,
+    tokenPath: info.tokenPath,
+    pidPath: getDaemonPidPath(runtimeDir),
+    profileScope: runtimeDir,
+    runtimeDir,
+    packagedAppVersion: resolvePackagedDarwinAppVersion(),
+    historyPath: getHistoryDir(),
+    respawn: async (reason: DaemonRespawnReason) => {
+      // Why: attribute rather than emit — the launcher below is the one that completes the
+      // replacement, and emitting here would fire before the outcome is known.
+      // Caveat: a wedged-but-alive daemon (#8689) can still report died_respawn here and
+      // failed_health_check from the launcher — the app cannot tell wedged from dead at this point.
+      if (reason === 'daemon_died') {
+        console.warn('[daemon] Daemon process died — respawning')
+        // Why: a manual restart tears the daemon down under a still-live adapter, so a pane
+        // respawning on its synthetic exit would bill a user action to the crash bucket.
+        if (!isDaemonRestartInFlight()) {
+          trackDaemonRetired('died_respawn')
+        }
+      } else {
+        // Must reach the launcher below without an await in between; see the consume site.
+        attributeNextDaemonReplacement(reason)
+      }
+      currentSpawner.resetHandle()
+      await currentSpawner.ensureRunning()
+      return takeDaemonAdoptionLeaseRelease(currentSpawner.getHandle())
+    }
+  })
+  let newProvider: DaemonProvider = newCurrent
+  try {
+    // Temporary launcher lease overlaps this permanent pair so a manual restart can't strand a newly spawned daemon during adoption.
+    await newCurrent.establishLifecycleLease()
+    releaseDaemonAdoptionLease(currentSpawner.getHandle())
+
+    // Re-wrap in a router only if legacy adapters exist; they're preserved by reference and still route to their pre-upgrade daemons.
+    newProvider =
+      legacyAdapters.length > 0
+        ? new DaemonPtyRouter({ current: newCurrent, legacy: legacyAdapters })
+        : newCurrent
+    if (newProvider instanceof DaemonPtyRouter) {
+      await newProvider.discoverLegacySessions()
+    }
+  } catch (error) {
+    let cleanupError: unknown
+    try {
+      if (newProvider instanceof DaemonPtyRouter) {
+        newProvider.disposeRouterOnly()
+      }
+      await cleanupFailedDaemonAdoption(currentSpawner, newCurrent)
+    } catch (caught) {
+      cleanupError = caught
+    }
+    // Previous provider stays module-authoritative until the swap; restore its renderer bindings when adoption fails.
+    rebindLocalProviderListeners()
+    if (cleanupError) {
+      throw new AggregateError([error, cleanupError], 'Daemon restart and cleanup both failed')
+    }
+    throw error
+  }
+
+  // Drain the old router's subscriptions via the router-only variant (plain dispose() would tear down the shared legacy adapters), after the new provider exists (no unhandled events) and before the swap (atomic for the renderer).
+  disposeProviderSubscriptionsOnly(currentAdapter)
+
+  // Step 6: swap module state (adapter + localProvider) atomically.
+  replaceDaemonProvider(newProvider)
+
+  // Step 7: rebind renderer listeners against the new provider.
+  rebindLocalProviderListeners()
+
+  return { killedCount }
+}
diff --git a/src/main/daemon/daemon-provider-routing.ts b/src/main/daemon/daemon-provider-routing.ts
new file mode 100644
index 00000000000..0198bf2893c
--- /dev/null
+++ b/src/main/daemon/daemon-provider-routing.ts
@@ -0,0 +1,29 @@
+import { DegradedDaemonPtyProvider } from './degraded-daemon-pty-provider'
+import type { DaemonPtyAdapter } from './daemon-pty-adapter'
+import { DaemonPtyRouter } from './daemon-pty-router'
+
+export type DaemonProvider = DaemonPtyRouter | DaemonPtyAdapter | DegradedDaemonPtyProvider
+
+export function getCurrentDaemonAdapter(provider: DaemonProvider): DaemonPtyAdapter {
+  if (provider instanceof DaemonPtyRouter || provider instanceof DegradedDaemonPtyProvider) {
+    return provider.getCurrentAdapter()
+  }
+  return provider
+}
+
+export function getLegacyDaemonAdapters(provider: DaemonProvider): DaemonPtyAdapter[] {
+  if (provider instanceof DaemonPtyRouter || provider instanceof DegradedDaemonPtyProvider) {
+    return [...provider.getLegacyAdapters()]
+  }
+  return []
+}
+
+export function disposeProviderSubscriptionsOnly(provider: DaemonProvider): void {
+  if (provider instanceof DaemonPtyRouter) {
+    provider.disposeRouterOnly()
+    return
+  }
+  if (provider instanceof DegradedDaemonPtyProvider) {
+    provider.disposeProviderOnly()
+  }
+}
diff --git a/src/main/daemon/daemon-provider-state.ts b/src/main/daemon/daemon-provider-state.ts
new file mode 100644
index 00000000000..412dda3af83
--- /dev/null
+++ b/src/main/daemon/daemon-provider-state.ts
@@ -0,0 +1,137 @@
+import { readFileSync } from 'node:fs'
+import { setLocalPtyProvider } from '../ipc/pty'
+import { DegradedDaemonPtyProvider } from './degraded-daemon-pty-provider'
+import { getDaemonRuntimeDir as getRuntimeDir } from './daemon-launch-paths'
+import { parseDaemonPidFile, type ParsedDaemonPid } from './daemon-pid-file-parse'
+import type { DaemonProvider } from './daemon-provider-routing'
+import { DaemonPtyRouter } from './daemon-pty-router'
+import { getDaemonPidPath, getDaemonSocketPath, getDaemonTokenPath } from './daemon-spawner'
+import type { DaemonSpawner } from './daemon-spawner'
+import {
+  getMacDaemonTccAttributionHealth,
+  type MacDaemonTccAttributionHealth
+} from './daemon-tcc-attribution'
+import { PROTOCOL_VERSION } from './types'
+
+let spawner: DaemonSpawner | null = null
+let adapter: DaemonProvider | null = null
+
+export function installDaemonProvider(newSpawner: DaemonSpawner, newAdapter: DaemonProvider): void {
+  spawner = newSpawner
+  replaceDaemonProvider(newAdapter)
+}
+
+export function getDaemonSpawner(): DaemonSpawner | null {
+  return spawner
+}
+
+// Why: a narrow getter (not a raw export) keeps the "swap on restart" invariant in one place (replaceDaemonProvider).
+/**
+ * Whether the installed provider is a daemon that will own FRESH terminals too.
+ *
+ * Why not `getDaemonProvider() !== null`: DegradedDaemonPtyProvider routes the daemon's
+ * EXISTING sessions to the daemon but spawns new ones on the in-process local provider, so
+ * those die with this process. A host that answered "I can recover persistent local PTYs"
+ * from that state would be advertising recovery for terminals that cannot be recovered.
+ */
+export function daemonOwnsFreshPersistentPtys(): boolean {
+  return adapter !== null && !(adapter instanceof DegradedDaemonPtyProvider)
+}
+
+/** Endpoint coordinates of the daemon this process installed, for out-of-band health probes. */
+export type DaemonEndpointFacts = {
+  runtimeDir: string
+  socketPath: string
+  tokenPath: string
+  pidPath: string
+  protocolVersion: number
+}
+
+export function getDaemonEndpointFacts(): DaemonEndpointFacts | null {
+  if (!adapter) {
+    return null
+  }
+  const runtimeDir = getRuntimeDir()
+  return {
+    runtimeDir,
+    socketPath: getDaemonSocketPath(runtimeDir),
+    tokenPath: getDaemonTokenPath(runtimeDir),
+    pidPath: getDaemonPidPath(runtimeDir),
+    protocolVersion: PROTOCOL_VERSION
+  }
+}
+
+/**
+ * What the live daemon's own PID record says about the build it was forked from.
+ *
+ * Why the record and not this process's version: the daemon deliberately outlives the
+ * runtime, so after an update the two can legitimately disagree — and a health surface that
+ * reported orcad's version for both would hide exactly that.
+ */
+export function readDaemonPidRecord(): ParsedDaemonPid | null {
+  const facts = getDaemonEndpointFacts()
+  if (!facts) {
+    return null
+  }
+  try {
+    return parseDaemonPidFile(readFileSync(facts.pidPath, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+export function getDaemonProvider(): DaemonProvider | null {
+  return adapter
+}
+
+// Why: computed from the pid record on demand (not cached at adoption) so the Settings
+// remedy surface always reflects the daemon actually serving terminals right now.
+export async function getCurrentDaemonMacTccAttributionHealth(): Promise<MacDaemonTccAttributionHealth> {
+  const runtimeDir = getRuntimeDir()
+  return getMacDaemonTccAttributionHealth(
+    runtimeDir,
+    getDaemonSocketPath(runtimeDir),
+    getDaemonTokenPath(runtimeDir)
+  )
+}
+
+/** Returns null unless every daemon generation supplied an authoritative inventory. */
+export async function listLiveDaemonPtyIds(): Promise<string[] | null> {
+  if (!adapter) {
+    return null
+  }
+  const adapters =
+    adapter instanceof DaemonPtyRouter || adapter instanceof DegradedDaemonPtyProvider
+      ? adapter.getAllAdapters()
+      : [adapter]
+  const inventories = await Promise.allSettled(
+    adapters.map((daemonAdapter) => daemonAdapter.listProcesses())
+  )
+  if (inventories.some((inventory) => inventory.status === 'rejected')) {
+    return null
+  }
+  return inventories.flatMap((inventory) =>
+    inventory.status === 'fulfilled' ? inventory.value.map((process) => process.id) : []
+  )
+}
+
+// Why: keep the module-level adapter and ipc/pty.ts's localProvider in sync so app-quit can't dispose a stale reference.
+export function replaceDaemonProvider(newAdapter: DaemonProvider): void {
+  adapter = newAdapter
+  setLocalPtyProvider(newAdapter)
+}
+
+// Disconnect without killing: the daemon survives app quit so sessions stay warm for reattach.
+// Leave history sessions marked "unclean" so a daemon crash while Orca is closed stays recoverable.
+export async function disconnectDaemon(): Promise<void> {
+  await adapter?.disconnectOnly()
+  adapter = null
+}
+
+/** Kill the daemon and all its sessions. Use for full cleanup only. */
+export async function shutdownDaemon(): Promise<void> {
+  adapter?.dispose()
+  adapter = null
+  await spawner?.shutdown()
+  spawner = null
+}
diff --git a/src/main/daemon/daemon-replacement-preflight.ts b/src/main/daemon/daemon-replacement-preflight.ts
new file mode 100644
index 00000000000..b6f9d7d395c
--- /dev/null
+++ b/src/main/daemon/daemon-replacement-preflight.ts
@@ -0,0 +1,228 @@
+import { getAppEnvironment } from '../../shared/app-environment'
+import type { DaemonReplaceReason } from '../../shared/daemon-lifecycle-telemetry'
+import { isDaemonStaleForCurrentBundle } from './daemon-bundle-staleness'
+import { DaemonEndpointOwnershipError } from './daemon-endpoint-adoption'
+import { checkDaemonHealth, getMacDaemonSystemResolverHealth } from './daemon-health'
+import { getAliveDaemonSessionCount, probeDaemonSocket as probeSocket } from './daemon-launch-paths'
+import { trackDaemonReplaced } from './daemon-lifecycle-event'
+import { getDaemonLaunchIdentity } from './daemon-pid-identity'
+import { cleanupDaemonForProtocol } from './daemon-protocol-cleanup'
+import type { DaemonProcessHandle } from './daemon-spawner'
+import { killStaleDaemon } from './daemon-stale-kill'
+import { getMacDaemonTccAttributionHealth } from './daemon-tcc-attribution'
+import { PROTOCOL_VERSION } from './types'
+
+// Why: extra hello+listSessions probes (~5s each) giving a wedged-but-connectable daemon ~60s grace to answer and keep its live sessions before a permanent wedge (#8689) is replaced; raise only alongside the fail-open cap.
+export const WEDGED_DAEMON_GRACE_RETRIES = 11
+
+type PreserveDaemon = (mode?: 'degraded-new-pty-fallback') => Promise<DaemonProcessHandle>
+
+type ReplacementPreflightOptions = {
+  runtimeDir: string
+  socketPath: string
+  tokenPath: string
+  entryPath: string
+  attributedReason: DaemonReplaceReason | null
+  releaseAdoptionClient: () => void
+  preserveDaemon: PreserveDaemon
+}
+
+export async function prepareDaemonReplacement(
+  options: ReplacementPreflightOptions
+): Promise<DaemonProcessHandle | null> {
+  const {
+    runtimeDir,
+    socketPath,
+    tokenPath,
+    entryPath,
+    attributedReason,
+    releaseAdoptionClient,
+    preserveDaemon
+  } = options
+  let pendingReplacement:
+    | {
+        reason: Parameters<typeof trackDaemonReplaced>[0]
+        liveSessionCount: number | null
+      }
+    | undefined
+  let confirmedReplacement = false
+  const health = await checkDaemonHealth(socketPath, tokenPath)
+  if (health === 'healthy') {
+    const resolverHealth = await getMacDaemonSystemResolverHealth(socketPath, tokenPath)
+    if (resolverHealth === 'unhealthy') {
+      const liveSessionCount = await getAliveDaemonSessionCount(socketPath, tokenPath)
+      if (liveSessionCount !== 0) {
+        console.warn(
+          liveSessionCount === null
+            ? '[daemon] Preserving daemon with unavailable macOS system resolver because live session state could not be verified'
+            : `[daemon] Preserving daemon with unavailable macOS system resolver because it owns ${liveSessionCount} live session${liveSessionCount === 1 ? '' : 's'}`
+        )
+        return preserveDaemon()
+      }
+      console.warn('[daemon] Replacing daemon with unavailable macOS system resolver')
+      pendingReplacement = {
+        reason: 'unhealthy_resolver',
+        liveSessionCount
+      }
+      confirmedReplacement = (await cleanupDaemonForProtocol(runtimeDir, PROTOCOL_VERSION)).cleaned
+    } else {
+      // Why: a protocol-healthy daemon can outlive its launching app bundle (dev worktree rebuild, or packaged update replacing the app path).
+      const identity = await getDaemonLaunchIdentity(runtimeDir, socketPath, tokenPath, entryPath)
+      const stalePackagedBundle =
+        getAppEnvironment().isPackaged() &&
+        (await isDaemonStaleForCurrentBundle(
+          runtimeDir,
+          socketPath,
+          tokenPath,
+          getAppEnvironment().getVersion()
+        ))
+      if (identity === 'mismatch' || stalePackagedBundle) {
+        // Why: replacing a healthy daemon kills its child PTYs; defer code freshness until no live sessions would be lost.
+        const replacementLabel = stalePackagedBundle
+          ? 'launched before the current app bundle was installed'
+          : 'launched from a different app path'
+        if (await shouldPreserveDaemonWithLiveSessions(socketPath, tokenPath, replacementLabel)) {
+          return preserveDaemon()
+        }
+        console.warn(
+          stalePackagedBundle
+            ? '[daemon] Replacing daemon launched before the current app bundle was installed'
+            : '[daemon] Replacing daemon launched from a different app path'
+        )
+        // liveSessionCount is 0: shouldPreserveDaemonWithLiveSessions() only falls through at exactly 0.
+        pendingReplacement = {
+          reason: stalePackagedBundle ? 'stale_bundle' : 'different_app_path',
+          liveSessionCount: 0
+        }
+        confirmedReplacement = (await cleanupDaemonForProtocol(runtimeDir, PROTOCOL_VERSION))
+          .cleaned
+      } else {
+        const attributionHealth = await getMacDaemonTccAttributionHealth(
+          runtimeDir,
+          socketPath,
+          tokenPath
+        )
+        if (attributionHealth === 'severed') {
+          // Why: replacing with live sessions would kill them; Settings → Developer
+          // Permissions surfaces the Manage Sessions → Restart remedy instead.
+          const liveSessionCount = await getAliveDaemonSessionCount(socketPath, tokenPath)
+          if (liveSessionCount === 0) {
+            console.warn(
+              '[daemon] Replacing daemon whose macOS TCC attribution is severed (spawning app binary no longer exists)'
+            )
+            pendingReplacement = { reason: 'severed_tcc_attribution', liveSessionCount }
+            confirmedReplacement = (await cleanupDaemonForProtocol(runtimeDir, PROTOCOL_VERSION))
+              .cleaned
+          } else {
+            return preserveDaemon()
+          }
+        } else {
+          // Why: healthy daemon from a previous session answered a protocol ping — safe to reuse.
+          return preserveDaemon()
+        }
+      }
+    }
+  } else {
+    // Why: a busy machine can time out the health check on a live daemon; re-verify with a session list before killing its sessions.
+    let liveSessionCount = await getAliveDaemonSessionCount(socketPath, tokenPath)
+    // Why: a wedged-but-connectable daemon (Windows update relaunch) may still own live sessions, so grace-retry before replacing; a permanent wedge (#8689) exhausts the grace, and 'rejected' skips it (handshake refused = never adoptable).
+    let graceRetry = 0
+    while (
+      liveSessionCount === null &&
+      health !== 'rejected' &&
+      graceRetry < WEDGED_DAEMON_GRACE_RETRIES &&
+      (await probeSocket(socketPath))
+    ) {
+      liveSessionCount = await getAliveDaemonSessionCount(socketPath, tokenPath)
+      graceRetry++
+    }
+    if (liveSessionCount !== null && liveSessionCount > 0) {
+      if (health === 'pty-spawn-unhealthy') {
+        console.warn(
+          `[daemon] DEGRADED MODE: preserving daemon that failed the PTY spawn health check because it owns ${liveSessionCount} live session${liveSessionCount === 1 ? '' : 's'}. Existing sessions keep working; fresh terminals run on the local provider WITHOUT daemon persistence until you restart the daemon (Manage Sessions → Restart).`
+        )
+        return preserveDaemon('degraded-new-pty-fallback')
+      }
+      console.warn(
+        `[daemon] Preserving daemon that failed the health check because it owns ${liveSessionCount} live session${liveSessionCount === 1 ? '' : 's'}`
+      )
+      return preserveDaemon()
+    }
+    // Why: the sibling replace branches announce themselves, but this one used
+    // to kill a daemon silently — leaving no way to tell a replacement apart
+    // from an adoption after the fact. A cold start also lands here with
+    // nothing to replace, so only speak up once something actually answered:
+    // a probe that returned a count, a socket that survived a grace retry, or
+    // a refused hello.
+    if (liveSessionCount !== null || graceRetry > 0 || health === 'rejected') {
+      console.warn(
+        `[daemon] Replacing daemon that failed the health check (health=${health}, liveSessions=${liveSessionCount ?? 'unverifiable'}, graceRetries=${graceRetry})`
+      )
+    }
+    // Why: unlike the log above, telemetry gates on confirmedReplacement below — the
+    // post-kill truth — so a cold start that killed nothing never reports a replacement.
+    pendingReplacement = {
+      reason: 'failed_health_check',
+      liveSessionCount
+    }
+  }
+
+  // Why: a raw socket can outlive a broken daemon; kill by PID before respawn so the new daemon doesn't race the stale one.
+  releaseAdoptionClient()
+  const killOutcome = await killStaleDaemon(runtimeDir, socketPath, tokenPath)
+  if (killOutcome.liveOwnerSurvived) {
+    // Why: forking beside a daemon we could not prove dead is precisely how the endpoint
+    // owner and the session host diverge. But refusing outright would leave the user with
+    // no daemon at all, and we have just proved something still answers the endpoint —
+    // so adopt it in degraded mode: existing sessions keep working, new PTYs run locally.
+    console.warn(
+      '[daemon] DEGRADED MODE: adopting a daemon that could not be confirmed stopped. Existing sessions keep working; fresh terminals run on the local provider WITHOUT daemon persistence until you restart the daemon (Manage Sessions → Restart).'
+    )
+    try {
+      return await preserveDaemon('degraded-new-pty-fallback')
+    } catch {
+      // It died between the probe and the adoption; the endpoint is genuinely free now.
+      throw new DaemonEndpointOwnershipError(
+        'Daemon replacement aborted: the existing daemon could not be confirmed stopped'
+      )
+    }
+  }
+  confirmedReplacement = killOutcome.killed || confirmedReplacement
+  // Why: rank by how well each reason is evidenced. A confirmed kill whose reason positively
+  // identified the daemon outranks the attribution, so a stale bundle caught here is not billed
+  // to the resolver. failed_health_check is the residual "couldn't tell" bucket though — it also
+  // absorbs wedges and crashes — so the adapter's attribution beats it. That case is not exotic:
+  // the same dead login session that fails the resolver also fails the PTY spawn probe, and with
+  // zero live sessions that lands here rather than in the degraded preserve above.
+  const identifiedReplacement =
+    pendingReplacement &&
+    confirmedReplacement &&
+    pendingReplacement.reason !== 'failed_health_check'
+      ? pendingReplacement
+      : null
+  if (identifiedReplacement) {
+    trackDaemonReplaced(identifiedReplacement.reason, identifiedReplacement.liveSessionCount)
+  } else if (attributedReason) {
+    trackDaemonReplaced(attributedReason, 0)
+  } else if (pendingReplacement && confirmedReplacement) {
+    trackDaemonReplaced(pendingReplacement.reason, pendingReplacement.liveSessionCount)
+  }
+  return null
+}
+
+async function shouldPreserveDaemonWithLiveSessions(
+  socketPath: string,
+  tokenPath: string,
+  replacementLabel: string
+): Promise<boolean> {
+  const liveSessionCount = await getAliveDaemonSessionCount(socketPath, tokenPath)
+  if (liveSessionCount === 0) {
+    return false
+  }
+  console.warn(
+    liveSessionCount === null
+      ? `[daemon] Preserving daemon ${replacementLabel} because live session state could not be verified`
+      : `[daemon] Preserving daemon ${replacementLabel} because it owns ${liveSessionCount} live session${liveSessionCount === 1 ? '' : 's'}`
+  )
+  return true
+}
diff --git a/src/main/daemon/daemon-restart-state.ts b/src/main/daemon/daemon-restart-state.ts
new file mode 100644
index 00000000000..e37fad69709
--- /dev/null
+++ b/src/main/daemon/daemon-restart-state.ts
@@ -0,0 +1,22 @@
+export type RestartDaemonResult = {
+  killedCount: number
+}
+
+// Why: coalesce concurrent restartDaemon() calls so two entries can't race the 7-step sequence against a half-spawned replacement.
+let restartInFlight: Promise<RestartDaemonResult> | null = null
+
+export function isDaemonRestartInFlight(): boolean {
+  return restartInFlight !== null
+}
+
+export function runCoalescedDaemonRestart(
+  run: () => Promise<RestartDaemonResult>
+): Promise<RestartDaemonResult> {
+  if (restartInFlight) {
+    return restartInFlight
+  }
+  restartInFlight = run().finally(() => {
+    restartInFlight = null
+  })
+  return restartInFlight
+}
diff --git a/src/shared/child-process/__fixtures__/child-process-import-allowlist.txt b/src/shared/child-process/__fixtures__/child-process-import-allowlist.txt
index 874ab972787..42cfe12add2 100644
--- a/src/shared/child-process/__fixtures__/child-process-import-allowlist.txt
+++ b/src/shared/child-process/__fixtures__/child-process-import-allowlist.txt
@@ -20,6 +20,9 @@
 # The src/main/git/command-runner/* entries are the seven spawn sites that used
 # to live in the single line src/main/git/runner.ts; splitting that file moved
 # them, it did not add any.
+#
+# daemon-launched-child.ts holds daemon-init.ts's fork() site; splitting that
+# file moved the import, it did not add one.
 src/cli/handlers/account.ts
 src/cli/handlers/core.ts
 src/cli/handlers/interactive-login-interruption.ts
@@ -56,7 +59,7 @@ src/main/computer/macos-computer-use-permissions.ts
 src/main/computer/macos-native-provider-transport.ts
 src/main/computer/sidecar-client.ts
 src/main/daemon/daemon-bash-wrapper-osc133-fixture.ts
-src/main/daemon/daemon-init.ts
+src/main/daemon/daemon-launched-child.ts
 src/main/daemon/daemon-process-identity-query.ts
 src/main/daemon/daemon-process-inspection.ts
 src/main/daemon/daemon-process-start-time.ts