From 2c559fa96a039b17004ce0c1b288bbe1c83b8ca1 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Tue, 1 Sep 2026 16:11:12 -0700
Subject: [PATCH 01/32] test(child-process): make the import ratchet able to
 fail

never grows asserted offenders.length <= ALLOWLIST.length, but the two
membership assertions already force those equal, so it could not fail. The
comment claimed it caught a swap -- one file migrated off child_process, one
added -- which is exactly the case it let through.

Pins the true count and asserts both directions, so a swap fails and a pin left
stale-high after a migration also fails rather than banking ground twice. Gives
the console-visibility ratchet the same test: it had no count assertion at all
and the same gap.

Also anchors the owner-directory exemption with a trailing slash, so a future
src/shared/child-process-foo.ts is scanned rather than silently exempt.
---
 .../child-process-import-boundary.test.ts     | 32 ++++++++++++++++---
 .../windows-console-visibility.test.ts        | 23 +++++++++++++
 2 files changed, 50 insertions(+), 5 deletions(-)

diff --git a/src/shared/child-process/child-process-import-boundary.test.ts b/src/shared/child-process/child-process-import-boundary.test.ts
index 4e261de5c8a..10ca4fd8522 100644
--- a/src/shared/child-process/child-process-import-boundary.test.ts
+++ b/src/shared/child-process/child-process-import-boundary.test.ts
@@ -23,10 +23,19 @@ const CHILD_PROCESS_IMPORT_ALLOWLIST: readonly string[] = readFileSync(
   .map((line) => line.trim())
   .filter((line) => line.length > 0 && !line.startsWith('#'))
 
+/**
+ * The true count of files importing child_process directly.
+ *
+ * May only ever be DECREASED, and only by migrating a file off
+ * `node:child_process`. Raising it is never the fix.
+ */
+const DIRECT_IMPORTER_PIN = 160
+
 const IMPORT_PATTERN =
   /(?:from\s+['"]node:child_process['"]|from\s+['"]child_process['"]|require\(\s*['"]node:child_process['"]|require\(\s*['"]child_process['"])/
 
-const OWNER_DIRECTORY = 'src/shared/child-process'
+// Why: trailing slash, so a sibling like src/shared/child-process-foo.ts is scanned, not exempted.
+const OWNER_DIRECTORY = 'src/shared/child-process/'
 const SCANNED_EXTENSIONS = ['.ts', '.tsx']
 const IGNORED_DIRECTORIES = new Set([
   'node_modules',
@@ -110,9 +119,22 @@ describe('child_process import boundary', () => {
     expect(stale, 'Allowlist entry no longer imports child_process — delete the line.').toEqual([])
   })
 
-  it('never grows', () => {
-    // The count is asserted separately from membership so a swap (one file
-    // migrated, one added) still fails loudly.
-    expect(offenders.length).toBeLessThanOrEqual(CHILD_PROCESS_IMPORT_ALLOWLIST.length)
+  it('holds the offender count at the pin', () => {
+    // Bounding by the allowlist's own length proves nothing: the two move
+    // together, so a swap (one file migrated off, one new file added with its
+    // entry) kept the bound satisfied. The pin is a literal for that reason.
+    expect(
+      offenders.length,
+      `${offenders.length} files import child_process directly; the pin is ${DIRECT_IMPORTER_PIN}. ` +
+        'Never raise the pin -- migrate the file to runProcess/spawnProcess from ' +
+        'src/shared/child-process instead.'
+    ).toBeLessThanOrEqual(DIRECT_IMPORTER_PIN)
+    // A pin left above reality is how a ratchet rots: it re-opens room for the
+    // next direct import to land for free.
+    expect(
+      offenders.length,
+      `Only ${offenders.length} files import child_process directly. Lower DIRECT_IMPORTER_PIN to ` +
+        `${offenders.length} to keep the ground you just took.`
+    ).toBeGreaterThanOrEqual(DIRECT_IMPORTER_PIN)
   })
 })
diff --git a/src/shared/child-process/windows-console-visibility.test.ts b/src/shared/child-process/windows-console-visibility.test.ts
index e98a97cfa98..7985b0ee11a 100644
--- a/src/shared/child-process/windows-console-visibility.test.ts
+++ b/src/shared/child-process/windows-console-visibility.test.ts
@@ -27,6 +27,15 @@ const ALLOWLIST: readonly string[] = readAllowlist(
   join(__dirname, '__fixtures__', 'windows-console-visibility-allowlist.txt')
 )
 
+/**
+ * The true count of files spawning without `windowsHide`.
+ *
+ * May only ever be DECREASED, and only by fixing a call site. Set equality with
+ * the allowlist does not bound this: a swap (one file fixed and delisted, one
+ * new file added with its entry) satisfies both membership assertions.
+ */
+const UNHIDDEN_SPAWNER_PIN = 68
+
 const CHILD_PROCESS_IMPORT =
   /from\s+['"](?:node:)?child_process['"]|require\(\s*['"](?:node:)?child_process['"]/
 // Includes the promisified and renamed spellings -- `execAsync`, `spawnDetached`,
@@ -166,4 +175,18 @@ describe('direct child-process calls hide the Windows console', () => {
     // A fixed file must leave the list, or the ratchet stops ratcheting.
     expect(ALLOWLIST.filter((path) => !offenders.includes(path))).toEqual([])
   })
+
+  it('holds the offender count at the pin', () => {
+    expect(
+      offenders.length,
+      `${offenders.length} files spawn without windowsHide; the pin is ${UNHIDDEN_SPAWNER_PIN}. ` +
+        'Never raise the pin -- add the flag, or route the call through run-process.ts.'
+    ).toBeLessThanOrEqual(UNHIDDEN_SPAWNER_PIN)
+    // A pin left above reality re-opens room for the next unguarded spawn.
+    expect(
+      offenders.length,
+      `Only ${offenders.length} files spawn without windowsHide. Lower UNHIDDEN_SPAWNER_PIN to ` +
+        `${offenders.length} to keep the ground you just took.`
+    ).toBeGreaterThanOrEqual(UNHIDDEN_SPAWNER_PIN)
+  })
 })

From 73fcdea23c74bab3bd49c6ee0b6441102a541bdc Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Tue, 1 Sep 2026 16:11:13 -0700
Subject: [PATCH 02/32] fix(palette): recompute quick-action availability when
 runtime status changes

buildQuickActionContext reads runtimeStatusByEnvironmentId transitively through
getClientCreationActionPolicy, but the split dropped it from the memo deps. The
store replaces the Map identity on update, so the palette held availability from
a snapshot that never refreshed -- offering a browser action against a provider
that had gone away, or hiding one that had come back.

exhaustive-deps could not catch it: the read is behind a void statement, which
the rule does not see.
---
 ...use-worktree-jump-palette-quick-actions.ts |   8 +-
 ...palette-quick-action-availability.test.tsx | 103 ++++++++++++++++++
 .../lib/lazy-chunk-recovery-reload.test.ts    |  29 +++++
 3 files changed, 139 insertions(+), 1 deletion(-)
 create mode 100644 src/renderer/src/components/worktree-jump-palette-quick-action-availability.test.tsx

diff --git a/src/renderer/src/components/use-worktree-jump-palette-quick-actions.ts b/src/renderer/src/components/use-worktree-jump-palette-quick-actions.ts
index c6cf2c48d05..0783a7e5d23 100644
--- a/src/renderer/src/components/use-worktree-jump-palette-quick-actions.ts
+++ b/src/renderer/src/components/use-worktree-jump-palette-quick-actions.ts
@@ -58,6 +58,7 @@ export function useWorktreeJumpPaletteQuickActions({
   groupsByWorktree,
   isLoading,
   settings,
+  runtimeStatusByEnvironmentId,
   deferredQuery,
   settingsResults
 }: WorktreeJumpPaletteQuickActionsInput) {
@@ -117,6 +118,9 @@ export function useWorktreeJumpPaletteQuickActions({
       openNewTerminalTabInActiveWorkspace
     ]
   )
+  // Why: buildQuickActionContext() reads the store imperatively, so these voided values are the
+  // memo's real inputs — each one is read (some transitively, e.g. runtimeStatusByEnvironmentId
+  // via the managed-browser creation policy) while availability is computed.
   const availableActionResults = useMemo(() => {
     void activeView
     void activeWorktreeId
@@ -127,6 +131,7 @@ export function useWorktreeJumpPaletteQuickActions({
     void groupsByWorktree
     void isLoading
     void settings?.activeRuntimeEnvironmentId
+    void runtimeStatusByEnvironmentId
     const context = buildQuickActionContext()
     return actionResults.filter((action) => action.isAvailable(context).available)
   }, [
@@ -140,7 +145,8 @@ export function useWorktreeJumpPaletteQuickActions({
     activeGroupIdByWorktree,
     groupsByWorktree,
     isLoading,
-    settings?.activeRuntimeEnvironmentId
+    settings?.activeRuntimeEnvironmentId,
+    runtimeStatusByEnvironmentId
   ])
   const middleItems = useMemo<(SettingsPaletteItem | QuickActionPaletteItem)[]>(
     () =>
diff --git a/src/renderer/src/components/worktree-jump-palette-quick-action-availability.test.tsx b/src/renderer/src/components/worktree-jump-palette-quick-action-availability.test.tsx
new file mode 100644
index 00000000000..69459901bfa
--- /dev/null
+++ b/src/renderer/src/components/worktree-jump-palette-quick-action-availability.test.tsx
@@ -0,0 +1,103 @@
+// @vitest-environment happy-dom
+
+import { renderHook } from '@testing-library/react'
+import { createRef } from 'react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { BROWSER_SCREENCAST_RUNTIME_CAPABILITY } from '../../../shared/protocol-version'
+import { buildCmdJActionResults } from '@/components/cmd-j/palette-results'
+import { getCmdJQuickActions } from '@/components/cmd-j/quick-actions'
+import { useWorktreeJumpPaletteQuickActions } from './use-worktree-jump-palette-quick-actions'
+
+const mocks = vi.hoisted(() => ({ state: {} as Record<string, unknown> }))
+
+vi.mock('@/store', () => ({ useAppStore: { getState: () => mocks.state } }))
+vi.mock('@/lib/worktree-runtime-owner', () => ({
+  getRuntimeEnvironmentIdForWorktree: () => RUNTIME_ID
+}))
+vi.mock('@/components/sidebar/delete-worktree-flow', () => ({ runWorktreeDelete: vi.fn() }))
+
+const RUNTIME_ID = 'runtime-1'
+const WORKTREE_ID = 'repo-1::/repo/wt'
+
+function runtimeStatuses(capabilities: string[]): Map<string, unknown> {
+  return new Map([[RUNTIME_ID, { status: { capabilities, hostPlatform: 'darwin' } }]])
+}
+
+// Every input except runtimeStatusByEnvironmentId keeps a stable identity across rerenders,
+// so a recomputation can only come from the runtime status dependency itself.
+function buildStableProps() {
+  return {
+    openModal: vi.fn(),
+    openSettingsPage: vi.fn(),
+    openSettingsTarget: vi.fn(),
+    activeGroupSnapshotRef: createRef<null>(),
+    openNewBrowserTabInActiveWorkspace: vi.fn(),
+    openNewMarkdownInActiveWorkspace: vi.fn(),
+    openNewTerminalTabInActiveWorkspace: vi.fn(),
+    actionResults: buildCmdJActionResults(getCmdJQuickActions()),
+    activeView: 'terminal',
+    activeWorktreeId: WORKTREE_ID,
+    worktreesByRepo: mocks.state.worktreesByRepo,
+    repos: mocks.state.repos,
+    sshConnectionStates: mocks.state.sshConnectionStates,
+    activeGroupIdByWorktree: mocks.state.activeGroupIdByWorktree,
+    groupsByWorktree: mocks.state.groupsByWorktree,
+    isLoading: false,
+    settings: mocks.state.settings,
+    deferredQuery: 'new browser tab',
+    settingsResults: []
+  }
+}
+
+function renderQuickActions(initialStatuses: Map<string, unknown>) {
+  const stable = buildStableProps()
+  mocks.state.runtimeStatusByEnvironmentId = initialStatuses
+  const harness = renderHook(
+    (runtimeStatusByEnvironmentId: Map<string, unknown>) =>
+      useWorktreeJumpPaletteQuickActions({ ...stable, runtimeStatusByEnvironmentId } as never),
+    { initialProps: initialStatuses }
+  )
+  return {
+    offersBrowserAction: (): boolean =>
+      harness.result.current.middleItems.some((item) => item.id === 'quick-action:new-browser-tab'),
+    setRuntimeStatuses: (next: Map<string, unknown>): void => {
+      mocks.state.runtimeStatusByEnvironmentId = next
+      harness.rerender(next)
+    }
+  }
+}
+
+describe('worktree jump palette quick action availability', () => {
+  beforeEach(() => {
+    ;(globalThis as { __ORCA_WEB_CLIENT__?: boolean }).__ORCA_WEB_CLIENT__ = true
+    mocks.state = {
+      activeView: 'terminal',
+      activeWorktreeId: WORKTREE_ID,
+      worktreesByRepo: { 'repo-1': [{ id: WORKTREE_ID, repoId: 'repo-1' }] },
+      repos: [{ id: 'repo-1' }],
+      sshConnectionStates: new Map(),
+      activeGroupIdByWorktree: { [WORKTREE_ID]: 'group-1' },
+      groupsByWorktree: { [WORKTREE_ID]: [{ id: 'group-1' }] },
+      settings: { activeRuntimeEnvironmentId: RUNTIME_ID }
+    }
+  })
+  afterEach(() => {
+    delete (globalThis as { __ORCA_WEB_CLIENT__?: boolean }).__ORCA_WEB_CLIENT__
+  })
+
+  it('drops the paired-web browser action when the runtime loses screencast capability', () => {
+    const palette = renderQuickActions(runtimeStatuses([BROWSER_SCREENCAST_RUNTIME_CAPABILITY]))
+    expect(palette.offersBrowserAction()).toBe(true)
+
+    palette.setRuntimeStatuses(runtimeStatuses([]))
+    expect(palette.offersBrowserAction()).toBe(false)
+  })
+
+  it('restores the browser action when a capable runtime comes back', () => {
+    const palette = renderQuickActions(runtimeStatuses([]))
+    expect(palette.offersBrowserAction()).toBe(false)
+
+    palette.setRuntimeStatuses(runtimeStatuses([BROWSER_SCREENCAST_RUNTIME_CAPABILITY]))
+    expect(palette.offersBrowserAction()).toBe(true)
+  })
+})
diff --git a/src/renderer/src/lib/lazy-chunk-recovery-reload.test.ts b/src/renderer/src/lib/lazy-chunk-recovery-reload.test.ts
index 9cdf4fa728d..8c113363861 100644
--- a/src/renderer/src/lib/lazy-chunk-recovery-reload.test.ts
+++ b/src/renderer/src/lib/lazy-chunk-recovery-reload.test.ts
@@ -6,6 +6,7 @@ import { requestLazyChunkRecoveryReload } from './lazy-chunk-recovery-reload'
 describe('requestLazyChunkRecoveryReload', () => {
   afterEach(() => {
     vi.restoreAllMocks()
+    vi.unstubAllGlobals()
   })
 
   it('refuses the reload when the staged checkpoint never reaches disk', async () => {
@@ -36,4 +37,32 @@ describe('requestLazyChunkRecoveryReload', () => {
 
     expect(order).toEqual(['flushed', 'reload'])
   })
+
+  it('joins the preload checkpoint before navigating when no override is supplied', async () => {
+    const order: string[] = []
+    let flush: () => void = () => undefined
+    const awaitBeforeUnloadCheckpoint = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          flush = () => {
+            order.push('flushed')
+            resolve()
+          }
+        })
+    )
+    vi.stubGlobal('api', { app: { awaitBeforeUnloadCheckpoint } })
+    const reload = vi.spyOn(window.location, 'reload').mockImplementation(() => {
+      order.push('reload')
+      window.dispatchEvent(new Event(ORCA_RENDERER_UNLOAD_PREVENTED_EVENT))
+    })
+
+    const outcome = requestLazyChunkRecoveryReload(window)
+    await vi.waitFor(() => expect(awaitBeforeUnloadCheckpoint).toHaveBeenCalledTimes(1))
+    expect(reload).not.toHaveBeenCalled()
+
+    flush()
+
+    await expect(outcome).resolves.toBe('unload-vetoed')
+    expect(order).toEqual(['flushed', 'reload'])
+  })
 })

From c8937936eb5ae50d8e0b9a0481617f90a6e7054a Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Tue, 1 Sep 2026 16:11:14 -0700
Subject: [PATCH 03/32] refactor(mobile): pin the terminal WebView payload and
 split its widest slice

The payload is one concatenated string, so slice boundaries follow document
order rather than responsibility -- but join is associative, so cutting a slice
into consecutive slices is byte-identical by construction. Splits the widest
slice, which carried fit-scale, a DECSET scanner and the write queue together
with no room left under the line cap.

Adds a hash guard. The behavioral tests each execute one region of the payload
in a vm, so an edit to an uncovered region shipped silently; the composed output
is now pinned by sha256 and length.

Derives the source-file list from the composer's own imports instead of a second
hardcoded list a new slice had to be added to by hand -- the same silent
subject-loss shape already found twice elsewhere in this repo.
---
 ...rminal-webview-html-source.test-support.ts |  45 +--
 mobile/src/terminal/terminal-webview-html.ts  |   8 +-
 .../fit-scale-and-write-queue.ts              | 288 ------------------
 .../mouse-mode-decset-scan.ts                 |  52 ++++
 .../terminal-fit-scale.ts                     | 130 ++++++++
 .../terminal-webview-html/write-queue.ts      | 110 +++++++
 .../terminal-webview-payload-hash.test.ts     |  17 ++
 7 files changed, 341 insertions(+), 309 deletions(-)
 delete mode 100644 mobile/src/terminal/terminal-webview-html/fit-scale-and-write-queue.ts
 create mode 100644 mobile/src/terminal/terminal-webview-html/mouse-mode-decset-scan.ts
 create mode 100644 mobile/src/terminal/terminal-webview-html/terminal-fit-scale.ts
 create mode 100644 mobile/src/terminal/terminal-webview-html/write-queue.ts
 create mode 100644 mobile/src/terminal/terminal-webview-payload-hash.test.ts

diff --git a/mobile/src/terminal/terminal-webview-html-source.test-support.ts b/mobile/src/terminal/terminal-webview-html-source.test-support.ts
index 25902305f41..19a9cfc07ba 100644
--- a/mobile/src/terminal/terminal-webview-html-source.test-support.ts
+++ b/mobile/src/terminal/terminal-webview-html-source.test-support.ts
@@ -1,24 +1,31 @@
 import { readFileSync } from 'node:fs'
 
-const SOURCE_FILES = [
-  './terminal-webview-html.ts',
-  './terminal-webview-html/document-shell.ts',
-  './terminal-webview-html/runtime-state-and-text-scaling.ts',
-  './terminal-webview-html/fit-scale-and-write-queue.ts',
-  './terminal-webview-html/terminal-init-and-write.ts',
-  './terminal-webview-html/host-message-router.ts',
-  './terminal-webview-html/selection-state-and-eviction.ts',
-  './terminal-webview-html/term-observers-and-mode-mirroring.ts',
-  './terminal-webview-html/mouse-report-and-scroll-routing.ts',
-  './terminal-webview-html/smooth-scroll-and-cell-geometry.ts',
-  './terminal-webview-html/selection-overlay.ts',
-  './terminal-webview-html/surface-touch-gestures.ts',
-  './terminal-webview-html/message-bridge-and-document-close.ts'
-] as const
+const COMPOSER_FILE = './terminal-webview-html.ts'
+const SLICE_IMPORT_RE = /^import \{[^}]*\} from '(\.\/terminal-webview-html\/[\w-]+)'$/gm
+const COMPOSED_ENTRY_RE = /^ {2}TERMINAL_HTML_\w+,?$/gm
 
-/** Reads the TypeScript source that assembles the in-WebView document. */
+function readSource(relativePath: string): string {
+  return readFileSync(new URL(relativePath, import.meta.url), 'utf8')
+}
+
+/**
+ * Reads the TypeScript source that assembles the in-WebView document.
+ *
+ * Why: the slice list is derived from the composer's own imports rather than duplicated, so a
+ * new slice cannot join the emitted document while staying invisible to the tests that search
+ * this source. The count cross-check catches an import shape the regex cannot see.
+ */
 export function readTerminalWebViewHtmlSource(): string {
-  return SOURCE_FILES.map((relativePath) =>
-    readFileSync(new URL(relativePath, import.meta.url), 'utf8')
-  ).join('\n')
+  const composer = readSource(COMPOSER_FILE)
+  const slices = [...composer.matchAll(SLICE_IMPORT_RE)].map((match) => `${match[1]}.ts`)
+  const composedCount = [...composer.matchAll(COMPOSED_ENTRY_RE)].length
+  if (composedCount === 0) {
+    throw new Error('no composed WebView document slices found')
+  }
+  if (slices.length !== composedCount) {
+    throw new Error(
+      `WebView document slice imports (${slices.length}) do not match composed entries (${composedCount})`
+    )
+  }
+  return [composer, ...slices.map(readSource)].join('\n')
 }
diff --git a/mobile/src/terminal/terminal-webview-html.ts b/mobile/src/terminal/terminal-webview-html.ts
index 40b7a2db22c..17fadd4d26c 100644
--- a/mobile/src/terminal/terminal-webview-html.ts
+++ b/mobile/src/terminal/terminal-webview-html.ts
@@ -1,6 +1,8 @@
 import { TERMINAL_HTML_DOCUMENT_SHELL } from './terminal-webview-html/document-shell'
 import { TERMINAL_HTML_RUNTIME_STATE_AND_TEXT_SCALING } from './terminal-webview-html/runtime-state-and-text-scaling'
-import { TERMINAL_HTML_FIT_SCALE_AND_WRITE_QUEUE } from './terminal-webview-html/fit-scale-and-write-queue'
+import { TERMINAL_HTML_FIT_SCALE } from './terminal-webview-html/terminal-fit-scale'
+import { TERMINAL_HTML_MOUSE_MODE_DECSET_SCAN } from './terminal-webview-html/mouse-mode-decset-scan'
+import { TERMINAL_HTML_WRITE_QUEUE } from './terminal-webview-html/write-queue'
 import { TERMINAL_HTML_INIT_AND_WRITE } from './terminal-webview-html/terminal-init-and-write'
 import { TERMINAL_HTML_HOST_MESSAGE_ROUTER } from './terminal-webview-html/host-message-router'
 import { TERMINAL_HTML_SELECTION_STATE_AND_EVICTION } from './terminal-webview-html/selection-state-and-eviction'
@@ -19,7 +21,9 @@ export { MOBILE_TERMINAL_CARET_OPTIONS } from './terminal-webview-html/theme'
 export const XTERM_HTML = [
   TERMINAL_HTML_DOCUMENT_SHELL,
   TERMINAL_HTML_RUNTIME_STATE_AND_TEXT_SCALING,
-  TERMINAL_HTML_FIT_SCALE_AND_WRITE_QUEUE,
+  TERMINAL_HTML_FIT_SCALE,
+  TERMINAL_HTML_MOUSE_MODE_DECSET_SCAN,
+  TERMINAL_HTML_WRITE_QUEUE,
   TERMINAL_HTML_INIT_AND_WRITE,
   TERMINAL_HTML_HOST_MESSAGE_ROUTER,
   TERMINAL_HTML_SELECTION_STATE_AND_EVICTION,
diff --git a/mobile/src/terminal/terminal-webview-html/fit-scale-and-write-queue.ts b/mobile/src/terminal/terminal-webview-html/fit-scale-and-write-queue.ts
deleted file mode 100644
index 074185d43a5..00000000000
--- a/mobile/src/terminal/terminal-webview-html/fit-scale-and-write-queue.ts
+++ /dev/null
@@ -1,288 +0,0 @@
-import { TERMINAL_WEBVIEW_THEME_JS } from '../terminal-webview-theme-injected'
-
-// Also carries the DECSET mouse-mode scanner: emitted-document order pins it between these two concerns.
-export const TERMINAL_HTML_FIT_SCALE_AND_WRITE_QUEUE = `${TERMINAL_WEBVIEW_THEME_JS}
-
-  function getCellHeight() {
-    if (!term || !term._core) return 15;
-    var core = term._core;
-    if (core._renderService && core._renderService.dimensions) {
-      return core._renderService.dimensions.css.cell.height || 15;
-    }
-    return 15;
-  }
-
-  // Why: clamp pan so the terminal content always covers the viewport
-  // when zoomed in. When content is smaller than viewport in a
-  // dimension, pin to top-left (no floating in the middle).
-  function clampPan() {
-    if (!term || !term.element) return;
-    var ts = getTotalScale();
-    var cw = term.element.scrollWidth * ts;
-    var ch = term.element.scrollHeight * ts;
-    var vpW = window.innerWidth;
-    var vpH = window.innerHeight;
-    if (cw > vpW) {
-      panX = Math.min(0, Math.max(vpW - cw, panX));
-    } else {
-      panX = 0;
-    }
-    if (ch > vpH) {
-      panY = Math.min(0, Math.max(vpH - ch, panY));
-    } else {
-      panY = 0;
-    }
-  }
-
-  // Why: intentional no-op. Mobile replays a live PTY snapshot then applies
-  // live cursor-relative chunks from that same PTY; resizing only the WebView
-  // xterm changes cursor coordinates and makes TUI repaint chunks duplicate or
-  // overlap. Kept as a no-op so its call sites stay legible.
-  function adjustRowsForViewport() {}
-
-  // Why: cold-start fit. After init() opens xterm, the renderer needs
-  // several frames before cell dimensions are computed. Reading too early
-  // gives cellWidth=0 (renderer service not ready) or scrollWidth=0 (DOM
-  // not laid out), and computeFitScale returns 1 → no zoom.
-  //
-  // Gate: cellWidth × cols is the canonical "logical width" of the grid
-  // and reflects xterm's layout decision, independent of buffer content.
-  // We commit when cellWidth becomes positive (renderer ready). Fallback:
-  // if cellWidth never becomes available, gate on stable positive
-  // scrollWidth (xterm rendered something). Cap at 60 frames (~1s @60Hz)
-  // so a backgrounded WebView never spins forever.
-  var FIT_RETRY_MAX_FRAMES = 60;
-  var fitRetryToken = 0;
-  function applyFitScale(reason) {
-    if (!term || !term.element) return;
-    var token = ++fitRetryToken;
-    var attempts = 0;
-    var lastScrollWidth = -1;
-    function attempt() {
-      if (token !== fitRetryToken) return;
-      if (!term || !term.element) return;
-      attempts++;
-      var cellW = getCellWidth();
-      if (cellW > 0 && term.cols > 0) {
-        commitFitScale(reason, attempts, 'cellW');
-        return;
-      }
-      var w = term.element.scrollWidth;
-      if (w > 0 && w === lastScrollWidth) {
-        commitFitScale(reason, attempts, 'stableSW');
-        return;
-      }
-      lastScrollWidth = w;
-      if (attempts >= FIT_RETRY_MAX_FRAMES) {
-        flog('commit-timeout', {
-          reason: reason,
-          attempts: attempts,
-          cellW: cellW,
-          scrollWidth: w,
-          cols: term.cols
-        });
-        commitFitScale(reason, attempts, 'timeout');
-        return;
-      }
-      requestAnimationFrame(attempt);
-    }
-    requestAnimationFrame(attempt);
-  }
-
-  function commitFitScale(reason, attempts, gate) {
-    if (!term || !term.element) return;
-    var preSnapScale = computeFitScale();
-    currentScale = preSnapScale;
-    // Why: when scale is very close to 1 (e.g. 0.97 from xterm scrollbar
-    // sub-pixels) snap to 1 to avoid imperceptible shrinkage that prevents
-    // a second applyFitScale from observing a "no-op needed" state.
-    if (currentScale >= 0.95) currentScale = 1;
-    userScale = 1;
-    panX = 0;
-    panY = 0;
-    smoothScrollOffsetY = 0;
-    updateTransform();
-    adjustRowsForViewport();
-
-    var cellW = getCellWidth();
-    var sw = term.element.scrollWidth;
-    var vpW = window.innerWidth;
-    var expectedW = cellW * term.cols;
-    var suspect =
-      currentScale === 1 && term.cols > 0 && expectedW > vpW + 1; // expected wider than viewport but no zoom
-    if (suspect) {
-      flog('commit-SUSPECT', {
-        reason: reason,
-        attempts: attempts,
-        gate: gate,
-        preSnapScale: preSnapScale,
-        finalScale: currentScale,
-        cellW: cellW,
-        cols: term.cols,
-        expectedW: expectedW,
-        scrollWidth: sw,
-        vpWidth: vpW
-      });
-    }
-    repositionOverlay();
-  }
-
-  function isAltScreenActive(data) {
-    if (typeof data !== 'string') return false;
-    var on = data.lastIndexOf(ESC + '[?1049h');
-    var off = data.lastIndexOf(ESC + '[?1049l');
-    return on !== -1 && on > off;
-  }
-
-  function normalizeInitialData(data) {
-    if (!isAltScreenActive(data)) return data;
-    var on = data.lastIndexOf(ESC + '[?1049h');
-    // Why: SerializeAddon can include normal-buffer scrollback before the
-    // active alternate-screen snapshot. Replaying both into a fresh mobile
-    // xterm duplicates TUI frames and can flatten SGR attributes.
-    return on > 0 ? data.slice(on) : data;
-  }
-
-  function updateMouseModeFromData(data) {
-    if (typeof data !== 'string' || data.length === 0) return;
-    var input = mouseModeScanTail + data;
-    mouseModeScanTail = extractMouseModeScanTail(input);
-    var re = new RegExp(ESC + 'c|' + ESC + '\\\\[\\\\?([0-9;]+)([hl])|' + C1_CSI + '\\\\?([0-9;]+)([hl])', 'g');
-    var match;
-    while ((match = re.exec(input)) !== null) {
-      if (match[0] === ESC + 'c') {
-        trackedMouseTrackingMode = 'none';
-        sgrMouseMode = false;
-        sgrMousePixelsMode = false;
-        continue;
-      }
-      var enabled = (match[2] || match[4]) === 'h';
-      var params = (match[1] || match[3]).split(';');
-      for (var i = 0; i < params.length; i++) {
-        if (params[i] === '') continue;
-        var param = Number(params[i]);
-        if (!Number.isInteger(param)) continue;
-        if (param === 9) trackedMouseTrackingMode = enabled ? 'x10' : 'none';
-        if (param === 1000) trackedMouseTrackingMode = enabled ? 'vt200' : 'none';
-        if (param === 1002) trackedMouseTrackingMode = enabled ? 'drag' : 'none';
-        if (param === 1003) trackedMouseTrackingMode = enabled ? 'any' : 'none';
-        if (param === 1006) {
-          sgrMouseMode = enabled;
-          sgrMousePixelsMode = false;
-        }
-        if (param === 1016) {
-          sgrMouseMode = false;
-          sgrMousePixelsMode = enabled;
-        }
-      }
-    }
-  }
-
-  function resetWriteQueue() {
-    writeQueue = [];
-    writeQueueHead = 0;
-  }
-
-  function isStatusDotPresentationSelector(value) {
-    return value === TEXT_PRESENTATION_SELECTOR || value === EMOJI_PRESENTATION_SELECTOR;
-  }
-
-  function endsWithStatusDotPresentationSequence(data) {
-    var i = data.length - 1;
-    while (i >= 0 && isStatusDotPresentationSelector(data.charAt(i))) i--;
-    return i >= 0 && data.charAt(i) === CLAUDE_STATUS_DOT;
-  }
-
-  // Why: iOS WebKit promotes Claude's record/status dot to a colorful emoji glyph.
-  function normalizeStatusDotPresentation(data) {
-    if (typeof data !== 'string' || data.length === 0) return data;
-    if (statusDotPendingSelector) {
-      statusDotPendingSelector = false;
-      var strippedPendingSelectors = false;
-      while (data.length > 0 && isStatusDotPresentationSelector(data.charAt(0))) data = data.slice(1);
-      strippedPendingSelectors = data.length === 0;
-      if (strippedPendingSelectors) {
-        statusDotPendingSelector = true;
-        return '';
-      }
-    }
-    var normalized = data.replace(CLAUDE_STATUS_DOT_PATTERN, CLAUDE_STATUS_DOT + TEXT_PRESENTATION_SELECTOR);
-    statusDotPendingSelector = endsWithStatusDotPresentationSequence(data);
-    return normalized;
-  }
-
-  function enqueueWrite(data) {
-    writeQueue.push(normalizeStatusDotPresentation(data));
-  }
-
-  function enqueueWriteBoundary(callback) {
-    writeQueue.push(callback);
-  }
-
-  function nextQueuedWrite() {
-    if (writeQueueHead >= writeQueue.length) {
-      resetWriteQueue();
-      return undefined;
-    }
-    var next = writeQueue[writeQueueHead];
-    writeQueueHead++;
-    // Why: high-throughput terminals can enqueue faster than xterm parses;
-    // compact consumed slots so drain work stays O(1) without retaining old chunks.
-    if (writeQueueHead > 128 && writeQueueHead * 2 > writeQueue.length) {
-      writeQueue = writeQueue.slice(writeQueueHead);
-      writeQueueHead = 0;
-    }
-    return next;
-  }
-
-  function disposeTermObservers() {
-    var disposables = termObserverDisposables;
-    termObserverDisposables = [];
-    for (var i = 0; i < disposables.length; i++) {
-      try { disposables[i] && disposables[i].dispose && disposables[i].dispose(); } catch (e) {}
-    }
-  }
-
-  function extractMouseModeScanTail(input) {
-    var start = Math.max(input.lastIndexOf(ESC), input.lastIndexOf(C1_CSI));
-    if (start === -1) return '';
-    var tail = input.slice(start);
-    // Why: PTY/SSH chunks can split a long combined DECSET before the final h/l.
-    // Keep parser state far beyond normal mode lists while still bounding memory.
-    if (tail.length > PRIVATE_MODE_SCAN_TAIL_LIMIT) return '';
-    if (tail === ESC || tail === ESC + '[' || tail === C1_CSI) return tail;
-    if (tail.indexOf(ESC + '[?') === 0) {
-      return /^[0-9;]*$/.test(tail.slice(3)) ? tail : '';
-    }
-    if (tail.indexOf(C1_CSI + '?') === 0) {
-      return /^[0-9;]*$/.test(tail.slice(2)) ? tail : '';
-    }
-    return '';
-  }
-
-  function pumpWrites(gen) {
-    if (!ready || !term || writesDraining || gen !== terminalGeneration) return;
-    var next = nextQueuedWrite();
-    if (typeof next !== 'string') {
-      if (typeof next === 'function') return next(), pumpWrites(gen);
-      var callbacks = afterDrainCallbacks;
-      afterDrainCallbacks = [];
-      for (var i = 0; i < callbacks.length; i++) callbacks[i]();
-      return;
-    }
-    writesDraining = true;
-    // Why: xterm.write() parses asynchronously. Row adjustment/resizing must
-    // wait until replayed SGR attributes have landed in the buffer.
-    term.write(next, function() {
-      if (gen !== terminalGeneration) return;
-      writesDraining = false;
-      pumpWrites(gen);
-    });
-  }
-
-  function afterWritesDrained(callback) {
-    afterDrainCallbacks.push(callback);
-    pumpWrites(terminalGeneration);
-  }
-
-`
diff --git a/mobile/src/terminal/terminal-webview-html/mouse-mode-decset-scan.ts b/mobile/src/terminal/terminal-webview-html/mouse-mode-decset-scan.ts
new file mode 100644
index 00000000000..6f0685df87e
--- /dev/null
+++ b/mobile/src/terminal/terminal-webview-html/mouse-mode-decset-scan.ts
@@ -0,0 +1,52 @@
+export const TERMINAL_HTML_MOUSE_MODE_DECSET_SCAN = `  function isAltScreenActive(data) {
+    if (typeof data !== 'string') return false;
+    var on = data.lastIndexOf(ESC + '[?1049h');
+    var off = data.lastIndexOf(ESC + '[?1049l');
+    return on !== -1 && on > off;
+  }
+
+  function normalizeInitialData(data) {
+    if (!isAltScreenActive(data)) return data;
+    var on = data.lastIndexOf(ESC + '[?1049h');
+    // Why: SerializeAddon can include normal-buffer scrollback before the
+    // active alternate-screen snapshot. Replaying both into a fresh mobile
+    // xterm duplicates TUI frames and can flatten SGR attributes.
+    return on > 0 ? data.slice(on) : data;
+  }
+
+  function updateMouseModeFromData(data) {
+    if (typeof data !== 'string' || data.length === 0) return;
+    var input = mouseModeScanTail + data;
+    mouseModeScanTail = extractMouseModeScanTail(input);
+    var re = new RegExp(ESC + 'c|' + ESC + '\\\\[\\\\?([0-9;]+)([hl])|' + C1_CSI + '\\\\?([0-9;]+)([hl])', 'g');
+    var match;
+    while ((match = re.exec(input)) !== null) {
+      if (match[0] === ESC + 'c') {
+        trackedMouseTrackingMode = 'none';
+        sgrMouseMode = false;
+        sgrMousePixelsMode = false;
+        continue;
+      }
+      var enabled = (match[2] || match[4]) === 'h';
+      var params = (match[1] || match[3]).split(';');
+      for (var i = 0; i < params.length; i++) {
+        if (params[i] === '') continue;
+        var param = Number(params[i]);
+        if (!Number.isInteger(param)) continue;
+        if (param === 9) trackedMouseTrackingMode = enabled ? 'x10' : 'none';
+        if (param === 1000) trackedMouseTrackingMode = enabled ? 'vt200' : 'none';
+        if (param === 1002) trackedMouseTrackingMode = enabled ? 'drag' : 'none';
+        if (param === 1003) trackedMouseTrackingMode = enabled ? 'any' : 'none';
+        if (param === 1006) {
+          sgrMouseMode = enabled;
+          sgrMousePixelsMode = false;
+        }
+        if (param === 1016) {
+          sgrMouseMode = false;
+          sgrMousePixelsMode = enabled;
+        }
+      }
+    }
+  }
+
+`
diff --git a/mobile/src/terminal/terminal-webview-html/terminal-fit-scale.ts b/mobile/src/terminal/terminal-webview-html/terminal-fit-scale.ts
new file mode 100644
index 00000000000..b756bcb550c
--- /dev/null
+++ b/mobile/src/terminal/terminal-webview-html/terminal-fit-scale.ts
@@ -0,0 +1,130 @@
+import { TERMINAL_WEBVIEW_THEME_JS } from '../terminal-webview-theme-injected'
+
+// Opens with the injected theme block: it lands at this point in the emitted document.
+export const TERMINAL_HTML_FIT_SCALE = `${TERMINAL_WEBVIEW_THEME_JS}
+
+  function getCellHeight() {
+    if (!term || !term._core) return 15;
+    var core = term._core;
+    if (core._renderService && core._renderService.dimensions) {
+      return core._renderService.dimensions.css.cell.height || 15;
+    }
+    return 15;
+  }
+
+  // Why: clamp pan so the terminal content always covers the viewport
+  // when zoomed in. When content is smaller than viewport in a
+  // dimension, pin to top-left (no floating in the middle).
+  function clampPan() {
+    if (!term || !term.element) return;
+    var ts = getTotalScale();
+    var cw = term.element.scrollWidth * ts;
+    var ch = term.element.scrollHeight * ts;
+    var vpW = window.innerWidth;
+    var vpH = window.innerHeight;
+    if (cw > vpW) {
+      panX = Math.min(0, Math.max(vpW - cw, panX));
+    } else {
+      panX = 0;
+    }
+    if (ch > vpH) {
+      panY = Math.min(0, Math.max(vpH - ch, panY));
+    } else {
+      panY = 0;
+    }
+  }
+
+  // Why: intentional no-op. Mobile replays a live PTY snapshot then applies
+  // live cursor-relative chunks from that same PTY; resizing only the WebView
+  // xterm changes cursor coordinates and makes TUI repaint chunks duplicate or
+  // overlap. Kept as a no-op so its call sites stay legible.
+  function adjustRowsForViewport() {}
+
+  // Why: cold-start fit. After init() opens xterm, the renderer needs
+  // several frames before cell dimensions are computed. Reading too early
+  // gives cellWidth=0 (renderer service not ready) or scrollWidth=0 (DOM
+  // not laid out), and computeFitScale returns 1 → no zoom.
+  //
+  // Gate: cellWidth × cols is the canonical "logical width" of the grid
+  // and reflects xterm's layout decision, independent of buffer content.
+  // We commit when cellWidth becomes positive (renderer ready). Fallback:
+  // if cellWidth never becomes available, gate on stable positive
+  // scrollWidth (xterm rendered something). Cap at 60 frames (~1s @60Hz)
+  // so a backgrounded WebView never spins forever.
+  var FIT_RETRY_MAX_FRAMES = 60;
+  var fitRetryToken = 0;
+  function applyFitScale(reason) {
+    if (!term || !term.element) return;
+    var token = ++fitRetryToken;
+    var attempts = 0;
+    var lastScrollWidth = -1;
+    function attempt() {
+      if (token !== fitRetryToken) return;
+      if (!term || !term.element) return;
+      attempts++;
+      var cellW = getCellWidth();
+      if (cellW > 0 && term.cols > 0) {
+        commitFitScale(reason, attempts, 'cellW');
+        return;
+      }
+      var w = term.element.scrollWidth;
+      if (w > 0 && w === lastScrollWidth) {
+        commitFitScale(reason, attempts, 'stableSW');
+        return;
+      }
+      lastScrollWidth = w;
+      if (attempts >= FIT_RETRY_MAX_FRAMES) {
+        flog('commit-timeout', {
+          reason: reason,
+          attempts: attempts,
+          cellW: cellW,
+          scrollWidth: w,
+          cols: term.cols
+        });
+        commitFitScale(reason, attempts, 'timeout');
+        return;
+      }
+      requestAnimationFrame(attempt);
+    }
+    requestAnimationFrame(attempt);
+  }
+
+  function commitFitScale(reason, attempts, gate) {
+    if (!term || !term.element) return;
+    var preSnapScale = computeFitScale();
+    currentScale = preSnapScale;
+    // Why: when scale is very close to 1 (e.g. 0.97 from xterm scrollbar
+    // sub-pixels) snap to 1 to avoid imperceptible shrinkage that prevents
+    // a second applyFitScale from observing a "no-op needed" state.
+    if (currentScale >= 0.95) currentScale = 1;
+    userScale = 1;
+    panX = 0;
+    panY = 0;
+    smoothScrollOffsetY = 0;
+    updateTransform();
+    adjustRowsForViewport();
+
+    var cellW = getCellWidth();
+    var sw = term.element.scrollWidth;
+    var vpW = window.innerWidth;
+    var expectedW = cellW * term.cols;
+    var suspect =
+      currentScale === 1 && term.cols > 0 && expectedW > vpW + 1; // expected wider than viewport but no zoom
+    if (suspect) {
+      flog('commit-SUSPECT', {
+        reason: reason,
+        attempts: attempts,
+        gate: gate,
+        preSnapScale: preSnapScale,
+        finalScale: currentScale,
+        cellW: cellW,
+        cols: term.cols,
+        expectedW: expectedW,
+        scrollWidth: sw,
+        vpWidth: vpW
+      });
+    }
+    repositionOverlay();
+  }
+
+`
diff --git a/mobile/src/terminal/terminal-webview-html/write-queue.ts b/mobile/src/terminal/terminal-webview-html/write-queue.ts
new file mode 100644
index 00000000000..ae8ed85297f
--- /dev/null
+++ b/mobile/src/terminal/terminal-webview-html/write-queue.ts
@@ -0,0 +1,110 @@
+// Also carries disposeTermObservers() and extractMouseModeScanTail(): both belong to
+// other concerns, but emitted-document order pins them inside this queue.
+export const TERMINAL_HTML_WRITE_QUEUE = `  function resetWriteQueue() {
+    writeQueue = [];
+    writeQueueHead = 0;
+  }
+
+  function isStatusDotPresentationSelector(value) {
+    return value === TEXT_PRESENTATION_SELECTOR || value === EMOJI_PRESENTATION_SELECTOR;
+  }
+
+  function endsWithStatusDotPresentationSequence(data) {
+    var i = data.length - 1;
+    while (i >= 0 && isStatusDotPresentationSelector(data.charAt(i))) i--;
+    return i >= 0 && data.charAt(i) === CLAUDE_STATUS_DOT;
+  }
+
+  // Why: iOS WebKit promotes Claude's record/status dot to a colorful emoji glyph.
+  function normalizeStatusDotPresentation(data) {
+    if (typeof data !== 'string' || data.length === 0) return data;
+    if (statusDotPendingSelector) {
+      statusDotPendingSelector = false;
+      var strippedPendingSelectors = false;
+      while (data.length > 0 && isStatusDotPresentationSelector(data.charAt(0))) data = data.slice(1);
+      strippedPendingSelectors = data.length === 0;
+      if (strippedPendingSelectors) {
+        statusDotPendingSelector = true;
+        return '';
+      }
+    }
+    var normalized = data.replace(CLAUDE_STATUS_DOT_PATTERN, CLAUDE_STATUS_DOT + TEXT_PRESENTATION_SELECTOR);
+    statusDotPendingSelector = endsWithStatusDotPresentationSequence(data);
+    return normalized;
+  }
+
+  function enqueueWrite(data) {
+    writeQueue.push(normalizeStatusDotPresentation(data));
+  }
+
+  function enqueueWriteBoundary(callback) {
+    writeQueue.push(callback);
+  }
+
+  function nextQueuedWrite() {
+    if (writeQueueHead >= writeQueue.length) {
+      resetWriteQueue();
+      return undefined;
+    }
+    var next = writeQueue[writeQueueHead];
+    writeQueueHead++;
+    // Why: high-throughput terminals can enqueue faster than xterm parses;
+    // compact consumed slots so drain work stays O(1) without retaining old chunks.
+    if (writeQueueHead > 128 && writeQueueHead * 2 > writeQueue.length) {
+      writeQueue = writeQueue.slice(writeQueueHead);
+      writeQueueHead = 0;
+    }
+    return next;
+  }
+
+  function disposeTermObservers() {
+    var disposables = termObserverDisposables;
+    termObserverDisposables = [];
+    for (var i = 0; i < disposables.length; i++) {
+      try { disposables[i] && disposables[i].dispose && disposables[i].dispose(); } catch (e) {}
+    }
+  }
+
+  function extractMouseModeScanTail(input) {
+    var start = Math.max(input.lastIndexOf(ESC), input.lastIndexOf(C1_CSI));
+    if (start === -1) return '';
+    var tail = input.slice(start);
+    // Why: PTY/SSH chunks can split a long combined DECSET before the final h/l.
+    // Keep parser state far beyond normal mode lists while still bounding memory.
+    if (tail.length > PRIVATE_MODE_SCAN_TAIL_LIMIT) return '';
+    if (tail === ESC || tail === ESC + '[' || tail === C1_CSI) return tail;
+    if (tail.indexOf(ESC + '[?') === 0) {
+      return /^[0-9;]*$/.test(tail.slice(3)) ? tail : '';
+    }
+    if (tail.indexOf(C1_CSI + '?') === 0) {
+      return /^[0-9;]*$/.test(tail.slice(2)) ? tail : '';
+    }
+    return '';
+  }
+
+  function pumpWrites(gen) {
+    if (!ready || !term || writesDraining || gen !== terminalGeneration) return;
+    var next = nextQueuedWrite();
+    if (typeof next !== 'string') {
+      if (typeof next === 'function') return next(), pumpWrites(gen);
+      var callbacks = afterDrainCallbacks;
+      afterDrainCallbacks = [];
+      for (var i = 0; i < callbacks.length; i++) callbacks[i]();
+      return;
+    }
+    writesDraining = true;
+    // Why: xterm.write() parses asynchronously. Row adjustment/resizing must
+    // wait until replayed SGR attributes have landed in the buffer.
+    term.write(next, function() {
+      if (gen !== terminalGeneration) return;
+      writesDraining = false;
+      pumpWrites(gen);
+    });
+  }
+
+  function afterWritesDrained(callback) {
+    afterDrainCallbacks.push(callback);
+    pumpWrites(terminalGeneration);
+  }
+
+`
diff --git a/mobile/src/terminal/terminal-webview-payload-hash.test.ts b/mobile/src/terminal/terminal-webview-payload-hash.test.ts
new file mode 100644
index 00000000000..f8bfa4bd134
--- /dev/null
+++ b/mobile/src/terminal/terminal-webview-payload-hash.test.ts
@@ -0,0 +1,17 @@
+import { createHash } from 'node:crypto'
+import { describe, expect, it } from 'vitest'
+import { XTERM_HTML } from './terminal-webview-html'
+
+// Why: every other WebView test exercises one slice of the document, so an edit to an
+// uncovered region ships silently. A diff here means the emitted WebView source changed —
+// update these values only when that change is deliberate, and only after checking the
+// document still runs. Refactors that merely move slice boundaries must leave them alone.
+const EXPECTED_SHA256 = '42cc000faddc3b58b8fd4855f848c7878f0cd6166c613f66d733645e8e1b9608'
+const EXPECTED_LENGTH = 729776
+
+describe('terminal WebView payload', () => {
+  it('composes the expected document', () => {
+    expect(XTERM_HTML.length).toBe(EXPECTED_LENGTH)
+    expect(createHash('sha256').update(XTERM_HTML, 'utf8').digest('hex')).toBe(EXPECTED_SHA256)
+  })
+})

From 80a52bb9b3fccd6c510bb1647c86fb7f19c8455b Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Tue, 1 Sep 2026 17:14:57 -0700
Subject: [PATCH 04/32] fix(git): recover commit ref badges on Git older than
 2.43 (#17923)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

GIT_HISTORY_COMMIT_FORMAT asked for decorations with %(decorate:…), which
Git 2.43 introduced. Older Git prints the placeholder verbatim and exits
zero, so nothing raised and every commit in the Source Control panel
silently lost its branch, remote and tag badges.

The record now also carries %D (Git 2.10) on its own line, selected by an
exact match against the unexpanded placeholder — a ref name can never
contain the \x1f that Git expands inside the echoed text. %n emits the %D
line on both sides of the boundary, so the message index is fixed and a
missed match degrades to no badges rather than a corrupted message.

The decoration separator is now bound to the field that produced the text
instead of sniffed from it. A lone decoration carries no separator, so the
old sniff split `refs/heads/feat,one` into two bogus refs.

Verified against real Git 2.38.1 and 2.49.1.

Co-authored-by: kaluli123123 <295758798+kaluli123123@users.noreply.github.com>
---
 docs/reference/git-compatibility.md         | 11 ++++++
 src/shared/git-binary-compatibility.test.ts | 26 ++++++++++++
 src/shared/git-history-log-parser.ts        | 33 +++++++++++-----
 src/shared/git-history.test.ts              | 44 ++++++++++++++++++++-
 4 files changed, 102 insertions(+), 12 deletions(-)

diff --git a/docs/reference/git-compatibility.md b/docs/reference/git-compatibility.md
index 3004b8888ab..0e8b1f257d3 100644
--- a/docs/reference/git-compatibility.md
+++ b/docs/reference/git-compatibility.md
@@ -42,6 +42,17 @@ authority.
 | `merge-tree-write-tree`     | Derive real-merge conflicts and no-op tree proofs                       | Omit the conflict summary and keep conservative branch cleanup behavior before Git 2.38                                                                                                                    |
 | `merge-tree-merge-base`     | Supply the already-resolved merge base                                  | Use the older two-commit `merge-tree --write-tree` form                                                                                                                                                    |
 
+### Placeholders That Fail Open
+
+`GitCapabilityCache` records commands Git *rejects*. A `git log --format`
+placeholder Git does not know is not rejected: Git echoes it verbatim and exits
+zero, so there is no error to remember and no probe to cache. Ask for both forms
+in one record and pick at parse time.
+
+| Placeholder      | Preferred behavior                                                                                | Compatibility behavior                                                                                     |
+| ---------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `%(decorate:…)`  | Git 2.43 separates commit decorations with `\x1f`, so ref names containing commas survive         | The same record also carries `%D` (Git 2.10); an unexpanded `%(decorate` placeholder selects it, at the cost of comma-splitting |
+
 ## Why Not `simple-git`
 
 `simple-git` is a process wrapper around the installed Git binary. Its custom
diff --git a/src/shared/git-binary-compatibility.test.ts b/src/shared/git-binary-compatibility.test.ts
index debab394649..3a8f562dff1 100644
--- a/src/shared/git-binary-compatibility.test.ts
+++ b/src/shared/git-binary-compatibility.test.ts
@@ -15,6 +15,7 @@ import {
   isUnsupportedWorktreeListZError
 } from './git-worktree-command-capabilities'
 import { gitCredentialPromptGuardEnv } from './git-credential-prompt-env'
+import { GIT_HISTORY_COMMIT_FORMAT, parseGitHistoryLog } from './git-history-log-parser'
 import {
   githubPullRequestHeadLocalRef,
   gitlabMergeRequestHeadLocalRef,
@@ -378,4 +379,29 @@ describeBinaryCompatibility('real Git binary compatibility', () => {
       runGit(['show', '--end-of-options', `${pinnedOid}:absent.txt`])
     ).rejects.toBeDefined()
   })
+  // Why pin this: an older Git echoes %(decorate:…) and exits zero, so only %D
+  // in the same record carries the badges (#15507). Asserts the echo and the recovery.
+  it('reads commit decorations on both sides of the %(decorate:...) boundary', async () => {
+    await writeFile(join(repoPath, 'decorated.txt'), 'decorated\n')
+    await runGit(['add', 'decorated.txt'])
+    await runGit(['commit', '-qm', 'decorated commit'])
+    await runGit(['tag', 'compat-decorated'])
+    const head = (await runGit(['rev-parse', 'HEAD'])).stdout.trim()
+
+    const log = await runGit([
+      'log',
+      `--format=${GIT_HISTORY_COMMIT_FORMAT}`,
+      '-z',
+      '--decorate=full',
+      '-n1',
+      head
+    ])
+
+    expect(log.stdout.includes('%(decorate')).toBe(!supports(2, 43))
+
+    const [item] = parseGitHistoryLog(log.stdout)
+    expect(item?.id).toBe(head)
+    expect(item?.subject).toBe('decorated commit')
+    expect(item?.references?.map((ref) => ref.id)).toContain('refs/tags/compat-decorated')
+  })
 })
diff --git a/src/shared/git-history-log-parser.ts b/src/shared/git-history-log-parser.ts
index 8f34002f0cc..ddc354513b9 100644
--- a/src/shared/git-history-log-parser.ts
+++ b/src/shared/git-history-log-parser.ts
@@ -2,9 +2,15 @@ import type { GitHistoryItem, GitHistoryItemRef } from './git-history-types'
 import { iterateNulDelimitedFields } from './nul-delimited-fields'
 
 const GIT_HISTORY_DECORATION_SEPARATOR = '\x1f'
+const GIT_HISTORY_LEGACY_DECORATION_SEPARATOR = ','
 
+// Why %D too: %(decorate:…) is Git 2.43+, and older Git echoes it verbatim and exits zero.
+// Callers must pass --decorate=full; both fields emit short names otherwise, which parse to no refs.
 export const GIT_HISTORY_COMMIT_FORMAT =
-  '%H%n%aN%n%aE%n%at%n%ct%n%P%n%(decorate:prefix=,suffix=,separator=%x1f)%n%B'
+  '%H%n%aN%n%aE%n%at%n%ct%n%P%n%(decorate:prefix=,suffix=,separator=%x1f)%n%D%n%B'
+
+// Why exact-match: no ref name may contain the \x1f an old Git echoes here.
+const UNEXPANDED_DECORATE_PLACEHOLDER = `%(decorate:prefix=,suffix=,separator=${GIT_HISTORY_DECORATION_SEPARATOR})`
 
 export function shortGitHash(hash: string): string {
   return hash.slice(0, 7)
@@ -15,17 +21,18 @@ function commitSubject(message: string): string {
   return firstLine || '(no commit message)'
 }
 
-function parseGitDecorationRefs(raw: string, revision: string): GitHistoryItemRef[] {
+function parseGitDecorationRefs(
+  raw: string,
+  revision: string,
+  separator: string
+): GitHistoryItemRef[] {
   if (!raw.trim()) {
     return []
   }
 
   const refs: GitHistoryItemRef[] = []
-  // Why: Git permits commas in ref names, so Orca's git log format uses a
-  // control-character separator that Git ref names cannot contain.
-  const parts = raw.includes(GIT_HISTORY_DECORATION_SEPARATOR)
-    ? raw.split(GIT_HISTORY_DECORATION_SEPARATOR)
-    : raw.split(',')
+  // Why passed in: a lone decoration carries no separator, so sniffing `raw` split `feat,one`.
+  const parts = raw.split(separator)
 
   for (const part of parts) {
     const ref = part.trim()
@@ -115,8 +122,10 @@ export function parseGitHistoryLog(stdout: string): GitHistoryItem[] {
     const authorEmail = lines[2] ?? ''
     const authorDateSeconds = Number.parseInt(lines[3] ?? '', 10)
     const parents = (lines[5] ?? '').trim()
-    const decorations = lines[6] ?? ''
-    const message = lines.slice(7).join('\n').replace(/\n$/, '')
+    const decorateField = lines[6] ?? ''
+    const isLegacyGit = decorateField === UNEXPANDED_DECORATE_PLACEHOLDER
+    const decorations = isLegacyGit ? (lines[7] ?? '') : decorateField
+    const message = lines.slice(8).join('\n').replace(/\n$/, '')
 
     items.push({
       id: hash,
@@ -127,7 +136,11 @@ export function parseGitHistoryLog(stdout: string): GitHistoryItem[] {
       authorEmail: authorEmail || undefined,
       displayId: shortGitHash(hash),
       timestamp: Number.isFinite(authorDateSeconds) ? authorDateSeconds * 1000 : undefined,
-      references: parseGitDecorationRefs(decorations, hash)
+      references: parseGitDecorationRefs(
+        decorations,
+        hash,
+        isLegacyGit ? GIT_HISTORY_LEGACY_DECORATION_SEPARATOR : GIT_HISTORY_DECORATION_SEPARATOR
+      )
     })
   }
   return items
diff --git a/src/shared/git-history.test.ts b/src/shared/git-history.test.ts
index 54aac202c71..617fa33c2ef 100644
--- a/src/shared/git-history.test.ts
+++ b/src/shared/git-history.test.ts
@@ -16,6 +16,7 @@ function logRecord({
   hash,
   parents = [],
   decorations = '',
+  legacyDecorations = '',
   message,
   author = 'Ada Lovelace',
   timestamp = 1_700_000_000
@@ -23,6 +24,7 @@ function logRecord({
   hash: string
   parents?: string[]
   decorations?: string
+  legacyDecorations?: string
   message: string
   author?: string
   timestamp?: number
@@ -35,6 +37,7 @@ function logRecord({
     String(timestamp),
     parents.join(' '),
     decorations,
+    legacyDecorations,
     message
   ].join('\n')}\0`
 }
@@ -94,8 +97,12 @@ describe('git history parsing', () => {
     const stdout = logRecord({
       hash: HEAD_OID,
       parents: [BASE_OID],
-      decorations:
-        'HEAD -> refs/heads/feature, refs/remotes/origin/HEAD -> refs/remotes/origin/feature, refs/remotes/origin/feature, tag: refs/tags/v1.0.0',
+      decorations: [
+        'HEAD -> refs/heads/feature',
+        'refs/remotes/origin/HEAD -> refs/remotes/origin/feature',
+        'refs/remotes/origin/feature',
+        'tag: refs/tags/v1.0.0'
+      ].join(DECORATION_SEPARATOR),
       message: 'feat: add graph\n\nbody line'
     })
 
@@ -117,6 +124,39 @@ describe('git history parsing', () => {
     ])
   })
 
+  it('falls back to %D decorations when Git predates the %(decorate:…) placeholder', () => {
+    // Why: Git < 2.43 echoes the placeholder and exits zero (#15507).
+    const stdout = logRecord({
+      hash: HEAD_OID,
+      decorations: `%(decorate:prefix=,suffix=,separator=${DECORATION_SEPARATOR})`,
+      legacyDecorations: 'HEAD -> refs/heads/feature, tag: refs/tags/v1.0.0',
+      message: 'feat: add graph'
+    })
+
+    const [item] = parseGitHistoryLog(stdout)
+
+    expect(item?.subject).toBe('feat: add graph')
+    expect(item?.references?.map((ref) => [ref.id, ref.name, ref.category])).toEqual([
+      ['refs/heads/feature', 'feature', 'branches'],
+      ['refs/tags/v1.0.0', 'v1.0.0', 'tags']
+    ])
+  })
+
+  it('keeps a comma inside a lone decoration, which carries no separator', () => {
+    // Why: a lone decoration carries no separator, so sniffing for \x1f split it in two.
+    const stdout = logRecord({
+      hash: HEAD_OID,
+      decorations: 'HEAD -> refs/heads/feat,one',
+      message: 'initial'
+    })
+
+    const [item] = parseGitHistoryLog(stdout)
+
+    expect(item?.references?.map((ref) => [ref.id, ref.name])).toEqual([
+      ['refs/heads/feat,one', 'feat,one']
+    ])
+  })
+
   it('preserves commas inside branch and tag decoration names', () => {
     const stdout = logRecord({
       hash: HEAD_OID,

From 1e82f66e80c6891d5e9296dd14e7512fcfe45fbb Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Tue, 1 Sep 2026 17:15:15 -0700
Subject: [PATCH 05/32] fix(agents): clear the unread completion marker when
 acknowledging agents (#17924)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Acknowledging is one action against two records, but only
clearTerminalPaneUnread cleared unreadAgentCompletionPanes. Acking from
the Activity page, the dashboard drawer or the popout bridge left the tab
dot, the ⌘J row and the floating-workspace dot lit with nothing left to
read; only the terminal-view auto-ack path cleared both.

Cleared inside the existing set so one ack is one commit, and only the
agent marker is touched — clearTerminalPaneUnread also drops
unreadTerminalPanes, which would silence a BEL the user never saw.

Refs #15445 (step 2 of that issue's fix; steps 1 and 3 remain open).

Co-authored-by: kaluli123123 <295758798+kaluli123123@users.noreply.github.com>
---
 .../slices/agent-status-ack-cleanup.test.ts   | 28 +++++++++++++++++++
 .../src/store/slices/ui-slice-test-harness.ts |  2 ++
 .../store/slices/ui/ui-slice-agent-actions.ts | 17 ++++++++++-
 3 files changed, 46 insertions(+), 1 deletion(-)

diff --git a/src/renderer/src/store/slices/agent-status-ack-cleanup.test.ts b/src/renderer/src/store/slices/agent-status-ack-cleanup.test.ts
index b763262a22d..4ca35b9bdc2 100644
--- a/src/renderer/src/store/slices/agent-status-ack-cleanup.test.ts
+++ b/src/renderer/src/store/slices/agent-status-ack-cleanup.test.ts
@@ -117,3 +117,31 @@ describe('acknowledgedAgentsByPaneKey cleanup on teardown', () => {
     expect(ackAt < newEntry.stateStartedAt).toBe(true)
   })
 })
+
+// Why: only the terminal-view path cleared unreadAgentCompletionPanes, so an
+// Activity-page ack left the tab dot lit.
+describe('acknowledgeAgents clears the unread agent-completion marker', () => {
+  it('drops the pane from unreadAgentCompletionPanes', () => {
+    const store = createTestStore()
+    store.getState().setAgentStatus('tab-1:0', { state: 'done', prompt: 'p', agentType: 'claude' })
+    store.getState().markAgentCompletionPaneUnread('tab-1:0')
+    expect(store.getState().unreadAgentCompletionPanes['tab-1:0']).toBe(true)
+
+    store.getState().acknowledgeAgents(['tab-1:0'])
+
+    expect(store.getState().unreadAgentCompletionPanes['tab-1:0']).toBeUndefined()
+  })
+
+  it('leaves other panes and the terminal-bell unread map untouched', () => {
+    const store = createTestStore()
+    store.getState().markAgentCompletionPaneUnread('tab-1:0')
+    store.getState().markAgentCompletionPaneUnread('tab-2:0')
+    store.getState().markTerminalPaneUnread('tab-1:0')
+
+    store.getState().acknowledgeAgents(['tab-1:0'])
+
+    expect(store.getState().unreadAgentCompletionPanes['tab-2:0']).toBe(true)
+    // Why: a BEL is a separate signal; acking the agent must not silence it.
+    expect(store.getState().unreadTerminalPanes['tab-1:0']).toBe(true)
+  })
+})
diff --git a/src/renderer/src/store/slices/ui-slice-test-harness.ts b/src/renderer/src/store/slices/ui-slice-test-harness.ts
index 318b24afef8..b8bbcf24b85 100644
--- a/src/renderer/src/store/slices/ui-slice-test-harness.ts
+++ b/src/renderer/src/store/slices/ui-slice-test-harness.ts
@@ -20,6 +20,8 @@ export function createUIStore(): StoreApi<AppState> {
     combinedDiffFileTreeWidth: 256,
     rightSidebarTab: 'explorer',
     rightSidebarExplorerView: 'files',
+    // Why: acknowledgeAgents clears the agent-completion marker the terminal slice owns.
+    unreadAgentCompletionPanes: {},
     ...createSettingsSearchState(args[0]),
     ...createWorktreeNavHistorySlice(...(args as Parameters<typeof createWorktreeNavHistorySlice>)),
     ...createUISlice(...(args as Parameters<typeof createUISlice>))
diff --git a/src/renderer/src/store/slices/ui/ui-slice-agent-actions.ts b/src/renderer/src/store/slices/ui/ui-slice-agent-actions.ts
index b1401e7d416..9fa15ffb81e 100644
--- a/src/renderer/src/store/slices/ui/ui-slice-agent-actions.ts
+++ b/src/renderer/src/store/slices/ui/ui-slice-agent-actions.ts
@@ -217,7 +217,16 @@ export function createUiAgentActions(
         const migrationUnsupported = Object.values(s.migrationUnsupportedByPtyId ?? {})
         // Why: only reallocate if an ack advances; compare prev<stamp not !== — the stamp ticks every ms and !== would rewrite the map every call.
         let next: Record<string, number> | null = null
+        // Why: one ack, two records — leaving the completion marker set keeps the tab dot,
+        // the ⌘J row and the floating-workspace dot lit with nothing left to read.
+        let nextUnreadCompletions: Record<string, true> | null = null
         for (const key of paneKeys) {
+          if (s.unreadAgentCompletionPanes[key]) {
+            if (nextUnreadCompletions === null) {
+              nextUnreadCompletions = { ...s.unreadAgentCompletionPanes }
+            }
+            delete nextUnreadCompletions[key]
+          }
           const prev = s.acknowledgedAgentsByPaneKey[key] ?? 0
           // Why not plain Date.now(): a remote/SSH execution host can stamp a turn ahead of this clock,
           // and every unread rule is `ackAt < turnTimestamp`. A behind-the-turn ack can never clear the
@@ -258,7 +267,13 @@ export function createUiAgentActions(
             next[key] = stamp
           }
         }
-        return next ? { acknowledgedAgentsByPaneKey: next } : s
+        if (!next && !nextUnreadCompletions) {
+          return s
+        }
+        return {
+          ...(next ? { acknowledgedAgentsByPaneKey: next } : {}),
+          ...(nextUnreadCompletions ? { unreadAgentCompletionPanes: nextUnreadCompletions } : {})
+        }
       })
       const notificationIds = [...notificationIdsToDismiss]
       if (notificationIds.length > 0 && typeof window !== 'undefined') {

From 519af49a589e2c95acfe972a844cecc4fcdaa00e Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Tue, 1 Sep 2026 17:04:44 -0700
Subject: [PATCH 06/32] fix(dev): keep the shared Electron dist writable for
 the dev app

pn dev crashes on macOS in any worktree that adopted the shared Electron dist.
publishSharedElectronDist marks the cache entry read-only, which hardlink
sharing needs, but clonefile preserves mode -- so the dist lands 0555, the dev
runner copies it into out/electron-dev unchanged, and the first plutil -replace
on Info.plist fails with a permission error. The shipped zip has that file at
0644; on disk it is 0555, so the mode is ours, not upstream's.

copyPrivateTree now restores write permission. Its contract is a private tree
the caller goes on to patch, and its one production caller is the dev runner.

The test that should have caught this ran the wrapper with stdio: 'ignore', so a
hard crash presented as a bare 20s timeout. It now captures the wrapper's output
into the failure message, and waits long enough for the two synchronous swiftc
builds and a codesign --deep over ~280MB that precede the assertion.
---
 config/scripts/space-sharing-copy.mjs         | 50 +++++++---
 config/scripts/space-sharing-copy.test.ts     | 35 +++++++
 .../startup/run-electron-vite-dev.test.ts     | 93 +++++++++++++------
 3 files changed, 139 insertions(+), 39 deletions(-)

diff --git a/config/scripts/space-sharing-copy.mjs b/config/scripts/space-sharing-copy.mjs
index 191bd8bffdc..01e9c8ac5ef 100644
--- a/config/scripts/space-sharing-copy.mjs
+++ b/config/scripts/space-sharing-copy.mjs
@@ -110,32 +110,60 @@ export function makeTreeReadOnly(targetPath, chmod = chmodSync) {
   chmod(targetPath, 0o755)
 }
 
+/**
+ * Restore owner write permission across a private copy.
+ *
+ * Counterpart to `makeTreeReadOnly`: clonefile, reflink and `cpSync` all carry the source's mode
+ * across, so a tree copied from the write-protected shared cache lands read-only and every patch
+ * the caller then makes -- `plutil -replace`, `codesign` -- fails with EACCES. Only the owner bit
+ * comes back; group and other stay as the source left them.
+ */
+export function makeTreeWritable(targetPath, chmod = chmodSync) {
+  for (const entry of readdirSync(targetPath, { withFileTypes: true })) {
+    const entryPath = join(targetPath, entry.name)
+    if (entry.isDirectory()) {
+      makeTreeWritable(entryPath, chmod)
+    } else if (!entry.isSymbolicLink()) {
+      const mode = statSync(entryPath, { throwIfNoEntry: false })?.mode
+      chmod(entryPath, mode === undefined ? 0o644 : mode | 0o200)
+    }
+  }
+  chmod(targetPath, 0o755)
+}
+
 /**
  * Share storage when possible, otherwise copy the bytes.
  *
  * Never hardlinks: this is for trees the caller goes on to patch, where shared inodes would write
- * through into the source.
+ * through into the source. The copy is unprotected on the way out for the same reason -- a private
+ * tree the caller cannot write to is useless to it.
  */
 export function copyPrivateTree(sourcePath, destinationPath, options = {}) {
   const platform = options.platform ?? process.platform
   const copy = options.copy ?? copyTreeVerbatim
+  const unprotect = options.unprotect ?? makeTreeWritable
   const privateMechanisms = new Set(['clone', 'reflink'])
+  let result = { mechanism: null, copyError: null }
   if (getShareMechanisms(platform).some((mechanism) => privateMechanisms.has(mechanism))) {
     try {
-      const mechanism = shareTree(sourcePath, destinationPath, {
-        ...options,
-        hardlink: () => {
-          throw new Error('hardlinks would not be private')
-        }
-      })
-      return { mechanism, copyError: null }
+      result = {
+        mechanism: shareTree(sourcePath, destinationPath, {
+          ...options,
+          hardlink: () => {
+            throw new Error('hardlinks would not be private')
+          }
+        }),
+        copyError: null
+      }
     } catch (copyError) {
       copy(sourcePath, destinationPath)
-      return { mechanism: null, copyError }
+      result = { mechanism: null, copyError }
     }
+  } else {
+    copy(sourcePath, destinationPath)
   }
-  copy(sourcePath, destinationPath)
-  return { mechanism: null, copyError: null }
+  unprotect(destinationPath)
+  return result
 }
 
 function copyTreeVerbatim(sourcePath, destinationPath) {
diff --git a/config/scripts/space-sharing-copy.test.ts b/config/scripts/space-sharing-copy.test.ts
index 3ce35aae25e..351f44b286e 100644
--- a/config/scripts/space-sharing-copy.test.ts
+++ b/config/scripts/space-sharing-copy.test.ts
@@ -19,6 +19,7 @@ import {
   copyPrivateTree,
   hardlinkTree,
   makeTreeReadOnly,
+  makeTreeWritable,
   shareTree
 } from './space-sharing-copy.mjs'
 
@@ -170,7 +171,41 @@ describe('makeTreeReadOnly', () => {
   )
 })
 
+describe('makeTreeWritable', () => {
+  it.runIf(process.platform !== 'win32')('undoes makeTreeReadOnly for the owner', () => {
+    const { source } = makeTree()
+    makeTreeReadOnly(source)
+    makeTreeWritable(source)
+    const file = path.join(source, 'nested', 'file')
+    expect(statSync(file).mode & 0o200).toBe(0o200)
+    expect(() => writeFileSync(file, 'mutated')).not.toThrow()
+  })
+
+  it.runIf(process.platform !== 'win32')('adds no write permission beyond the owner', () => {
+    const { source } = makeTree()
+    const executable = path.join(source, 'electron')
+    writeFileSync(executable, 'binary')
+    chmodSync(executable, 0o555)
+    makeTreeWritable(source)
+    expect(statSync(executable).mode & 0o777).toBe(0o755)
+  })
+})
+
 describe('copyPrivateTree', () => {
+  it.runIf(process.platform !== 'win32')(
+    'hands back a tree the caller can patch, even from a write-protected source',
+    () => {
+      const { root, source } = makeTree()
+      const destination = path.join(root, 'private')
+      makeTreeReadOnly(source)
+      copyPrivateTree(source, destination)
+      // The regression this guards: the shared Electron dist is read-only, clonefile/reflink/cpSync
+      // all carry that across, and `pn dev` then died patching the copied bundle's Info.plist.
+      expect(() => writeFileSync(path.join(destination, 'nested', 'file'), 'patched')).not.toThrow()
+      expect(readFileSync(path.join(source, 'nested', 'file'), 'utf8')).toBe('contents')
+    }
+  )
+
   it('never hardlinks, because the caller patches what it gets back', () => {
     const { root, source } = makeTree()
     const destination = path.join(root, 'private')
diff --git a/src/main/startup/run-electron-vite-dev.test.ts b/src/main/startup/run-electron-vite-dev.test.ts
index 2146563373d..73d1bb21cdc 100644
--- a/src/main/startup/run-electron-vite-dev.test.ts
+++ b/src/main/startup/run-electron-vite-dev.test.ts
@@ -105,6 +105,56 @@ function devWrapperTestEnv(extra: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
   return { ...env, ...extra }
 }
 
+/**
+ * What the two cases below wait on: a ~280MB clone of Electron.app, two swiftc
+ * helper builds, and `codesign --deep` over the result. Six seconds on an idle
+ * machine; the swiftc builds alone pass fifteen when this file runs inside the
+ * full suite and every core is taken. The generous ceiling only costs time on a
+ * run that is already failing.
+ */
+const PREPARE_TIMEOUT_MS = 90_000
+
+/**
+ * Spawns the wrapper with its output retained.
+ *
+ * Why retained: the wrapper reports its own failures on stderr, and discarding
+ * them turned a crash in prepare into a bare "Timed out waiting for condition"
+ * with nothing to act on.
+ */
+function spawnDevWrapper(
+  args: string[],
+  env: NodeJS.ProcessEnv
+): { wrapper: ChildProcess; readOutput: () => string } {
+  const wrapper = spawn(process.execPath, args, {
+    cwd: resolve('.'),
+    env,
+    stdio: ['ignore', 'pipe', 'pipe']
+  })
+  let output = ''
+  const collect = (chunk: Buffer): void => {
+    output += chunk.toString()
+  }
+  wrapper.stdout?.on('data', collect)
+  wrapper.stderr?.on('data', collect)
+  return { wrapper, readOutput: () => output }
+}
+
+async function waitForEnvFile(envFile: string, readOutput: () => string): Promise<void> {
+  try {
+    await waitFor(() => {
+      try {
+        return readFileSync(envFile, 'utf8').trim().length > 0
+      } catch {
+        return false
+      }
+    }, PREPARE_TIMEOUT_MS)
+  } catch (error) {
+    throw new Error(
+      `${(error as Error).message}: the dev wrapper never wrote ${envFile}. Wrapper output:\n${readOutput() || '(none)'}`
+    )
+  }
+}
+
 describe('run-electron-vite-dev', () => {
   afterEach(async () => {
     for (const pid of processesToCleanUp) {
@@ -351,26 +401,19 @@ describe('run-electron-vite-dev', () => {
       async function runWrapper(runId: string): Promise<{ electronExecPath: string }> {
         const pidFile = join(tempDir, `${runId}.pid`)
         const envFile = join(tempDir, `${runId}.json`)
-        const wrapper = spawn(process.execPath, [wrapperPath, '--remote-debugging-port=9448'], {
-          cwd: resolve('.'),
-          env: {
+        const { wrapper, readOutput } = spawnDevWrapper(
+          [wrapperPath, '--remote-debugging-port=9448'],
+          {
             ...baseEnv,
             ORCA_DEV_WRAPPER_TEST_PID_FILE: pidFile,
             ORCA_DEV_WRAPPER_TEST_ENV_FILE: envFile
-          },
-          stdio: 'ignore'
-        })
+          }
+        )
 
         expect(wrapper.pid).toBeTypeOf('number')
         processesToCleanUp.add(wrapper.pid!)
 
-        await waitFor(() => {
-          try {
-            return readFileSync(envFile, 'utf8').trim().length > 0
-          } catch {
-            return false
-          }
-        }, 20000)
+        await waitForEnvFile(envFile, readOutput)
 
         const trackedPids = trackPidFile(pidFile)
 
@@ -409,7 +452,8 @@ describe('run-electron-vite-dev', () => {
         }
       }
     },
-    30000
+    // Two full prepares, each budgeted at PREPARE_TIMEOUT_MS.
+    PREPARE_TIMEOUT_MS * 2 + 30_000
   )
 
   it.skipIf(process.platform !== 'darwin')(
@@ -421,9 +465,9 @@ describe('run-electron-vite-dev', () => {
       const wrapperPath = resolve('config/scripts/run-electron-vite-dev.mjs')
       const fakeCliPath = resolve('src/main/startup/__fixtures__/fake-electron-vite-dev-cli.mjs')
 
-      const wrapper = spawn(process.execPath, [wrapperPath, '--remote-debugging-port=9448'], {
-        cwd: resolve('.'),
-        env: devWrapperTestEnv({
+      const { wrapper, readOutput } = spawnDevWrapper(
+        [wrapperPath, '--remote-debugging-port=9448'],
+        devWrapperTestEnv({
           ORCA_ELECTRON_VITE_CLI: fakeCliPath,
           ORCA_SKIP_DEV_CLI_PREPARE: '1',
           ORCA_SKIP_DEV_WEB_PREPARE: '1',
@@ -431,20 +475,13 @@ describe('run-electron-vite-dev', () => {
           ORCA_DEV_WRAPPER_TEST_ENV_FILE: envFile,
           ORCA_DEV_BRANCH: 'feature/framework-symlinks',
           ORCA_DEV_WORKTREE_NAME: 'symlink-ui'
-        }),
-        stdio: 'ignore'
-      })
+        })
+      )
 
       expect(wrapper.pid).toBeTypeOf('number')
       processesToCleanUp.add(wrapper.pid!)
 
-      await waitFor(() => {
-        try {
-          return readFileSync(envFile, 'utf8').trim().length > 0
-        } catch {
-          return false
-        }
-      }, 20000)
+      await waitForEnvFile(envFile, readOutput)
 
       const trackedPids = trackPidFile(pidFile)
 
@@ -464,6 +501,6 @@ describe('run-electron-vite-dev', () => {
 
       await stopWrapperAndTrackedPids(wrapper, trackedPids)
     },
-    30000
+    PREPARE_TIMEOUT_MS + 30_000
   )
 })

From a2aea5d0b05db182ae1315f608dfc6d00fa487ed Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Tue, 1 Sep 2026 01:03:06 -0700
Subject: [PATCH 07/32] fix(persistence): sweep rows owned by deregistered repo
 ids at load

Deregistering a project stranded every row it owned. Each pruning path is
gated on the repo still being in `state.repos`, so once an id leaves the
catalogue its metadata, identity aliases, lineage and session rows became
unreachable forever -- and on a paired client they rendered as phantom
worktrees under an "Unknown" project.

Reconcile against the repo catalogue on load instead: any repo id that owns
rows but is absent from `state.repos` has its rows removed through the same
path `removeProject` uses. Host-independent and session-independent, because
an orphan has no owner that could object -- which is also why this reaches a
client's mirror of a remote host's session partition, something no local
removal can do.

Only a full `<repoId>::<path>` locator seeds the orphan set; bare keys can be
folder workspace ids or repo-keyed revisions, and guessing wrong there would
delete live state. `retiredWorktreeNamesByRepo` is deliberately untouched so a
re-added repo cannot reissue a name onto a cwd that still holds a prior
occupant's agent state.

Test fixtures that wrote worktree rows without registering their repo were
relying on orphans surviving a reload; they now register the repo they name.

Refs #17776
---
 .../profile-project-worktree-identity.ts      |  19 +-
 ...ence-cohort-and-identity-migration.test.ts |   2 +
 ...rsistence-cross-host-pane-identity.test.ts |   6 +
 ...sistence-deregistered-repo-residue.test.ts | 176 ++++++++++++++++++
 ...sistence-host-partitioned-sessions.test.ts |  10 +
 src/main/persistence-initial-load.test.ts     |   2 +
 ...sistence-native-chat-tab-view-mode.test.ts |   2 +-
 src/main/persistence-repo-lifecycle.test.ts   |   6 +-
 src/main/persistence-settings-update.test.ts  |   2 +-
 ...sistence-ssh-targets-and-pane-keys.test.ts |   4 +-
 ...tence-worktree-lineage-and-backups.test.ts |   3 +
 .../repo-lifecycle-operations.ts              |  50 +++++
 src/main/persistence/loading-store/store.ts   |  10 +-
 .../deregistered-repo-residue.ts              |  82 ++++++++
 .../ssh-reattach-pane-cardinality.test.ts     |  10 +-
 .../worktree-identity-persistence.test.ts     |  26 ++-
 16 files changed, 389 insertions(+), 21 deletions(-)
 create mode 100644 src/main/persistence-deregistered-repo-residue.test.ts
 create mode 100644 src/main/persistence/tracking-repos/deregistered-repo-residue.ts

diff --git a/src/main/orca-profiles/profile-project-worktree-identity.ts b/src/main/orca-profiles/profile-project-worktree-identity.ts
index 1586a0e0120..f4063cbb372 100644
--- a/src/main/orca-profiles/profile-project-worktree-identity.ts
+++ b/src/main/orca-profiles/profile-project-worktree-identity.ts
@@ -66,15 +66,18 @@ export function rekeyOwnerKey(
   return null
 }
 
-export function ownerKeyBelongsToRepo(ownerKey: string, repoId: string): boolean {
-  const rawOwnerKey = isWorktreeHostIdentity(ownerKey)
-    ? getWorktreeIdFromHostIdentity(ownerKey)
-    : ownerKey
-  if (isRepoWorktreeId(repoId, rawOwnerKey)) {
-    return true
+/** The worktree locator an owner key names, or null when the key is not worktree-scoped. */
+export function ownerKeyWorktreeId(ownerKey: string): string | null {
+  const scope = parseWorkspaceKey(ownerKey)
+  if (scope) {
+    return scope.type === 'worktree' ? scope.worktreeId : null
   }
-  const parsed = parseWorkspaceKey(ownerKey)
-  return parsed?.type === 'worktree' && isRepoWorktreeId(repoId, parsed.worktreeId)
+  return isWorktreeHostIdentity(ownerKey) ? getWorktreeIdFromHostIdentity(ownerKey) : ownerKey
+}
+
+export function ownerKeyBelongsToRepo(ownerKey: string, repoId: string): boolean {
+  const worktreeId = ownerKeyWorktreeId(ownerKey)
+  return worktreeId !== null && isRepoWorktreeId(repoId, worktreeId)
 }
 
 export function removeRepoWorktreeRecord<T>(
diff --git a/src/main/persistence-cohort-and-identity-migration.test.ts b/src/main/persistence-cohort-and-identity-migration.test.ts
index 4081672c821..a894b8a4c63 100644
--- a/src/main/persistence-cohort-and-identity-migration.test.ts
+++ b/src/main/persistence-cohort-and-identity-migration.test.ts
@@ -397,6 +397,8 @@ describe('Store.migrateWorktreeIdentity', () => {
 
   it('moves persisted mobile selections across reloads', async () => {
     const store = await createStore()
+    // Registered on purpose: rows owned by an unregistered repo id are swept as orphans on load.
+    store.addRepo(makeRepo({ id: 'repo1', path: '/repo1' }))
     store.setMobileClientTabSelections({
       'device-a': {
         [OLD]: { activeTabId: 'tab-1', activeGroupId: null, activeTabIdByGroupId: {} }
diff --git a/src/main/persistence-cross-host-pane-identity.test.ts b/src/main/persistence-cross-host-pane-identity.test.ts
index 2b6a70da934..479d3727837 100644
--- a/src/main/persistence-cross-host-pane-identity.test.ts
+++ b/src/main/persistence-cross-host-pane-identity.test.ts
@@ -10,6 +10,7 @@ import {
   createStore,
   writeDataFile,
   readDataFile,
+  makeRepo,
   makeTerminalTab
 } from './persistence-test-harness'
 
@@ -53,6 +54,11 @@ describe('cross-host pane identity migration', () => {
   it('refuses hostless alias and acknowledgement rewrites for a tab id two partitions share', async () => {
     writeDataFile({
       schemaVersion: 1,
+      // Registered on purpose: rows owned by an unregistered repo id are swept as orphans on load.
+      repos: [
+        makeRepo({ id: 'repo-local', path: '/repo-local' }),
+        makeRepo({ id: 'repo-a', path: '/repo-a' })
+      ],
       workspaceSession: makeLegacyPaneSession('repo-local', 'local-pty'),
       workspaceSessionsByHostId: {
         'ssh:host-a': makeLegacyPaneSession('repo-a', 'pty-a')
diff --git a/src/main/persistence-deregistered-repo-residue.test.ts b/src/main/persistence-deregistered-repo-residue.test.ts
new file mode 100644
index 00000000000..f1ecbde3213
--- /dev/null
+++ b/src/main/persistence-deregistered-repo-residue.test.ts
@@ -0,0 +1,176 @@
+// Why this file exists: deregistering a project used to strand every row it owned. No sweeper could
+// reach them -- the missing-directory prune is gated on the repo still being registered, and a
+// paired client's mirror of a remote host's rows is keyed by ids that client never registers, so the
+// owning host's removal never reached it (#17776).
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { rmSync, mkdtempSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { getDefaultWorkspaceSession } from '../shared/constants'
+import { composeWorktreeHostIdentity } from '../shared/worktree/host-qualified-identity'
+import { folderWorkspaceKey } from '../shared/workspace-scope'
+import type { PersistedState } from '../shared/persisted-state-types'
+import {
+  testState,
+  createStore,
+  writeDataFile,
+  readDataFile,
+  makeRepo,
+  makeTerminalTab
+} from './persistence-test-harness'
+
+vi.mock('./ssh/ssh-config-parser', () => ({
+  loadUserSshConfig: vi.fn(),
+  sshConfigHostsToTargets: vi.fn()
+}))
+
+vi.mock('electron', () => ({
+  app: { getPath: () => testState.dir },
+  safeStorage: { isEncryptionAvailable: () => false }
+}))
+
+vi.mock('./telemetry/client', () => ({ track: vi.fn() }))
+vi.mock('./telemetry/cohort-classifier', () => ({ getCohortAtEmit: vi.fn().mockReturnValue({}) }))
+
+const LIVE_REPO = 'live-repo'
+const GONE_REPO = 'gone-repo'
+const LIVE_WORKTREE = `${LIVE_REPO}::/workspace/live`
+const GONE_WORKTREE = `${GONE_REPO}::/workspace/orphan`
+const RUNTIME_HOST = 'runtime:env-a'
+
+const sessionFor = (worktreeId: string, tabId = 'tab-1') => ({
+  ...getDefaultWorkspaceSession(),
+  tabsByWorktree: {
+    [worktreeId]: [makeTerminalTab({ id: tabId, worktreeId })]
+  },
+  activeTabTypeByWorktree: { [worktreeId]: 'terminal' as const },
+  lastVisitedAtByWorktreeId: { [worktreeId]: 123 },
+  // The residue `profile-project-session-field-disposition` flags as leaking on repo removal.
+  sleepingAgentSessionsByPaneKey: {
+    [`${tabId}:leaf-1`]: {
+      paneKey: `${tabId}:leaf-1`,
+      tabId,
+      worktreeId,
+      agent: 'codex' as const,
+      providerSession: { key: 'session_id' as const, id: 'sess-1' },
+      prompt: 'sleeping',
+      state: 'waiting' as const,
+      capturedAt: 1,
+      updatedAt: 1,
+      origin: 'worktree-sleep' as const
+    }
+  }
+})
+
+describe('deregistered repo residue', () => {
+  beforeEach(() => {
+    testState.dir = mkdtempSync(join(tmpdir(), 'orca-orphan-sweep-'))
+  })
+
+  afterEach(() => {
+    rmSync(testState.dir, { recursive: true, force: true })
+  })
+
+  it('drops metadata, identity rows and sessions owned by an unregistered repo id', async () => {
+    const seed = await createStore()
+    seed.addRepo(makeRepo({ id: LIVE_REPO, path: '/workspace/live' }))
+    seed.addRepo(makeRepo({ id: GONE_REPO, path: '/workspace/orphan' }))
+    seed.setWorktreeMetaForHost(LIVE_WORKTREE, 'local', { displayName: 'Live' })
+    seed.setWorktreeMetaForHost(GONE_WORKTREE, 'local', { displayName: 'Orphan' })
+    seed.setWorkspaceSession(sessionFor(GONE_WORKTREE), 'local')
+    seed.flush()
+
+    // Deregister by hand: the point is that a row can outlive its repo however that happened.
+    const persisted = readDataFile() as PersistedState
+    persisted.repos = persisted.repos.filter((repo) => repo.id !== GONE_REPO)
+    writeDataFile(persisted)
+
+    const reloaded = await createStore()
+    reloaded.flush()
+    const swept = readDataFile() as PersistedState
+
+    expect(Object.keys(swept.worktreeMeta)).toEqual([LIVE_WORKTREE])
+    expect(swept.worktreeIdentityAliases).not.toHaveProperty(
+      composeWorktreeHostIdentity('local', GONE_WORKTREE)
+    )
+    expect(Object.keys(swept.worktreeMetaByIdentity ?? {})).toHaveLength(1)
+    const session = swept.workspaceSession
+    expect(session.tabsByWorktree).toEqual({})
+    expect(session.lastVisitedAtByWorktreeId).toEqual({})
+    expect(session.activeTabTypeByWorktree).toEqual({})
+    expect(session.sleepingAgentSessionsByPaneKey ?? {}).toEqual({})
+  })
+
+  it("sweeps a remote host's session partition the owning host's removal can never reach", async () => {
+    writeDataFile({
+      schemaVersion: 1,
+      repos: [makeRepo({ id: LIVE_REPO, path: '/workspace/live' })],
+      worktreeMeta: {},
+      workspaceSessionsByHostId: {
+        [RUNTIME_HOST]: sessionFor(GONE_WORKTREE)
+      }
+    })
+
+    const store = await createStore()
+    store.flush()
+
+    const partition = store.getWorkspaceSession(RUNTIME_HOST)
+    expect(partition.tabsByWorktree).toEqual({})
+    expect(partition.activeTabTypeByWorktree).toEqual({})
+  })
+
+  it('keeps rows for every registered repo, on any execution host', async () => {
+    const remoteWorktree = `${LIVE_REPO}::/home/user/remote`
+    writeDataFile({
+      schemaVersion: 1,
+      repos: [makeRepo({ id: LIVE_REPO, path: '/home/user/live', executionHostId: RUNTIME_HOST })],
+      worktreeMeta: { [remoteWorktree]: { hostId: RUNTIME_HOST, status: 'active' } },
+      workspaceSessionsByHostId: { [RUNTIME_HOST]: sessionFor(remoteWorktree) }
+    })
+
+    const store = await createStore()
+
+    expect(store.getWorktreeMeta(remoteWorktree)).toBeDefined()
+    const partition = store.getWorkspaceSession(RUNTIME_HOST)
+    expect(partition.tabsByWorktree[remoteWorktree]).toHaveLength(1)
+    // Also proves the sleeping-agent fixture is well-formed, so the sweep assertions above bite.
+    expect(Object.keys(partition.sleepingAgentSessionsByPaneKey ?? {})).toHaveLength(1)
+  })
+
+  it('leaves folder-workspace session rows alone: their keys name no repo', async () => {
+    const workspaceKey = folderWorkspaceKey('folder-1')
+    writeDataFile({
+      schemaVersion: 1,
+      repos: [],
+      worktreeMeta: {},
+      workspaceSession: {
+        ...getDefaultWorkspaceSession(),
+        lastVisitedAtByWorktreeId: { [workspaceKey]: 7 }
+      }
+    })
+
+    const store = await createStore()
+
+    expect(store.getWorkspaceSession('local').lastVisitedAtByWorktreeId).toEqual({
+      [workspaceKey]: 7
+    })
+  })
+
+  // Why: a sweep that dirtied every launch would rewrite the profile forever and mask real changes.
+  it('leaves a profile with no orphans byte-identical across reloads', async () => {
+    const seed = await createStore()
+    seed.addRepo(makeRepo({ id: LIVE_REPO, path: '/workspace/live' }))
+    seed.setWorktreeMetaForHost(LIVE_WORKTREE, 'local', { displayName: 'Live' })
+    seed.setWorkspaceSession(sessionFor(LIVE_WORKTREE), 'local')
+    seed.flush()
+
+    const canonicalizing = await createStore()
+    canonicalizing.flush()
+    const canonical = JSON.stringify(readDataFile())
+
+    const reloaded = await createStore()
+    reloaded.flush()
+
+    expect(JSON.stringify(readDataFile())).toBe(canonical)
+  })
+})
diff --git a/src/main/persistence-host-partitioned-sessions.test.ts b/src/main/persistence-host-partitioned-sessions.test.ts
index 023737ed386..aa2e46e52fd 100644
--- a/src/main/persistence-host-partitioned-sessions.test.ts
+++ b/src/main/persistence-host-partitioned-sessions.test.ts
@@ -123,6 +123,9 @@ describe('Store host-partitioned workspace sessions', () => {
     }
   })
 
+  // Registered on purpose: rows owned by an unregistered repo id are swept as orphans on load.
+  const makeRepos = (...repoIds: string[]) => repoIds.map((id) => makeRepo({ id, path: `/${id}` }))
+
   it('migrates a legacy workspaceSession blob into the local partition', async () => {
     writeDataFile({
       schemaVersion: 1,
@@ -194,6 +197,7 @@ describe('Store host-partitioned workspace sessions', () => {
     writeDataFile({
       schemaVersion: 1,
       workspaceSession: makeHostSession('local-repo'),
+      repos: makeRepos('repo-ssh'),
       workspaceSessionsByHostId: {
         'ssh:ssh-1': makeLegacyPaneHostSession('repo-ssh', 'remote-pty')
       },
@@ -224,6 +228,7 @@ describe('Store host-partitioned workspace sessions', () => {
     writeDataFile({
       schemaVersion: 1,
       workspaceSession: makeHostSession('local-repo'),
+      repos: makeRepos('repo-a', 'repo-b'),
       workspaceSessionsByHostId: {
         'ssh:host-a': makeLegacyPaneHostSession('repo-a', 'pty-a'),
         'ssh:host-b': makeLegacyPaneHostSession('repo-b', 'pty-b')
@@ -488,6 +493,7 @@ describe('Store host-partitioned workspace sessions', () => {
 
   it('removes one orphaned worktree with a host-scoped topology fence', async () => {
     const store = await createStore()
+    store.addRepo(makeRepo({ id: 'repo-gone', path: '/repo-gone' }))
     const worktreeId = 'repo-gone::/workspace/stale'
     const session = {
       ...makeHostSession('repo-gone'),
@@ -728,6 +734,7 @@ describe('Store host-partitioned workspace sessions', () => {
     const worktreeId = 'repo-1::/worktree'
     writeDataFile({
       schemaVersion: 1,
+      repos: makeRepos('repo-1'),
       workspaceSessionsByHostId: {
         'runtime:good': makeHostSession('good-repo'),
         // activeRepoId must be string|null; a number fails the zod parse.
@@ -753,6 +760,7 @@ describe('Store host-partitioned workspace sessions', () => {
     const worktreeId = 'repo-1::/worktree'
     writeDataFile({
       schemaVersion: 1,
+      repos: makeRepos('repo-1'),
       workspaceSession: {
         ...makeHostSession('local-repo'),
         // A projected/truncated write can leave a top-level field the wrong type;
@@ -813,6 +821,7 @@ describe('Store host-partitioned workspace sessions', () => {
     const worktreeId = 'repo-1::/worktree'
     const profile = await canonicalize({
       schemaVersion: 1,
+      repos: makeRepos('repo-1'),
       workspaceSession: {
         ...makeHostSession('local-repo'),
         tabsByWorktree: { [worktreeId]: [makeTerminalTab({ id: 'tab-keep', worktreeId })] }
@@ -845,6 +854,7 @@ describe('Store host-partitioned workspace sessions', () => {
     const worktreeId = 'repo-1::/worktree'
     const profile = await canonicalize({
       schemaVersion: 1,
+      repos: makeRepos('repo-1'),
       workspaceSessionsByHostId: {
         'runtime:env-a': {
           ...makeHostSession('runtime-repo'),
diff --git a/src/main/persistence-initial-load.test.ts b/src/main/persistence-initial-load.test.ts
index 6d0c0f11d5e..934ab44e1cb 100644
--- a/src/main/persistence-initial-load.test.ts
+++ b/src/main/persistence-initial-load.test.ts
@@ -150,6 +150,8 @@ describe('Store', () => {
 
   it('does not restore a terminal tab after its durable close flush returns', async () => {
     const store = await createStore()
+    // Registered on purpose: rows owned by an unregistered repo id are swept as orphans on load.
+    store.addRepo(makeRepo({ id: 'repo-1', path: '/repo-1' }))
     const worktreeId = 'repo-1::/tmp/worktree-1'
     const tabId = 'terminal-1'
     const session: WorkspaceSessionState = {
diff --git a/src/main/persistence-native-chat-tab-view-mode.test.ts b/src/main/persistence-native-chat-tab-view-mode.test.ts
index 3e3544c7495..9bcaab15494 100644
--- a/src/main/persistence-native-chat-tab-view-mode.test.ts
+++ b/src/main/persistence-native-chat-tab-view-mode.test.ts
@@ -58,7 +58,7 @@ describe('Store native-chat tab viewMode persistence', () => {
     const WORKTREE = 'repo1::/worktree'
     writeDataFile({
       schemaVersion: 1,
-      repos: [makeRepo()],
+      repos: [makeRepo({ id: 'repo1', path: '/repo1' })],
       worktreeMeta: {},
       settings: {},
       ui: {},
diff --git a/src/main/persistence-repo-lifecycle.test.ts b/src/main/persistence-repo-lifecycle.test.ts
index 1653f78297e..66f3fc2c32e 100644
--- a/src/main/persistence-repo-lifecycle.test.ts
+++ b/src/main/persistence-repo-lifecycle.test.ts
@@ -737,7 +737,10 @@ describe('Store', () => {
 
   it('reassignSshTargetId persists a worktree-meta-only re-point (no matching repo)', async () => {
     const store = await createStore()
-    // A meta on the old SSH host with no repo row — the re-point must still be persisted, not memory-only.
+    // A meta on the old SSH host with no repo row for that host — the re-point must still be
+    // persisted, not memory-only. The repo id stays registered so the load-time orphan sweep,
+    // which only reads repo ids, leaves the row alone.
+    store.addRepo(makeRepo({ id: 'r1', path: '/r1' }))
     store.setWorktreeMeta('r1::/remote/wt', { displayName: 'wt', hostId: 'ssh:ssh-old' })
 
     const repoIds = store.reassignSshTargetId('ssh-old', 'ssh-new')
@@ -787,6 +790,7 @@ describe('Store', () => {
 
   it('reassignSshTargetId re-keys a session partition stored under the old ssh host id', async () => {
     const store = await createStore()
+    store.addRepo(makeRepo({ id: 'r1', path: '/r1' }))
     store.setWorkspaceSession(
       {
         activeRepoId: null,
diff --git a/src/main/persistence-settings-update.test.ts b/src/main/persistence-settings-update.test.ts
index dc3a3c7ebb5..9af63ca7ccd 100644
--- a/src/main/persistence-settings-update.test.ts
+++ b/src/main/persistence-settings-update.test.ts
@@ -708,7 +708,7 @@ describe('Store', () => {
     }
     writeDataFile({
       schemaVersion: 1,
-      repos: [makeRepo()],
+      repos: [makeRepo({ id: 'repo1', path: '/repo1' })],
       worktreeMeta: {
         'repo1::/worktree-a': { status: 'active' },
         'repo1::/worktree-b': { status: 'active' }
diff --git a/src/main/persistence-ssh-targets-and-pane-keys.test.ts b/src/main/persistence-ssh-targets-and-pane-keys.test.ts
index 6c186ade077..c11ecbf0bc2 100644
--- a/src/main/persistence-ssh-targets-and-pane-keys.test.ts
+++ b/src/main/persistence-ssh-targets-and-pane-keys.test.ts
@@ -346,7 +346,7 @@ describe('Store', () => {
     const acknowledgedAt = 1_700_000_000_000
     writeDataFile({
       schemaVersion: 1,
-      repos: [makeRepo()],
+      repos: [makeRepo({ id: 'repo1', path: '/repo1' })],
       worktreeMeta: {},
       settings: {},
       ui: {
@@ -408,7 +408,7 @@ describe('Store', () => {
 
     writeDataFile({
       schemaVersion: 1,
-      repos: [makeRepo()],
+      repos: [makeRepo({ id: 'repo1', path: '/repo1' })],
       worktreeMeta: {},
       settings: {},
       ui: {
diff --git a/src/main/persistence-worktree-lineage-and-backups.test.ts b/src/main/persistence-worktree-lineage-and-backups.test.ts
index ef5e83745be..372e8b0e33b 100644
--- a/src/main/persistence-worktree-lineage-and-backups.test.ts
+++ b/src/main/persistence-worktree-lineage-and-backups.test.ts
@@ -166,6 +166,8 @@ describe('Store', () => {
   describe('mobileClientTabSelectionsByDeviceId', () => {
     it('persists device tab selections across reloads and drops malformed payloads', async () => {
       const store = await createStore()
+      // Registered on purpose: rows owned by an unregistered repo id are swept as orphans on load.
+      store.addRepo(makeRepo({ id: 'repo-1', path: '/repo-1' }))
       store.setMobileClientTabSelections({
         'device-a': {
           'repo-1::/tmp/wt': { activeTabId: 'tab-1', activeGroupId: 'g1', activeTabIdByGroupId: {} }
@@ -188,6 +190,7 @@ describe('Store', () => {
     it('prunes selections for a removed repo worktree', async () => {
       const store = await createStore()
       store.addRepo(makeRepo())
+      store.addRepo(makeRepo({ id: 'other-repo', path: '/other-repo' }))
       store.setMobileClientTabSelections({
         'device-a': {
           'r1::/tmp/wt': {
diff --git a/src/main/persistence/loading-store/repo-lifecycle-operations.ts b/src/main/persistence/loading-store/repo-lifecycle-operations.ts
index 095090ee1ca..c7bdbd9de37 100644
--- a/src/main/persistence/loading-store/repo-lifecycle-operations.ts
+++ b/src/main/persistence/loading-store/repo-lifecycle-operations.ts
@@ -12,10 +12,13 @@ import {
 import { mergeProjectHostSetupCompatibilityState } from '../tracking-repos/project-host-compatibility'
 import { RepoOrderPersistenceOperations } from '../tracking-repos/repo-order-operations'
 import { pruneWorktreeStateForRepo as pruneWorktreeStateForRepoOperation } from '../tracking-repos/repo-worktree-pruning'
+import { collectDeregisteredRepoIds } from '../tracking-repos/deregistered-repo-residue'
 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 { PersistedState } from '../../../shared/persisted-state-types'
+import { getRepoIdFromWorktreeId } from '../../../shared/worktree/id'
 
 import type { StoreRuntimeState } from './store-runtime-state'
 import type { WriteSchedulingOperations } from './write-scheduling'
@@ -129,6 +132,33 @@ export class RepoLifecycleOperations {
     scheduleSave(this[repoLifecycleOperationsContext].scheduling)
   }
 
+  /**
+   * Drop every persisted row owned by a repo id that is no longer registered.
+   *
+   * Runs at load because no removal path can: `removeProject` only fires while the repo is still in
+   * `state.repos`, and a paired client's mirror of a remote host's rows is keyed by ids that client
+   * never registers, so the owning host's removal never reaches it (#17776). An orphan has no owner
+   * that could object, so this ignores the session-ownership and local-execution-host gates the
+   * missing-directory sweeper needs.
+   */
+  sweepDeregisteredRepoResidue(): string[] {
+    const state = this[repoLifecycleOperationsContext].runtime.state
+    const orphanRepoIds = collectDeregisteredRepoIds(state)
+    if (orphanRepoIds.size === 0) {
+      return []
+    }
+    for (const repoId of orphanRepoIds) {
+      pruneWorktreeStateForRepo(this, repoId, null)
+      state.workspaceSession = removeRepoFromWorkspaceSession(state.workspaceSession, repoId)
+      state.workspaceSessionsByHostId = removeRepoFromHostWorkspaceSessions(
+        state.workspaceSessionsByHostId,
+        repoId
+      )
+    }
+    pruneDeregisteredRepoUiResidue(state.ui, orphanRepoIds)
+    return [...orphanRepoIds]
+  }
+
   updateRepo(
     id: string,
     updates: Partial<
@@ -212,6 +242,26 @@ export function pruneMobileClientTabSelections(
   }
 }
 
+function pruneDeregisteredRepoUiResidue(
+  ui: PersistedState['ui'],
+  orphanRepoIds: ReadonlySet<string>
+): void {
+  const isOrphanWorktree = (worktreeId: string): boolean =>
+    orphanRepoIds.has(getRepoIdFromWorktreeId(worktreeId))
+  if (ui.lastActiveRepoId && orphanRepoIds.has(ui.lastActiveRepoId)) {
+    ui.lastActiveRepoId = null
+  }
+  if (ui.lastActiveWorktreeId && isOrphanWorktree(ui.lastActiveWorktreeId)) {
+    ui.lastActiveWorktreeId = null
+  }
+  ui.filterRepoIds = ui.filterRepoIds?.filter((repoId) => !orphanRepoIds.has(repoId)) ?? []
+  for (const worktreeId of Object.keys(ui.showDotfilesByWorktree ?? {})) {
+    if (isOrphanWorktree(worktreeId)) {
+      delete ui.showDotfilesByWorktree?.[worktreeId]
+    }
+  }
+}
+
 export function getRepoUpdateOperations(
   owner: RepoLifecycleOperations
 ): RepoUpdatePersistenceOperations {
diff --git a/src/main/persistence/loading-store/store.ts b/src/main/persistence/loading-store/store.ts
index 888c0092ed2..017583e8f86 100644
--- a/src/main/persistence/loading-store/store.ts
+++ b/src/main/persistence/loading-store/store.ts
@@ -64,6 +64,9 @@ export class Store {
     )
     const adaptedProjectGroups = this.domains.adaptation.adaptFlatFolderScanProjectGroups()
     this.domains.adaptation.hydrateFolderWorkspaceDiffComments()
+    // Load is the only place an orphaned repo id can be swept: every removal path needs the repo to
+    // still be registered, so rows outlive their owner without one (#17776).
+    const sweptRepoIds = this.domains.repos.sweepDeregisteredRepoResidue()
     for (const entry of normalized.migrationUnsupportedEntries) {
       setMigrationUnsupportedPty(entry)
     }
@@ -78,7 +81,12 @@ export class Store {
       this.state.legacyPaneKeyAliasEntries = entries
       scheduleSave(this.domains.scheduling)
     })
-    if (normalized.changed || this.runtime.loadNeedsSave || adaptedProjectGroups) {
+    if (
+      normalized.changed ||
+      this.runtime.loadNeedsSave ||
+      adaptedProjectGroups ||
+      sweptRepoIds.length > 0
+    ) {
       scheduleSave(this.domains.scheduling)
     }
   }
diff --git a/src/main/persistence/tracking-repos/deregistered-repo-residue.ts b/src/main/persistence/tracking-repos/deregistered-repo-residue.ts
new file mode 100644
index 00000000000..60a77a7ed10
--- /dev/null
+++ b/src/main/persistence/tracking-repos/deregistered-repo-residue.ts
@@ -0,0 +1,82 @@
+import type { PersistedState } from '../../../shared/persisted-state-types'
+import { getWorktreeIdFromHostIdentity } from '../../../shared/worktree/host-qualified-identity'
+import { splitWorktreeId } from '../../../shared/worktree/id'
+import type { WorkspaceSessionState } from '../../../shared/workspace-session-state-types'
+import { SESSION_FIELDS_PRUNED_BY_OWNER_KEY } from '../../orca-profiles/profile-project-session-field-disposition'
+import { ownerKeyWorktreeId } from '../../orca-profiles/profile-project-worktree-identity'
+
+/**
+ * Repo ids that still own persisted rows but no longer appear in `state.repos`.
+ *
+ * Why nothing else finds them: every other sweeper is gated on the repo still being registered, so
+ * deregistering a project stranded the rows it owned permanently — including a paired client's
+ * mirror of a remote host's session partition, which no local repo removal can reach (#17776).
+ */
+export function collectDeregisteredRepoIds(state: PersistedState): Set<string> {
+  const liveRepoIds = new Set(state.repos.map((repo) => repo.id))
+  const orphanRepoIds = new Set<string>()
+  // Only a full `<repoId>::<path>` locator seeds the set. A bare key -- a folder workspace id, a
+  // repo-keyed topology revision, a test-shaped locator -- cannot be told apart from a repo id, and
+  // guessing wrong here deletes live session state.
+  const addWorktreeId = (worktreeId: string | null | undefined): void => {
+    const repoId = worktreeId ? splitWorktreeId(worktreeId)?.repoId : undefined
+    if (repoId && !liveRepoIds.has(repoId)) {
+      orphanRepoIds.add(repoId)
+    }
+  }
+  const addOwnerKey = (ownerKey: string): void => {
+    addWorktreeId(ownerKeyWorktreeId(ownerKey))
+  }
+
+  // Deliberately not seeded from `sparsePresetsByRepo` or `retiredWorktreeNamesByRepo`: both are
+  // bounded, and dropping a retired-name row would let a re-added repo reissue a name onto a cwd
+  // that still holds a prior occupant's agent state.
+  for (const worktreeId of Object.keys(state.worktreeMeta)) {
+    addWorktreeId(worktreeId)
+  }
+  for (const alias of Object.keys(state.worktreeIdentityAliases ?? {})) {
+    addWorktreeId(getWorktreeIdFromHostIdentity(alias))
+  }
+  for (const [childId, lineage] of Object.entries(state.worktreeLineageById)) {
+    addWorktreeId(childId)
+    addWorktreeId(lineage.parentWorktreeId)
+  }
+  for (const [childKey, lineage] of Object.entries(state.workspaceLineageByChildKey)) {
+    addOwnerKey(childKey)
+    addOwnerKey(lineage.parentWorkspaceKey)
+  }
+  for (const selections of Object.values(state.mobileClientTabSelectionsByDeviceId ?? {})) {
+    for (const worktreeId of Object.keys(selections)) {
+      addWorktreeId(worktreeId)
+    }
+  }
+  const sessions: (WorkspaceSessionState | undefined)[] = [
+    state.workspaceSession,
+    ...Object.values(state.workspaceSessionsByHostId ?? {})
+  ]
+  for (const session of sessions) {
+    if (!session) {
+      continue
+    }
+    for (const field of SESSION_FIELDS_PRUNED_BY_OWNER_KEY) {
+      for (const ownerKey of Object.keys(
+        (session[field] as Record<string, unknown> | undefined) ?? {}
+      )) {
+        addOwnerKey(ownerKey)
+      }
+    }
+    for (const ownerKey of Object.keys(session.tabsByWorktree ?? {})) {
+      addOwnerKey(ownerKey)
+    }
+    for (const ownerKey of Object.keys(session.browserTabsByWorktree ?? {})) {
+      addOwnerKey(ownerKey)
+    }
+    for (const record of Object.values(session.sleepingAgentSessionsByPaneKey ?? {})) {
+      addWorktreeId(record.worktreeId)
+    }
+    for (const tombstone of Object.values(session.terminalSurfaceTombstonesByPaneKey ?? {})) {
+      addWorktreeId(tombstone.worktreeId)
+    }
+  }
+  return orphanRepoIds
+}
diff --git a/src/main/ssh-reattach-pane-cardinality.test.ts b/src/main/ssh-reattach-pane-cardinality.test.ts
index 51cbdb26794..96362ffbfc2 100644
--- a/src/main/ssh-reattach-pane-cardinality.test.ts
+++ b/src/main/ssh-reattach-pane-cardinality.test.ts
@@ -2,7 +2,13 @@ import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
 import { rmSync, mkdtempSync } from 'node:fs'
 import { join } from 'node:path'
 import { tmpdir } from 'node:os'
-import { testState, createStore, makeTerminalTab, writeDataFile } from './persistence-test-harness'
+import {
+  testState,
+  createStore,
+  makeRepo,
+  makeTerminalTab,
+  writeDataFile
+} from './persistence-test-harness'
 import { TEST_LEAF_1, TEST_LEAF_2 } from './persistence-session-fixtures'
 import { getDefaultPersistedState } from '../shared/constants'
 
@@ -196,6 +202,8 @@ describe('STA-3077: an SSH reattach binds panes without grafting them back', ()
   it('does not clear and rebind a retired surface loaded from an older profile', async () => {
     const paneKey = `${TAB}:${TEST_LEAF_1}`
     const persisted = getDefaultPersistedState(testState.dir)
+    // Registered on purpose: rows owned by an unregistered repo id are swept as orphans on load.
+    persisted.repos = [makeRepo({ id: 'repo1', path: '/repo1' })]
     persisted.workspaceSession = {
       ...persisted.workspaceSession,
       ...sessionWithPane({ tabId: TAB, leafId: TEST_LEAF_1, ptyId: 'pty-1' }),
diff --git a/src/main/worktree-identity-persistence.test.ts b/src/main/worktree-identity-persistence.test.ts
index c66a2d72ce8..0b6dd178e84 100644
--- a/src/main/worktree-identity-persistence.test.ts
+++ b/src/main/worktree-identity-persistence.test.ts
@@ -5,12 +5,26 @@ import { tmpdir } from 'node:os'
 import type { PersistedState } from '../shared/persisted-state-types'
 import { canonicalWorktreeIdentity } from '../shared/worktree/identity'
 import { composeWorktreeHostIdentity } from '../shared/worktree/host-qualified-identity'
-import { createStore, readDataFile, testState, writeDataFile } from './persistence-test-harness'
+import type { Store } from './persistence/loading-store/store'
+import {
+  createStore,
+  makeRepo,
+  readDataFile,
+  testState,
+  writeDataFile
+} from './persistence-test-harness'
 
 describe('host-qualified worktree metadata', () => {
   const worktreeId = 'repo-1::/workspace/feature'
   const ROTATED_INSTANCE_ID = '44444444-4444-4444-8444-444444444444'
 
+  // Registered on purpose: rows owned by an unregistered repo id are swept as orphans on load.
+  const createStoreWithRepo = (): Store => {
+    const store = createStore()
+    store.addRepo(makeRepo({ id: 'repo-1', path: '/workspace' }))
+    return store
+  }
+
   beforeEach(() => {
     testState.dir = mkdtempSync(join(tmpdir(), 'orca-worktree-identity-'))
   })
@@ -52,7 +66,7 @@ describe('host-qualified worktree metadata', () => {
     })
   })
   it('reloads host-specific metadata without collapsing it to the legacy locator', () => {
-    const store = createStore()
+    const store = createStoreWithRepo()
     store.setWorktreeMetaForHost(worktreeId, 'local', { displayName: 'Local feature' })
     store.setWorktreeMetaForHost(worktreeId, 'ssh:build-box', { displayName: 'Remote feature' })
     store.flush()
@@ -72,7 +86,7 @@ describe('host-qualified worktree metadata', () => {
     expect(store.getWorktreeMetaForHost(worktreeId, 'local')?.comment).toBe('after')
   })
   it('backfills one stable instance for legacy metadata that omitted it', () => {
-    const seed = createStore()
+    const seed = createStoreWithRepo()
     seed.setWorktreeMeta(worktreeId, { displayName: 'Legacy feature' })
     seed.flush()
     const legacy = readDataFile() as PersistedState
@@ -97,7 +111,7 @@ describe('host-qualified worktree metadata', () => {
   // Fails open on purpose: an ambiguous alias used to brick reads and throw out of the worktree
   // listing loop, taking every workspace in the repo down with it and never self-healing.
   it('collapses an ambiguous locator onto its most recently active instance', () => {
-    const seed = createStore()
+    const seed = createStoreWithRepo()
     const first = seed.setWorktreeMetaForHost(worktreeId, 'local', { displayName: 'First' })
     seed.flush()
     const persisted = readDataFile() as PersistedState
@@ -262,7 +276,7 @@ describe('host-qualified worktree metadata', () => {
   it('repairs a missing canonical instance id while re-adopting an SSH target', () => {
     const oldHostId = 'ssh:old-target' as const
     const newHostId = 'ssh:new-target' as const
-    const seed = createStore()
+    const seed = createStoreWithRepo()
     seed.setWorktreeMetaForHost(worktreeId, oldHostId, { displayName: 'Remote feature' })
     seed.flush()
     const persisted = readDataFile() as PersistedState
@@ -318,7 +332,7 @@ describe('host-qualified worktree metadata', () => {
   it('deduplicates an equivalent destination during SSH target re-adoption', () => {
     const oldHostId = 'ssh:old-target' as const
     const newHostId = 'ssh:new-target' as const
-    const seed = createStore()
+    const seed = createStoreWithRepo()
     seed.setWorktreeMetaForHost(worktreeId, oldHostId, { displayName: 'Remote feature' })
     seed.flush()
     const persisted = readDataFile() as PersistedState

From 2f105b23d17d715bb648ae1809f8c43a3d30a0c6 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Tue, 1 Sep 2026 02:19:57 -0700
Subject: [PATCH 08/32] fix(persistence): sweep sleeping-agent-only residue and
 stop mis-seeding orphans

Review found three holes in the load-time sweep.

`sleepingAgentSessionsByPaneKey` and `terminalSurfaceTombstonesByPaneKey` are
pruned by the worktreeId they name, not by their own key, but
`pruneWorktreeStateForRepo` only collected owner keys from `worktreeMeta` and
`lastVisitedAtByWorktreeId`. An orphan whose only residue was a sleeping agent
therefore survived the sweep and re-seeded it on the next load, so the store
never self-cleared and every launch scheduled another save. Collect owner keys
from those records too, which fixes `removeProject` for the same shape.

`ownerKeyBelongsToRepo` is restored to its original body. Reordering its two
readings was not behavior-preserving as claimed: for a repo named `folder` or
`worktree`, checking the workspace-key reading first flips the result. The
census now uses `ownerKeyWorktreeIds`, which returns both readings, and seeds
only when neither names a live repo -- seeding one reading of a key whose
other reading is live would hand the removal pass a live row to delete.

Seed from `activeWorktreeId`, `activeWorkspaceKey` and
`activeWorktreeIdsOnShutdown`, which are pruned by bespoke rules and so were
reachable by no owner-key loop, and record why
`terminalTopologyRevisionByRepoId` stays excluded.

Refs #17776
---
 .../profile-project-worktree-identity.ts      | 31 ++++++++---
 ...sistence-deregistered-repo-residue.test.ts | 54 ++++++++++++++-----
 .../deregistered-repo-residue.ts              | 30 ++++++++++-
 .../tracking-repos/repo-worktree-pruning.ts   | 23 ++++++--
 4 files changed, 111 insertions(+), 27 deletions(-)

diff --git a/src/main/orca-profiles/profile-project-worktree-identity.ts b/src/main/orca-profiles/profile-project-worktree-identity.ts
index f4063cbb372..8cf58dd1bd5 100644
--- a/src/main/orca-profiles/profile-project-worktree-identity.ts
+++ b/src/main/orca-profiles/profile-project-worktree-identity.ts
@@ -66,18 +66,33 @@ export function rekeyOwnerKey(
   return null
 }
 
-/** The worktree locator an owner key names, or null when the key is not worktree-scoped. */
-export function ownerKeyWorktreeId(ownerKey: string): string | null {
+/**
+ * Every worktree locator an owner key could name.
+ *
+ * Two readings, because one key can be both: with a repo literally named `worktree`,
+ * `worktree::/p` is a `<repoId>::<path>` locator AND parses as a `worktree:` workspace key naming
+ * repo `` (empty). `ownerKeyBelongsToRepo` accepts either, so a caller that reasons about a key
+ * without a repo id in hand has to consider both or it will disagree with the predicate.
+ */
+export function ownerKeyWorktreeIds(ownerKey: string): string[] {
+  const rawOwnerKey = isWorktreeHostIdentity(ownerKey)
+    ? getWorktreeIdFromHostIdentity(ownerKey)
+    : ownerKey
   const scope = parseWorkspaceKey(ownerKey)
-  if (scope) {
-    return scope.type === 'worktree' ? scope.worktreeId : null
-  }
-  return isWorktreeHostIdentity(ownerKey) ? getWorktreeIdFromHostIdentity(ownerKey) : ownerKey
+  return scope?.type === 'worktree' && scope.worktreeId !== rawOwnerKey
+    ? [rawOwnerKey, scope.worktreeId]
+    : [rawOwnerKey]
 }
 
 export function ownerKeyBelongsToRepo(ownerKey: string, repoId: string): boolean {
-  const worktreeId = ownerKeyWorktreeId(ownerKey)
-  return worktreeId !== null && isRepoWorktreeId(repoId, worktreeId)
+  const rawOwnerKey = isWorktreeHostIdentity(ownerKey)
+    ? getWorktreeIdFromHostIdentity(ownerKey)
+    : ownerKey
+  if (isRepoWorktreeId(repoId, rawOwnerKey)) {
+    return true
+  }
+  const parsed = parseWorkspaceKey(ownerKey)
+  return parsed?.type === 'worktree' && isRepoWorktreeId(repoId, parsed.worktreeId)
 }
 
 export function removeRepoWorktreeRecord<T>(
diff --git a/src/main/persistence-deregistered-repo-residue.test.ts b/src/main/persistence-deregistered-repo-residue.test.ts
index f1ecbde3213..62d4aab957e 100644
--- a/src/main/persistence-deregistered-repo-residue.test.ts
+++ b/src/main/persistence-deregistered-repo-residue.test.ts
@@ -38,6 +38,21 @@ const LIVE_WORKTREE = `${LIVE_REPO}::/workspace/live`
 const GONE_WORKTREE = `${GONE_REPO}::/workspace/orphan`
 const RUNTIME_HOST = 'runtime:env-a'
 
+const sleepingAgentFor = (worktreeId: string, tabId = 'tab-1') => ({
+  [`${tabId}:leaf-1`]: {
+    paneKey: `${tabId}:leaf-1`,
+    tabId,
+    worktreeId,
+    agent: 'codex' as const,
+    providerSession: { key: 'session_id' as const, id: 'sess-1' },
+    prompt: 'sleeping',
+    state: 'waiting' as const,
+    capturedAt: 1,
+    updatedAt: 1,
+    origin: 'worktree-sleep' as const
+  }
+})
+
 const sessionFor = (worktreeId: string, tabId = 'tab-1') => ({
   ...getDefaultWorkspaceSession(),
   tabsByWorktree: {
@@ -46,20 +61,7 @@ const sessionFor = (worktreeId: string, tabId = 'tab-1') => ({
   activeTabTypeByWorktree: { [worktreeId]: 'terminal' as const },
   lastVisitedAtByWorktreeId: { [worktreeId]: 123 },
   // The residue `profile-project-session-field-disposition` flags as leaking on repo removal.
-  sleepingAgentSessionsByPaneKey: {
-    [`${tabId}:leaf-1`]: {
-      paneKey: `${tabId}:leaf-1`,
-      tabId,
-      worktreeId,
-      agent: 'codex' as const,
-      providerSession: { key: 'session_id' as const, id: 'sess-1' },
-      prompt: 'sleeping',
-      state: 'waiting' as const,
-      capturedAt: 1,
-      updatedAt: 1,
-      origin: 'worktree-sleep' as const
-    }
-  }
+  sleepingAgentSessionsByPaneKey: sleepingAgentFor(worktreeId, tabId)
 })
 
 describe('deregistered repo residue', () => {
@@ -156,6 +158,30 @@ describe('deregistered repo residue', () => {
     })
   })
 
+  // Regression: the pane-keyed records are pruned by the worktreeId they name, not by their own key,
+  // so an orphan whose ONLY residue is a sleeping agent survived -- and re-seeded the sweep on every
+  // launch, so the store never self-cleared and every load scheduled another save.
+  it("drops a sleeping agent that is the orphan repo's only residue, and self-clears", async () => {
+    writeDataFile({
+      schemaVersion: 1,
+      repos: [makeRepo({ id: LIVE_REPO, path: '/workspace/live' })],
+      worktreeMeta: {},
+      workspaceSession: {
+        ...getDefaultWorkspaceSession(),
+        sleepingAgentSessionsByPaneKey: sleepingAgentFor(GONE_WORKTREE)
+      }
+    })
+
+    const store = await createStore()
+    store.flush()
+    expect(store.getWorkspaceSession('local').sleepingAgentSessionsByPaneKey ?? {}).toEqual({})
+
+    // Self-clearing: with the residue gone nothing re-seeds the orphan id, so the next launch has
+    // no work. Before the fix this stayed non-empty forever and every load scheduled another save.
+    const reloaded = await createStore()
+    expect(reloaded.sweepDeregisteredRepoResidue()).toEqual([])
+  })
+
   // Why: a sweep that dirtied every launch would rewrite the profile forever and mask real changes.
   it('leaves a profile with no orphans byte-identical across reloads', async () => {
     const seed = await createStore()
diff --git a/src/main/persistence/tracking-repos/deregistered-repo-residue.ts b/src/main/persistence/tracking-repos/deregistered-repo-residue.ts
index 60a77a7ed10..c52bddbb712 100644
--- a/src/main/persistence/tracking-repos/deregistered-repo-residue.ts
+++ b/src/main/persistence/tracking-repos/deregistered-repo-residue.ts
@@ -3,7 +3,7 @@ import { getWorktreeIdFromHostIdentity } from '../../../shared/worktree/host-qua
 import { splitWorktreeId } from '../../../shared/worktree/id'
 import type { WorkspaceSessionState } from '../../../shared/workspace-session-state-types'
 import { SESSION_FIELDS_PRUNED_BY_OWNER_KEY } from '../../orca-profiles/profile-project-session-field-disposition'
-import { ownerKeyWorktreeId } from '../../orca-profiles/profile-project-worktree-identity'
+import { ownerKeyWorktreeIds } from '../../orca-profiles/profile-project-worktree-identity'
 
 /**
  * Repo ids that still own persisted rows but no longer appear in `state.repos`.
@@ -24,8 +24,21 @@ export function collectDeregisteredRepoIds(state: PersistedState): Set<string> {
       orphanRepoIds.add(repoId)
     }
   }
+  /**
+   * Seed from an owner key, which can read as two different locators (see `ownerKeyWorktreeIds`).
+   * All or nothing: if either reading names a live repo the key is that repo's, and seeding the
+   * other reading would hand the removal pass -- which accepts either -- a live row to delete.
+   */
   const addOwnerKey = (ownerKey: string): void => {
-    addWorktreeId(ownerKeyWorktreeId(ownerKey))
+    const repoIds = ownerKeyWorktreeIds(ownerKey).flatMap((worktreeId) => {
+      const repoId = splitWorktreeId(worktreeId)?.repoId
+      return repoId ? [repoId] : []
+    })
+    if (repoIds.length > 0 && repoIds.every((repoId) => !liveRepoIds.has(repoId))) {
+      for (const repoId of repoIds) {
+        orphanRepoIds.add(repoId)
+      }
+    }
   }
 
   // Deliberately not seeded from `sparsePresetsByRepo` or `retiredWorktreeNamesByRepo`: both are
@@ -71,6 +84,19 @@ export function collectDeregisteredRepoIds(state: PersistedState): Set<string> {
     for (const ownerKey of Object.keys(session.browserTabsByWorktree ?? {})) {
       addOwnerKey(ownerKey)
     }
+    // Pruned by bespoke rules rather than by owner key, so the loop above never reaches them.
+    for (const ownerKey of [
+      session.activeWorktreeId,
+      session.activeWorkspaceKey,
+      ...(session.activeWorktreeIdsOnShutdown ?? [])
+    ]) {
+      if (ownerKey) {
+        addOwnerKey(ownerKey)
+      }
+    }
+    // Not seeded from `terminalTopologyRevisionByRepoId`: its keys are bare repo ids by contract,
+    // and a bare key is exactly what `addWorktreeId` refuses to trust. Rows there are removed once
+    // any locator seeds their repo id, which every repo that ever opened a terminal has.
     for (const record of Object.values(session.sleepingAgentSessionsByPaneKey ?? {})) {
       addWorktreeId(record.worktreeId)
     }
diff --git a/src/main/persistence/tracking-repos/repo-worktree-pruning.ts b/src/main/persistence/tracking-repos/repo-worktree-pruning.ts
index f6d17b24aa2..a41f7c6319d 100644
--- a/src/main/persistence/tracking-repos/repo-worktree-pruning.ts
+++ b/src/main/persistence/tracking-repos/repo-worktree-pruning.ts
@@ -2,6 +2,7 @@ import type { WorkspaceKey } from '../../../shared/folder-workspace-types'
 import { LOCAL_EXECUTION_HOST_ID, type ExecutionHostId } from '../../../shared/execution-host'
 import { parseWorkspaceKey } from '../../../shared/workspace-scope'
 import type { PersistedState } from '../../../shared/persisted-state-types'
+import type { WorkspaceSessionState } from '../../../shared/workspace-session-state-types'
 import { removeWorkspaceSessionOwners } from '../restoring-sessions/session-owner-removal'
 import {
   getExecutionHostIdFromWorktreeHostIdentity,
@@ -58,10 +59,26 @@ export function pruneWorktreeStateForRepo(
       }
     }
   }
-  collectPrefixedKeys(Object.keys(state.worktreeMeta))
-  collectPrefixedKeys(Object.keys(state.workspaceSession?.lastVisitedAtByWorktreeId ?? {}))
-  for (const session of Object.values(state.workspaceSessionsByHostId ?? {})) {
+  // Why the pane-keyed records contribute owner keys: they are pruned by the worktreeId they name,
+  // not by their own key, so a worktree with no meta and no visit row would otherwise keep its
+  // sleeping agents and tombstones forever -- and keep re-seeding the orphan sweep every load.
+  const collectScannedRecordOwners = (session: WorkspaceSessionState | undefined): void => {
     collectPrefixedKeys(Object.keys(session?.lastVisitedAtByWorktreeId ?? {}))
+    collectPrefixedKeys(
+      Object.values(session?.sleepingAgentSessionsByPaneKey ?? {}).map(
+        (record) => record.worktreeId
+      )
+    )
+    collectPrefixedKeys(
+      Object.values(session?.terminalSurfaceTombstonesByPaneKey ?? {}).map(
+        (tombstone) => tombstone.worktreeId
+      )
+    )
+  }
+  collectPrefixedKeys(Object.keys(state.worktreeMeta))
+  collectScannedRecordOwners(state.workspaceSession)
+  for (const session of Object.values(state.workspaceSessionsByHostId ?? {})) {
+    collectScannedRecordOwners(session)
   }
 
   for (const key of Object.keys(state.worktreeMeta)) {

From 87f3e907ddd72abd390897060d6e21d7471d9f51 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Tue, 1 Sep 2026 02:49:04 -0700
Subject: [PATCH 09/32] test(persistence): assert the sleeping-agent cleanup
 reached disk

The self-clearing check loaded a second store, but that constructor runs the
sweep itself. If the first flush had not persisted the cleanup, the second load
would have redone it in memory and the assertion would have passed without
meaning anything. Read the profile back and assert the map is empty there first.

Refs #17776
---
 src/main/persistence-deregistered-repo-residue.test.ts | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/src/main/persistence-deregistered-repo-residue.test.ts b/src/main/persistence-deregistered-repo-residue.test.ts
index 62d4aab957e..03db3ed14fc 100644
--- a/src/main/persistence-deregistered-repo-residue.test.ts
+++ b/src/main/persistence-deregistered-repo-residue.test.ts
@@ -175,6 +175,10 @@ describe('deregistered repo residue', () => {
     const store = await createStore()
     store.flush()
     expect(store.getWorkspaceSession('local').sleepingAgentSessionsByPaneKey ?? {}).toEqual({})
+    // On disk, not just in memory: if the flush had not persisted the cleanup, the next load would
+    // silently redo it and the self-clearing assertion below would pass without meaning anything.
+    const persisted = readDataFile() as PersistedState
+    expect(persisted.workspaceSession.sleepingAgentSessionsByPaneKey ?? {}).toEqual({})
 
     // Self-clearing: with the residue gone nothing re-seeds the orphan id, so the next launch has
     // no work. Before the fix this stayed non-empty forever and every load scheduled another save.

From 1a11f82fcc22dc613947449d285220cab0885f06 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Tue, 1 Sep 2026 17:04:49 -0700
Subject: [PATCH 10/32] test(persistence): cover each session scalar as an
 orphan's only residue

`activeWorktreeId`, `activeWorkspaceKey` and `activeWorktreeIdsOnShutdown` are
pruned by bespoke rules rather than by owner key, so no owner-key loop reaches
them and each has to be able to seed the sweep alone. The sweep already handles
all three -- the census seeds from them and `removeRepoFromWorkspaceSession`
clears them -- but nothing pinned it, and dropping that seeding turns all three
cases red.

The `activeWorkspaceKey` case uses the canonical `worktree:<id>` form, so it
also covers unwrapping the workspace key before the repo id is visible.

Refs #17776
---
 ...sistence-deregistered-repo-residue.test.ts | 36 ++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

diff --git a/src/main/persistence-deregistered-repo-residue.test.ts b/src/main/persistence-deregistered-repo-residue.test.ts
index 03db3ed14fc..3a7a3372b3c 100644
--- a/src/main/persistence-deregistered-repo-residue.test.ts
+++ b/src/main/persistence-deregistered-repo-residue.test.ts
@@ -8,7 +8,7 @@ import { join } from 'node:path'
 import { tmpdir } from 'node:os'
 import { getDefaultWorkspaceSession } from '../shared/constants'
 import { composeWorktreeHostIdentity } from '../shared/worktree/host-qualified-identity'
-import { folderWorkspaceKey } from '../shared/workspace-scope'
+import { folderWorkspaceKey, worktreeWorkspaceKey } from '../shared/workspace-scope'
 import type { PersistedState } from '../shared/persisted-state-types'
 import {
   testState,
@@ -186,6 +186,40 @@ describe('deregistered repo residue', () => {
     expect(reloaded.sweepDeregisteredRepoResidue()).toEqual([])
   })
 
+  // The session scalars are pruned by bespoke rules, not by owner key, so no owner-key loop reaches
+  // them. Each has to be able to seed the sweep on its own or an orphan named only there is stuck.
+  it.each([
+    { label: 'activeWorktreeId', session: { activeWorktreeId: GONE_WORKTREE } },
+    // Canonical `worktree:<id>` form, which needs unwrapping before the repo id is visible.
+    {
+      label: 'activeWorkspaceKey',
+      session: { activeWorkspaceKey: worktreeWorkspaceKey(GONE_WORKTREE) }
+    },
+    {
+      label: 'activeWorktreeIdsOnShutdown',
+      session: { activeWorktreeIdsOnShutdown: [GONE_WORKTREE] }
+    }
+  ])("clears $label when it is the orphan repo's only residue", async ({ session }) => {
+    writeDataFile({
+      schemaVersion: 1,
+      repos: [makeRepo({ id: LIVE_REPO, path: '/workspace/live' })],
+      worktreeMeta: {},
+      workspaceSessionsByHostId: {
+        [RUNTIME_HOST]: { ...getDefaultWorkspaceSession(), ...session }
+      }
+    })
+
+    const store = await createStore()
+    store.flush()
+
+    const partition = store.getWorkspaceSession(RUNTIME_HOST)
+    expect(partition.activeWorktreeId ?? null).toBeNull()
+    expect(partition.activeWorkspaceKey ?? null).toBeNull()
+    expect(partition.activeWorktreeIdsOnShutdown ?? []).toEqual([])
+    const reloaded = await createStore()
+    expect(reloaded.sweepDeregisteredRepoResidue()).toEqual([])
+  })
+
   // Why: a sweep that dirtied every launch would rewrite the profile forever and mask real changes.
   it('leaves a profile with no orphans byte-identical across reloads', async () => {
     const seed = await createStore()

From ff8b4d08ab98c8a4d8cabcadcbfe9628924b9995 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Tue, 1 Sep 2026 01:11:21 -0700
Subject: [PATCH 11/32] fix(runtime): sweep missing local worktree metadata on
 the host that owns it

`pruneMetadataMissingFromAuthoritativeLocalScan` had exactly one caller:
`ipcMain.handle('worktrees:listAll')`. A headless runtime host has no
renderer, so it never ran, and that host's `worktreeMeta` grew without bound
even for its own local repos -- 129 of 139 rows dangling on the profile in
#17776.

Run it from the runtime's own detected listing instead. That is the same
trigger on the same evidence: `listDetected` already prunes lineage on an
authoritative scan, and a paired client refreshing a remote repo calls
`worktree.detectedList`, so the host now sweeps exactly when the desktop
would have.

The expectation is captured before the scan, because listing can mutate
metadata synchronously before its first await. WSL-routed repos are excluded
for the reason the desktop listing excludes them: the listing runs in the
distro and reports Linux paths while metadata can hold UNC ones, and v1
cannot prove those aliases equivalent. A runtime needing repair throws rather
than resolving routing, which is likewise no basis for deleting rows.

The prune's own gates still apply, so an SSH- or otherwise off-host repo is
never swept from a local stat -- the execution host owns that verdict.

Refs #17776
---
 ...me-managed-worktree-metadata-sweep.test.ts | 117 ++++++++++++++++++
 .../runtime-managed-worktree-queries.ts       |  44 +++++++
 src/main/runtime/runtime-store-contract.ts    |   3 +
 3 files changed, 164 insertions(+)
 create mode 100644 src/main/runtime/runtime-managed-worktree-metadata-sweep.test.ts

diff --git a/src/main/runtime/runtime-managed-worktree-metadata-sweep.test.ts b/src/main/runtime/runtime-managed-worktree-metadata-sweep.test.ts
new file mode 100644
index 00000000000..12d5d71e7e0
--- /dev/null
+++ b/src/main/runtime/runtime-managed-worktree-metadata-sweep.test.ts
@@ -0,0 +1,117 @@
+// Why this file exists: the authoritative missing-metadata prune had exactly one caller,
+// `ipcMain.handle('worktrees:listAll')`. A headless runtime host has no renderer, so it never swept
+// its own repos and their `worktreeMeta` rows grew without bound (#17776).
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import type { GitWorktreeInfo } from '../../shared/worktree/types'
+import type { Repo } from '../../shared/repo-types'
+import { testState, createStore, makeRepo } from '../persistence-test-harness'
+import type { Store } from '../persistence/loading-store/store'
+import { RuntimeManagedWorktreeQueries } from './runtime-managed-worktree-queries'
+import type { RuntimeStore } from './runtime-store-contract'
+
+vi.mock('./ssh/ssh-config-parser', () => ({
+  loadUserSshConfig: vi.fn(),
+  sshConfigHostsToTargets: vi.fn()
+}))
+
+vi.mock('electron', () => ({
+  app: { getPath: () => testState.dir },
+  safeStorage: { isEncryptionAvailable: () => false }
+}))
+
+vi.mock('./telemetry/client', () => ({ track: vi.fn() }))
+vi.mock('./telemetry/cohort-classifier', () => ({ getCohortAtEmit: vi.fn().mockReturnValue({}) }))
+
+const gitWorktree = (path: string): GitWorktreeInfo => ({
+  path,
+  branch: 'main',
+  head: 'abc1234',
+  isBare: false,
+  isMainWorktree: true
+})
+
+function queries(
+  store: Store,
+  repo: Repo,
+  worktrees: readonly GitWorktreeInfo[],
+  ok = true
+): RuntimeManagedWorktreeQueries {
+  return new RuntimeManagedWorktreeQueries({
+    getStore: () => store as unknown as RuntimeStore,
+    listResolved: async () => [],
+    resolveRepo: async () => repo,
+    selectRepos: () => [repo],
+    scanRepo: async () => ({ ok, worktrees: [...worktrees] })
+  })
+}
+
+describe('runtime detected-worktree listing sweeps missing local metadata', () => {
+  let repoPath = ''
+
+  beforeEach(() => {
+    testState.dir = mkdtempSync(join(tmpdir(), 'orca-runtime-sweep-'))
+    repoPath = join(testState.dir, 'repo')
+    mkdirSync(repoPath, { recursive: true })
+  })
+
+  afterEach(() => {
+    rmSync(testState.dir, { recursive: true, force: true })
+  })
+
+  it('drops a metadata row whose directory is gone and the scan does not list', async () => {
+    const store = createStore()
+    const repo = makeRepo({ id: 'repo-1', path: repoPath })
+    store.addRepo(repo)
+    const missingId = `${repo.id}::${join(testState.dir, 'deleted-worktree')}`
+    store.setWorktreeMetaForHost(missingId, 'local', { displayName: 'Gone' })
+    expect(store.getWorktreeMeta(missingId)).toBeDefined()
+
+    await queries(store, repo, [gitWorktree(repoPath)]).listDetected(repo)
+
+    expect(store.getWorktreeMeta(missingId)).toBeUndefined()
+  })
+
+  it('keeps a row whose directory still exists', async () => {
+    const store = createStore()
+    const repo = makeRepo({ id: 'repo-1', path: repoPath })
+    store.addRepo(repo)
+    const livePath = join(testState.dir, 'live-worktree')
+    mkdirSync(livePath, { recursive: true })
+    const liveId = `${repo.id}::${livePath}`
+    store.setWorktreeMetaForHost(liveId, 'local', { displayName: 'Live' })
+
+    await queries(store, repo, [gitWorktree(repoPath)]).listDetected(repo)
+
+    expect(store.getWorktreeMeta(liveId)).toBeDefined()
+  })
+
+  // A non-authoritative scan is a failed listing, which is no evidence any checkout is gone.
+  it('keeps every row when the scan is not authoritative', async () => {
+    const store = createStore()
+    const repo = makeRepo({ id: 'repo-1', path: repoPath })
+    store.addRepo(repo)
+    const missingId = `${repo.id}::${join(testState.dir, 'deleted-worktree')}`
+    store.setWorktreeMetaForHost(missingId, 'local', { displayName: 'Gone' })
+
+    await queries(store, repo, [], false).listDetected(repo)
+
+    expect(store.getWorktreeMeta(missingId)).toBeDefined()
+  })
+
+  // The execution host owns this verdict: a runtime host cannot stat an SSH checkout, so a local
+  // miss is not evidence of absence. See docs/reference/ssh-execution-boundary.md.
+  it('never sweeps a repo whose git runs off-host', async () => {
+    const store = createStore()
+    const repo = makeRepo({ id: 'repo-1', path: repoPath, connectionId: 'build-box' })
+    store.addRepo(repo)
+    const missingId = `${repo.id}::${join(testState.dir, 'deleted-worktree')}`
+    store.setWorktreeMetaForHost(missingId, 'ssh:build-box', { displayName: 'Gone' })
+
+    await queries(store, repo, [gitWorktree(repoPath)]).listDetected(repo)
+
+    expect(store.getWorktreeMetaForHost(missingId, 'ssh:build-box')).toBeDefined()
+  })
+})
diff --git a/src/main/runtime/runtime-managed-worktree-queries.ts b/src/main/runtime/runtime-managed-worktree-queries.ts
index d444f024e84..b0ed2bc4a3b 100644
--- a/src/main/runtime/runtime-managed-worktree-queries.ts
+++ b/src/main/runtime/runtime-managed-worktree-queries.ts
@@ -20,6 +20,10 @@ import {
 } from '../../shared/worktree/visibility-sources'
 import { mergeWorktree } from '../ipc/worktree-logic'
 import { pruneLineageForMissingRepoWorktrees } from '../worktree-lineage-pruning'
+import { pruneMetadataMissingFromAuthoritativeLocalScan } from '../ipc/worktrees/listing/authoritative-local-worktree-metadata-pruning'
+import type { NativeLocalWorktreeMetadataScanExpectation } from '../persistence/tracking-repos/missing-local-worktree-metadata-pruning'
+import { getLocalWorktreeScanGeneration } from '../local-worktree-scan-generation'
+import { getLocalProjectWorktreeGitOptions } from '../project-runtime-git-options'
 import type { Store } from '../persistence'
 import type { RuntimeStore } from './runtime-store-contract'
 import type { RuntimeWorktreeScanResult } from './repo-worktree-resolution-scan'
@@ -36,6 +40,31 @@ type Dependencies = {
   scanRepo(repo: Repo): Promise<RuntimeWorktreeScanResult>
 }
 
+/**
+ * The destructive scan expectation for one repo, or undefined when this repo must not carry one.
+ *
+ * WSL-routed repos are excluded for the same reason the desktop listing excludes them: the listing
+ * runs in the distro and reports Linux paths while metadata can hold UNC ones, and v1 cannot prove
+ * those aliases equivalent. A runtime that needs repair throws rather than resolving routing, which
+ * is likewise no basis for deleting rows.
+ */
+function captureLocalMetadataPruneExpectation(
+  store: RuntimeStore,
+  repo: Repo
+): NativeLocalWorktreeMetadataScanExpectation | undefined {
+  if (typeof store.captureNativeLocalWorktreeMetadataScanExpectation !== 'function') {
+    return undefined
+  }
+  try {
+    if (getLocalProjectWorktreeGitOptions(store as unknown as Store, repo).wslDistro) {
+      return undefined
+    }
+  } catch {
+    return undefined
+  }
+  return store.captureNativeLocalWorktreeMetadataScanExpectation(repo)
+}
+
 export class RuntimeManagedWorktreeQueries {
   constructor(private readonly deps: Dependencies) {}
 
@@ -129,6 +158,10 @@ export class RuntimeManagedWorktreeQueries {
         worktrees: projectResolvedWorktreeLineage(detected, store.getAllWorktreeLineage?.() ?? {})
       }
     }
+    // Why capture before the scan: listing can mutate metadata synchronously before its first
+    // await, and the prune revalidates against the rows as they stood when the scan was issued.
+    const metadataScanGeneration = getLocalWorktreeScanGeneration(repo.id)
+    const metadataPruneExpectation = captureLocalMetadataPruneExpectation(store, repo)
     let scan: RuntimeWorktreeScanResult
     try {
       scan = await this.deps.scanRepo(repo)
@@ -136,6 +169,17 @@ export class RuntimeManagedWorktreeQueries {
       scan = { ok: false, worktrees: [] }
     }
     if (scan.ok) {
+      // Why the runtime sweeps too: the desktop listing that used to own this runs off `ipcMain`,
+      // so a headless host -- which has no renderer -- never pruned its own repos' rows (#17776).
+      if (metadataPruneExpectation) {
+        await pruneMetadataMissingFromAuthoritativeLocalScan({
+          store: store as unknown as Store,
+          repo,
+          gitWorktrees: scan.worktrees,
+          scan: metadataPruneExpectation,
+          scanGeneration: metadataScanGeneration
+        })
+      }
       pruneLineageForMissingRepoWorktrees(store as unknown as Store, repo, scan.worktrees)
     }
     const matcher = createWorktreeVisibilitySourceMatcher(
diff --git a/src/main/runtime/runtime-store-contract.ts b/src/main/runtime/runtime-store-contract.ts
index 692826b3c29..e160e039533 100644
--- a/src/main/runtime/runtime-store-contract.ts
+++ b/src/main/runtime/runtime-store-contract.ts
@@ -30,6 +30,9 @@ export type RuntimeStore = {
   removeProjectForHost?: Store['removeProjectForHost']
   reorderRepos?: Store['reorderRepos']
   getAllWorktreeMeta: Store['getAllWorktreeMeta']
+  captureNativeLocalWorktreeMetadataScanExpectation?: Store['captureNativeLocalWorktreeMetadataScanExpectation']
+  pruneSessionlessMissingLocalWorktreeMetadataForRepo?: Store['pruneSessionlessMissingLocalWorktreeMetadataForRepo']
+  getProfileStorageDirectory?: Store['getProfileStorageDirectory']
   getWorktreeMeta: Store['getWorktreeMeta']
   setWorktreeMeta: Store['setWorktreeMeta']
   setWorktreeMetaForHost?: Store['setWorktreeMetaForHost']

From 05a7d390588362eb7b2eff6922c62d13a3968bc7 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Tue, 1 Sep 2026 02:23:44 -0700
Subject: [PATCH 12/32] test(runtime): make the off-host sweep case a real
 control

The row was stamped `ssh:build-box`, which
`captureNativeLocalWorktreeMetadataScanExpectation` filters out before the
prune runs -- so it survived whether or not any host gate existed and pinned
nothing.

Stamp it `local` so it is a genuine prune candidate whose directory really is
missing, and make the fixture identical to the first case apart from
`connectionId`. That pairing is what proves the behavior: the same fixture
without a connection loses the row. Deleting any single gate would not show
it, since four independent checks derive from `connectionId` on this path.

Refs #17776
---
 ...runtime-managed-worktree-metadata-sweep.test.ts | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/src/main/runtime/runtime-managed-worktree-metadata-sweep.test.ts b/src/main/runtime/runtime-managed-worktree-metadata-sweep.test.ts
index 12d5d71e7e0..6df19517d64 100644
--- a/src/main/runtime/runtime-managed-worktree-metadata-sweep.test.ts
+++ b/src/main/runtime/runtime-managed-worktree-metadata-sweep.test.ts
@@ -61,6 +61,7 @@ describe('runtime detected-worktree listing sweeps missing local metadata', () =
     rmSync(testState.dir, { recursive: true, force: true })
   })
 
+  // Paired with the off-host case below: same fixture, no `connectionId`.
   it('drops a metadata row whose directory is gone and the scan does not list', async () => {
     const store = createStore()
     const repo = makeRepo({ id: 'repo-1', path: repoPath })
@@ -101,17 +102,22 @@ describe('runtime detected-worktree listing sweeps missing local metadata', () =
     expect(store.getWorktreeMeta(missingId)).toBeDefined()
   })
 
-  // The execution host owns this verdict: a runtime host cannot stat an SSH checkout, so a local
-  // miss is not evidence of absence. See docs/reference/ssh-execution-boundary.md.
+  // The execution host owns this verdict: this host cannot stat a checkout that lives behind an SSH
+  // connection, so a local miss is not evidence of absence. See docs/reference/ssh-execution-boundary.md.
+  //
+  // Deliberately identical to the first case except for `connectionId`, and the row is stamped
+  // `local` so it is a real prune candidate. That pairing is the proof: the same fixture without a
+  // connection loses the row, so the connection is the only reason this one keeps it. Removing any
+  // single gate would not show that -- four independent checks derive from `connectionId` here.
   it('never sweeps a repo whose git runs off-host', async () => {
     const store = createStore()
     const repo = makeRepo({ id: 'repo-1', path: repoPath, connectionId: 'build-box' })
     store.addRepo(repo)
     const missingId = `${repo.id}::${join(testState.dir, 'deleted-worktree')}`
-    store.setWorktreeMetaForHost(missingId, 'ssh:build-box', { displayName: 'Gone' })
+    store.setWorktreeMetaForHost(missingId, 'local', { displayName: 'Gone' })
 
     await queries(store, repo, [gitWorktree(repoPath)]).listDetected(repo)
 
-    expect(store.getWorktreeMetaForHost(missingId, 'ssh:build-box')).toBeDefined()
+    expect(store.getWorktreeMeta(missingId)).toBeDefined()
   })
 })

From 398aeccdfea472584d976a62ea83c1d1c6f5ea2b Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Tue, 1 Sep 2026 01:22:04 -0700
Subject: [PATCH 13/32] fix(worktrees): retire runtime-host metadata a scan
 proved gone

A paired client's WorktreeMeta for a runtime host is exempt from
gcStaleWorktreeMeta -- that GC skips any row that is not local on both the
repo and the meta's hostId -- so a scan-proven removal is the only thing that
ever retires one. Both halves of that path were gated to `ssh:`, so the client
kept a row for every remote worktree it had ever seen and dropped none.

The renderer already computed the removals for runtime hosts and purged its
own in-memory state with them; only the persisted half bailed. Widen it, and
the matching main-side handler, to runtime hosts. `OffHostExecutionHostId`
names the set precisely: the hosts the local-only GC skips.

Also require `source === 'git'` before retiring anything. `session-fallback`
reports `authoritative: true` but is the truncated, visibility-filtered
`worktree.list` reply from a host too old for `worktree.detectedList`; its
omissions are no evidence a checkout is gone. That guard did not matter while
this only ran the in-memory purge, and does now that it deletes rows.

A repo that reaches its checkouts over a connection is still never condemned
under a runtime host id -- the host that executes owns that verdict.

Refs #17776
---
 ...orktrees-ssh-repo-owner-resolution.test.ts |  75 ++++++++++++-
 .../listing/register-host-catalog-handlers.ts |  13 ++-
 ...s-runtime-host-metadata-retirement.test.ts | 104 ++++++++++++++++++
 .../authoritative-worktree-removal-memory.ts  |  10 +-
 .../listing/fetched-worktree-merge.ts         |   9 +-
 .../detected-worktree-provider-contract.ts    |   8 +-
 6 files changed, 209 insertions(+), 10 deletions(-)
 create mode 100644 src/renderer/src/store/slices/worktrees-runtime-host-metadata-retirement.test.ts

diff --git a/src/main/ipc/worktrees-ssh-repo-owner-resolution.test.ts b/src/main/ipc/worktrees-ssh-repo-owner-resolution.test.ts
index 6a398e9b02d..5a4d775c2d0 100644
--- a/src/main/ipc/worktrees-ssh-repo-owner-resolution.test.ts
+++ b/src/main/ipc/worktrees-ssh-repo-owner-resolution.test.ts
@@ -1,7 +1,11 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import type { GitWorktreeInfo, Worktree } from '../../shared/worktree/types'
 import type { ProviderRequestId } from '../../shared/detected-worktree-provider-contract'
-import { LOCAL_EXECUTION_HOST_ID, toSshExecutionHostId } from '../../shared/execution-host'
+import {
+  LOCAL_EXECUTION_HOST_ID,
+  toRuntimeExecutionHostId,
+  toSshExecutionHostId
+} from '../../shared/execution-host'
 import { getSshProviderAuthority } from '../ssh/ssh-provider-authority'
 import {
   listWorktreesMock,
@@ -443,7 +447,74 @@ describe('registerWorktreeHandlers', () => {
     expect(store.removeWorktreeMeta).not.toHaveBeenCalled()
   })
 
-  it('refuses to retire metadata for non-SSH hosts and unowned repos', async () => {
+  // Runtime-host rows are exempt from gcStaleWorktreeMeta exactly as SSH ones are, so a paired
+  // client needs this path to ever drop them (#17776).
+  it('retires runtime-host metadata an authoritative scan proved gone', async () => {
+    const runtimeHostId = toRuntimeExecutionHostId('env-1')
+    const runtimeRepo = {
+      id: 'repo-1',
+      path: '/home/orca/repo',
+      displayName: 'repo',
+      badgeColor: '#000',
+      addedAt: 0,
+      executionHostId: runtimeHostId
+    }
+    const metaById: Record<string, ReturnType<typeof makeWorktreeMeta>> = {
+      'repo-1::/home/orca/deleted': makeWorktreeMeta({ hostId: runtimeHostId }),
+      'repo-1::/home/orca/other-host': makeWorktreeMeta({
+        hostId: toSshExecutionHostId('target-a')
+      })
+    }
+    store.getRepos.mockReturnValue([runtimeRepo])
+    store.getProjectHostSetups.mockReturnValue([])
+    store.getAllWorktreeMeta.mockReturnValue(metaById)
+    store.removeWorktreeMeta.mockImplementation((worktreeId: string) => {
+      delete metaById[worktreeId]
+    })
+
+    const forgotten = await handlers['worktrees:forgetRemovedForExecutionHost'](null, {
+      repoId: runtimeRepo.id,
+      executionHostId: runtimeHostId,
+      worktreeIds: ['repo-1::/home/orca/deleted', 'repo-1::/home/orca/other-host']
+    })
+
+    // The row stamped to another host needs that host's own scan, not this one's.
+    expect(forgotten).toEqual({ forgottenWorktreeIds: ['repo-1::/home/orca/deleted'] })
+    expect(store.removeWorktreeMeta).toHaveBeenCalledExactlyOnceWith(
+      'repo-1::/home/orca/deleted',
+      runtimeHostId
+    )
+  })
+
+  // A repo that reaches its checkouts over SSH is not the runtime host's to condemn.
+  it('refuses to retire a connection-backed repo under a runtime host id', async () => {
+    const runtimeHostId = toRuntimeExecutionHostId('env-1')
+    store.getRepos.mockReturnValue([
+      {
+        id: 'repo-1',
+        path: '/home/orca/repo',
+        displayName: 'repo',
+        badgeColor: '#000',
+        addedAt: 0,
+        executionHostId: runtimeHostId,
+        connectionId: 'target-a'
+      }
+    ])
+    store.getAllWorktreeMeta.mockReturnValue({
+      'repo-1::/home/orca/deleted': makeWorktreeMeta({ hostId: runtimeHostId })
+    })
+
+    expect(
+      await handlers['worktrees:forgetRemovedForExecutionHost'](null, {
+        repoId: 'repo-1',
+        executionHostId: runtimeHostId,
+        worktreeIds: ['repo-1::/home/orca/deleted']
+      })
+    ).toEqual({ forgottenWorktreeIds: [] })
+    expect(store.removeWorktreeMeta).not.toHaveBeenCalled()
+  })
+
+  it('refuses to retire metadata for non-executing hosts and unowned repos', async () => {
     const sshRepo = {
       id: 'repo-1',
       path: '/remote/repo-a',
diff --git a/src/main/ipc/worktrees/listing/register-host-catalog-handlers.ts b/src/main/ipc/worktrees/listing/register-host-catalog-handlers.ts
index 0d47f3638c2..56c2f282f37 100644
--- a/src/main/ipc/worktrees/listing/register-host-catalog-handlers.ts
+++ b/src/main/ipc/worktrees/listing/register-host-catalog-handlers.ts
@@ -103,11 +103,20 @@ export function registerHostCatalogHandlers(context: WorktreeIpcContext): void {
       const requestedExecutionHostId = args?.executionHostId ?? 'ssh:'
       const worktreeIds = Array.isArray(args?.worktreeIds) ? args.worktreeIds : []
       const parsedHost = parseExecutionHostId(requestedExecutionHostId)
-      if (parsedHost?.kind !== 'ssh' || worktreeIds.length === 0) {
+      // Runtime hosts belong here for the same reason SSH ones do: their rows are exempt from
+      // gcStaleWorktreeMeta, so a scan-proven removal is the only thing that ever retires them.
+      if (
+        (parsedHost?.kind !== 'ssh' && parsedHost?.kind !== 'runtime') ||
+        worktreeIds.length === 0
+      ) {
         return nothingForgotten
       }
       const repo = findExactRepoOwner(store, args?.repoId ?? '', requestedExecutionHostId)
-      if (!repo || repo.connectionId !== parsedHost.targetId) {
+      // The connection must be the one the host id names, so a caller cannot retire a row belonging
+      // to a repo that reaches its checkouts some other way.
+      const connectionMatchesHost =
+        parsedHost.kind === 'ssh' ? repo?.connectionId === parsedHost.targetId : !repo?.connectionId
+      if (!repo || !connectionMatchesHost) {
         return nothingForgotten
       }
       // Why: a folder workspace's meta IS the workspace record, not a checkout row — gcStaleWorktreeMeta skips
diff --git a/src/renderer/src/store/slices/worktrees-runtime-host-metadata-retirement.test.ts b/src/renderer/src/store/slices/worktrees-runtime-host-metadata-retirement.test.ts
new file mode 100644
index 00000000000..eeaf49dd5e4
--- /dev/null
+++ b/src/renderer/src/store/slices/worktrees-runtime-host-metadata-retirement.test.ts
@@ -0,0 +1,104 @@
+// Why this file exists: a paired client's WorktreeMeta for a runtime host is exempt from
+// gcStaleWorktreeMeta (it skips any row that is not local on both the repo and the meta's hostId),
+// and `forgetPersistedWorktreeMetaForRemovals` used to bail for every non-SSH host. So the client
+// kept a row per remote worktree it had ever seen and dropped none (#17776).
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { AppState } from '../types'
+import { makeWorktree } from './worktrees-slice-test-fixtures'
+import { makeDetectedResult } from './worktrees-detected-listing-fixtures'
+import {
+  createTestStore,
+  forgetRemovedForExecutionHostMock,
+  resetRemoteRuntimeMocks,
+  resetWorktreeSliceModuleMemory,
+  runtimeEnvironmentCall
+} from './worktrees-slice-test-harness'
+
+const REPO_ID = 'repo-runtime'
+const HOST_ID = 'runtime:env-1'
+
+const worktree = (path: string) =>
+  makeWorktree({ id: `${REPO_ID}::${path}`, repoId: REPO_ID, path, hostId: HOST_ID })
+
+const live = worktree('/home/orca/live')
+const deletedOnHost = worktree('/home/orca/deleted')
+
+function seedClientWithBothRows(): ReturnType<typeof createTestStore> {
+  const store = createTestStore()
+  store.setState({
+    settings: { activeRuntimeEnvironmentId: 'env-1' } as never,
+    repos: [
+      {
+        id: REPO_ID,
+        path: '/home/orca/repo',
+        displayName: 'Runtime Repo',
+        badgeColor: '#000',
+        addedAt: 0,
+        executionHostId: HOST_ID
+      }
+    ],
+    worktreesByRepo: { [REPO_ID]: [live, deletedOnHost] }
+  } as Partial<AppState>)
+  return store
+}
+
+beforeEach(resetWorktreeSliceModuleMemory)
+
+describe('runtime-host persisted metadata retirement', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    resetRemoteRuntimeMocks()
+  })
+
+  it('retires metadata for rows an authoritative runtime-host scan proved gone', async () => {
+    const store = seedClientWithBothRows()
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-detected',
+      ok: true,
+      result: makeDetectedResult(REPO_ID, [live]),
+      _meta: { runtimeId: 'runtime-remote' }
+    })
+
+    await store.getState().fetchWorktrees(REPO_ID, { executionHostId: HOST_ID })
+
+    expect(forgetRemovedForExecutionHostMock).toHaveBeenCalledExactlyOnceWith({
+      repoId: REPO_ID,
+      executionHostId: HOST_ID,
+      worktreeIds: [deletedOnHost.id]
+    })
+  })
+
+  // A non-authoritative reply is a failed listing, not a report that a checkout is gone.
+  it('retires nothing when the runtime host could not scan', async () => {
+    const store = seedClientWithBothRows()
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-detected',
+      ok: true,
+      result: makeDetectedResult(REPO_ID, [live], {
+        authoritative: false,
+        source: 'metadata-fallback'
+      }),
+      _meta: { runtimeId: 'runtime-remote' }
+    })
+
+    await store.getState().fetchWorktrees(REPO_ID, { executionHostId: HOST_ID })
+
+    expect(forgetRemovedForExecutionHostMock).not.toHaveBeenCalled()
+  })
+
+  // `session-fallback` claims authoritative but is the truncated, visibility-filtered `worktree.list`
+  // reply from a host too old for `worktree.detectedList`. Its omissions prove nothing.
+  it('retires nothing from a legacy session-fallback listing', async () => {
+    const store = seedClientWithBothRows()
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-detected',
+      ok: true,
+      result: makeDetectedResult(REPO_ID, [live], { source: 'session-fallback' }),
+      _meta: { runtimeId: 'runtime-remote' }
+    })
+
+    await store.getState().fetchWorktrees(REPO_ID, { executionHostId: HOST_ID })
+
+    expect(forgetRemovedForExecutionHostMock).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/renderer/src/store/slices/worktrees/listing/authoritative-worktree-removal-memory.ts b/src/renderer/src/store/slices/worktrees/listing/authoritative-worktree-removal-memory.ts
index 9793adb0e16..e2fae6b9f77 100644
--- a/src/renderer/src/store/slices/worktrees/listing/authoritative-worktree-removal-memory.ts
+++ b/src/renderer/src/store/slices/worktrees/listing/authoritative-worktree-removal-memory.ts
@@ -50,16 +50,18 @@ export function resetAuthoritativelyRemovedWorktreeMemoryForTests(): void {
   authoritativelyRemovedWorktreeIdsByHost.clear()
 }
 
-// Why: SSH WorktreeMeta is exempt from gcStaleWorktreeMeta (persistence.ts:407,415) and outlives the remote
-// worktree, so a scan-proven removal must retire the metadata itself — otherwise the next launch's fallback
-// re-lists the deleted row before the host connects, and the in-memory suppression above is already gone.
+// Why: off-host WorktreeMeta is exempt from gcStaleWorktreeMeta -- it skips any row whose repo or hostId is
+// not local -- and outlives the remote worktree, so a scan-proven removal must retire the metadata itself.
+// Otherwise the next launch's fallback re-lists the deleted row before the host connects, and the in-memory
+// suppression above is already gone. Runtime hosts were excluded until #17776, which is why a paired client
+// accumulated a row per remote worktree it had ever seen and never dropped one.
 export function forgetPersistedWorktreeMetaForRemovals(
   repoId: string,
   hostId: ExecutionHostId,
   worktreeIds: readonly string[]
 ): void {
   const parsedHost = parseExecutionHostId(hostId)
-  if (worktreeIds.length === 0 || parsedHost?.kind !== 'ssh') {
+  if (worktreeIds.length === 0 || (parsedHost?.kind !== 'ssh' && parsedHost?.kind !== 'runtime')) {
     return
   }
   const forget = window.api.worktrees.forgetRemovedForExecutionHost
diff --git a/src/renderer/src/store/slices/worktrees/listing/fetched-worktree-merge.ts b/src/renderer/src/store/slices/worktrees/listing/fetched-worktree-merge.ts
index 13e6b1572c1..fde831ee2e5 100644
--- a/src/renderer/src/store/slices/worktrees/listing/fetched-worktree-merge.ts
+++ b/src/renderer/src/store/slices/worktrees/listing/fetched-worktree-merge.ts
@@ -254,7 +254,14 @@ export function mergeFetchedWorktrees(
     // Why: applied outside the updater so a repeated updater call cannot double-apply the removal memory.
     forgetAuthoritativelyRemovedWorktrees(args.hostId, authoritativelySeenIds)
     rememberAuthoritativelyRemovedWorktrees(args.hostId, authoritativelyRemovedIds)
-    forgetPersistedWorktreeMetaForRemovals(args.repoId, args.hostId, authoritativelyRemovedIds)
+    // Only a real scan retires persisted metadata. `session-fallback` also reports authoritative,
+    // but it is the truncated, visibility-filtered `worktree.list` reply from a host too old for
+    // `worktree.detectedList` -- its omissions are not evidence a checkout is gone.
+    forgetPersistedWorktreeMetaForRemovals(
+      args.repoId,
+      args.hostId,
+      args.refresh.result.source === 'git' ? authoritativelyRemovedIds : []
+    )
   }
   return admitted
 }
diff --git a/src/shared/detected-worktree-provider-contract.ts b/src/shared/detected-worktree-provider-contract.ts
index 9f146e35778..99b0f8fdc74 100644
--- a/src/shared/detected-worktree-provider-contract.ts
+++ b/src/shared/detected-worktree-provider-contract.ts
@@ -41,9 +41,15 @@ export type HostQualifiedKnownWorktreeResult =
       executionHostId: SshExecutionHostId
     }
 
+/**
+ * Hosts whose persisted metadata a scan can retire: exactly those `gcStaleWorktreeMeta` skips,
+ * because it only ever condemns rows that are local on both the repo and the meta's `hostId`.
+ */
+export type OffHostExecutionHostId = Extract<ExecutionHostId, `ssh:${string}` | `runtime:${string}`>
+
 export type ForgetRemovedWorktreesForExecutionHostArgs = {
   repoId: string
-  executionHostId: SshExecutionHostId
+  executionHostId: OffHostExecutionHostId
   /** Ids an authoritative scan of this host proved gone — the only evidence that retires persisted metadata. */
   worktreeIds: readonly string[]
 }

From f2fa4a7754e03e975b0da31efa914cf9a552e154 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Tue, 1 Sep 2026 17:06:24 -0700
Subject: [PATCH 14/32] fix(worktrees): drop an unreachable runtime arm from
 the retirement gate

`findExactRepoOwner` already refuses a repo carrying both a runtime
`executionHostId` and a `connectionId` -- `resolveRepoOwnershipEvidence` calls
that pair contradictory, and one non-owned candidate voids the whole lookup.
There is also no way for a `connectionId` to yield a `runtime:` host id, since
`toSshExecutionHostId` always emits `ssh:`. The runtime arm of
`connectionMatchesHost` could therefore never decide anything, and the test
meant to pin it was passing through the contradiction gate instead.

Keep the SSH arm, which does gate, and record where the runtime refusal
actually comes from. Unreachable code on a destructive path reads as a
guarantee it is not making.

Refs #17776
---
 .../ipc/worktrees-ssh-repo-owner-resolution.test.ts   |  4 +++-
 .../listing/register-host-catalog-handlers.ts         | 11 ++++++-----
 2 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/src/main/ipc/worktrees-ssh-repo-owner-resolution.test.ts b/src/main/ipc/worktrees-ssh-repo-owner-resolution.test.ts
index 5a4d775c2d0..b3231da86f6 100644
--- a/src/main/ipc/worktrees-ssh-repo-owner-resolution.test.ts
+++ b/src/main/ipc/worktrees-ssh-repo-owner-resolution.test.ts
@@ -486,7 +486,9 @@ describe('registerWorktreeHandlers', () => {
     )
   })
 
-  // A repo that reaches its checkouts over SSH is not the runtime host's to condemn.
+  // A repo that reaches its checkouts over SSH is not the runtime host's to condemn. The refusal
+  // comes from `findExactRepoOwner`: a runtime `executionHostId` beside a `connectionId` is
+  // contradictory ownership evidence, so no owner resolves at all.
   it('refuses to retire a connection-backed repo under a runtime host id', async () => {
     const runtimeHostId = toRuntimeExecutionHostId('env-1')
     store.getRepos.mockReturnValue([
diff --git a/src/main/ipc/worktrees/listing/register-host-catalog-handlers.ts b/src/main/ipc/worktrees/listing/register-host-catalog-handlers.ts
index 56c2f282f37..4467506e790 100644
--- a/src/main/ipc/worktrees/listing/register-host-catalog-handlers.ts
+++ b/src/main/ipc/worktrees/listing/register-host-catalog-handlers.ts
@@ -111,12 +111,13 @@ export function registerHostCatalogHandlers(context: WorktreeIpcContext): void {
       ) {
         return nothingForgotten
       }
+      // No runtime arm in the check below: `findExactRepoOwner` already refuses a repo carrying both
+      // a runtime `executionHostId` and a `connectionId`, because `resolveRepoOwnershipEvidence`
+      // calls that pair contradictory and one non-owned candidate voids the whole lookup. A second
+      // check would be unreachable, and unreachable code on a destructive path reads as a guarantee
+      // it is not making.
       const repo = findExactRepoOwner(store, args?.repoId ?? '', requestedExecutionHostId)
-      // The connection must be the one the host id names, so a caller cannot retire a row belonging
-      // to a repo that reaches its checkouts some other way.
-      const connectionMatchesHost =
-        parsedHost.kind === 'ssh' ? repo?.connectionId === parsedHost.targetId : !repo?.connectionId
-      if (!repo || !connectionMatchesHost) {
+      if (!repo || (parsedHost.kind === 'ssh' && repo.connectionId !== parsedHost.targetId)) {
         return nothingForgotten
       }
       // Why: a folder workspace's meta IS the workspace record, not a checkout row — gcStaleWorktreeMeta skips

From d48ab9614465f175fcaa6d39beab2d6768b89a7b Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Tue, 1 Sep 2026 17:04:45 -0700
Subject: [PATCH 15/32] test: stop two suites failing for reasons unrelated to
 their subject

The zsh wrapper test relocated into a fixed-name directory in shared temp, so a
single killed run left it behind and every later run on that machine failed with
ENOTEMPTY, permanently. Makes the name unique while keeping the non-ASCII
component the test exists for.

The palette budget asserted a helper named percentile95 that returns
sorted[floor(n * 0.95)] -- the maximum of the batch. Asserting worst-case
wall-clock under a parallel runner measures scheduler preemption: the asserted
quantity ranged 123-343ms across 20 saturated windows and blew the 220ms budget
in 6 of them, while the fastest sample of those same batches held at 19-32ms.
Asserts the fastest sample instead and adds a deterministic fan-out ceiling, so
the guard counts work rather than time. Budgets are unchanged.
---
 ...user-config-equivalence.live-shell.test.ts |  7 +-
 .../lib/palette-match/palette-match-budget.ts | 25 +++--
 .../palette-match-performance.test.ts         | 95 ++++++++++++-------
 3 files changed, 86 insertions(+), 41 deletions(-)

diff --git a/src/main/zsh-startup-hook-user-config-equivalence.live-shell.test.ts b/src/main/zsh-startup-hook-user-config-equivalence.live-shell.test.ts
index e5e45d2c22a..cbb7d2da7c5 100644
--- a/src/main/zsh-startup-hook-user-config-equivalence.live-shell.test.ts
+++ b/src/main/zsh-startup-hook-user-config-equivalence.live-shell.test.ts
@@ -16,7 +16,7 @@
  */
 import { existsSync, mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
-import { dirname, join } from 'node:path'
+import { basename, dirname, join } from 'node:path'
 import { afterAll, beforeAll, describe, expect, it } from 'vitest'
 import { getShellLaunchConfig } from './providers/local-pty-shell-ready'
 import { selectShellStartupFeatures } from './shell-startup-features'
@@ -382,9 +382,12 @@ describe.skipIf(process.platform === 'win32')('the fixes the old wrapper was bui
     // value this wrapper cannot use degrades to $HOME, where zsh itself looks.
     const home = makeZshHome({ '.zshrc': 'export ORCA_TEST_FROM_ZSHRC=1\n' })
     try {
+      // Unique per run: a fixed name here shares one path with every other run in
+      // the system temp dir, so a killed run leaves a stale directory behind and
+      // every later rename onto it fails with ENOTEMPTY.
       const { values } = await runFromRelocatedRoot(
         home,
-        join(dirname(userDataPath), '홍길동-wsl-view')
+        join(dirname(userDataPath), `홍길동-${basename(userDataPath)}`)
       )
 
       expect(values.ORCA_TEST_FROM_ZSHRC).toBe('1')
diff --git a/src/renderer/src/lib/palette-match/palette-match-budget.ts b/src/renderer/src/lib/palette-match/palette-match-budget.ts
index c51144fb39d..864473a65e6 100644
--- a/src/renderer/src/lib/palette-match/palette-match-budget.ts
+++ b/src/renderer/src/lib/palette-match/palette-match-budget.ts
@@ -1,8 +1,14 @@
 /**
  * Checked-in performance budget for the Cmd+J matcher, measured against the
  * synthetic corpus in `palette-match-performance.test.ts`. These are ceilings for
- * catching order-of-magnitude regressions, not targets — the measured numbers on
- * a developer machine sit roughly an order of magnitude under each one.
+ * catching order-of-magnitude regressions, not targets.
+ *
+ * The wall-clock ceilings are asserted against the *fastest* sample of a batch,
+ * never the slowest: a vitest worker sharing cores with the rest of the suite
+ * gets preempted mid-measurement, so the slowest sample measures the machine
+ * while the fastest still approximates the matcher. Fan-out regressions are
+ * caught by `fieldMatchesPerCandidate` instead, which counts work rather than
+ * time and so does not depend on machine speed at all.
  *
  * Raising any value requires a fresh measurement recorded in the PR.
  */
@@ -11,10 +17,17 @@ export const PALETTE_MATCH_BUDGET = {
   candidateCount: 800,
   /** Unique tokens in the worst supported query. */
   tokenCount: 16,
-  /** p95 milliseconds to normalize every document once (cold open). */
-  coldBuildP95Ms: 900,
-  /** p95 milliseconds to match the whole corpus against one prepared query. */
-  warmMatchP95Ms: 220,
+  /**
+   * Ceiling on `matchPaletteField` calls per candidate for the worst query.
+   * Deterministic — it counts work, not time — so it catches a fan-out
+   * regression (re-matching every field per evidence unit, say) on any machine.
+   * Measured 45: 15 fields across the 3 tokens scanned before the first miss.
+   */
+  fieldMatchesPerCandidate: 60,
+  /** Milliseconds to normalize every document once (cold open), fastest sample. */
+  coldBuildMs: 900,
+  /** Milliseconds to match the whole corpus against one prepared query, fastest sample. */
+  warmMatchMs: 220,
   /**
    * Megabytes of indexed text and offset tables the normalized documents retain.
    * Measured deterministically rather than from `heapUsed`, which is polluted by
diff --git a/src/renderer/src/lib/palette-match/palette-match-performance.test.ts b/src/renderer/src/lib/palette-match/palette-match-performance.test.ts
index aa1e6e12047..13fbced916f 100644
--- a/src/renderer/src/lib/palette-match/palette-match-performance.test.ts
+++ b/src/renderer/src/lib/palette-match/palette-match-performance.test.ts
@@ -1,8 +1,11 @@
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import { PALETTE_MATCH_BUDGET } from './palette-match-budget'
 import { matchPaletteDocument } from './match-document'
+import * as matchFieldModule from './match-field'
 import { preparePaletteQuery } from './palette-query'
 import { buildWorktreePaletteDocuments } from '../worktree-palette-document'
+import type { PaletteDocument } from './palette-document'
+import type { PaletteQueryToken } from './palette-query'
 import type { Repo } from '../../../../shared/repo-types'
 import type { Worktree } from '../../../../shared/worktree/types'
 
@@ -89,49 +92,75 @@ const WORST_QUERY = Array.from({ length: tokenCount }, (_, index) =>
   index === 0 ? 'scan' : index === 1 ? 'daily' : `token${index}`
 ).join(' ')
 
-function percentile95(samples: number[]): number {
-  const sorted = [...samples].sort((a, b) => a - b)
-  return sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * 0.95))]
+function prepareWorstQuery(): { tokens: readonly PaletteQueryToken[]; normalized: string } {
+  const prepared = preparePaletteQuery(WORST_QUERY)
+  if (prepared.state !== 'ready') {
+    throw new Error(`Expected a ready query, got ${prepared.state}`)
+  }
+  return { tokens: prepared.tokens, normalized: prepared.normalized }
+}
+
+const preparedQuery = prepareWorstQuery()
+
+function matchEveryDocument(documents: ReadonlyMap<string, PaletteDocument>): void {
+  for (const document of documents.values()) {
+    matchPaletteDocument({
+      document,
+      tokens: preparedQuery.tokens,
+      normalizedQuery: preparedQuery.normalized
+    })
+  }
+}
+
+/**
+ * Why the fastest sample and not p95: this runs in a vitest worker competing for
+ * cores with the rest of the suite, so a slow sample records a preemption rather
+ * than the matcher. The fastest sample is the least contaminated estimate of
+ * intrinsic cost — measured stable within 1.6x on a fully saturated machine,
+ * while the slowest of the same batch swung by 17x.
+ */
+function fastestSample(samples: readonly number[]): number {
+  return Math.min(...samples)
+}
+
+function timeRepeatedly(work: () => void, rounds: number): number[] {
+  const samples: number[] = []
+  for (let round = 0; round < rounds; round += 1) {
+    const start = performance.now()
+    work()
+    samples.push(performance.now() - start)
+  }
+  return samples
 }
 
 describe('palette matcher performance budget', () => {
   it('normalizes a cold corpus within budget', () => {
-    const samples: number[] = []
-    for (let run = 0; run < 5; run += 1) {
-      const start = performance.now()
-      buildWorktreePaletteDocuments(worktrees, sources)
-      samples.push(performance.now() - start)
-    }
-    expect(percentile95(samples)).toBeLessThan(PALETTE_MATCH_BUDGET.coldBuildP95Ms)
+    const samples = timeRepeatedly(() => buildWorktreePaletteDocuments(worktrees, sources), 5)
+    expect(fastestSample(samples)).toBeLessThan(PALETTE_MATCH_BUDGET.coldBuildMs)
   })
 
   it('matches a 16-token query against warm documents within budget', () => {
     const documents = buildWorktreePaletteDocuments(worktrees, sources)
-    const prepared = preparePaletteQuery(WORST_QUERY)
-    expect(prepared.state).toBe('ready')
-    if (prepared.state !== 'ready') {
-      return
-    }
 
-    const matchAllDocuments = (): void => {
-      for (const document of documents.values()) {
-        matchPaletteDocument({
-          document,
-          tokens: prepared.tokens,
-          normalizedQuery: prepared.normalized
-        })
-      }
-    }
+    // Warm the matcher before timing so JIT compilation is not part of the samples.
+    matchEveryDocument(documents)
 
-    // Warm the matcher before timing so JIT compilation is not part of p95.
-    matchAllDocuments()
-    const samples: number[] = []
-    for (let run = 0; run < 10; run += 1) {
-      const start = performance.now()
-      matchAllDocuments()
-      samples.push(performance.now() - start)
+    const samples = timeRepeatedly(() => matchEveryDocument(documents), 10)
+    expect(fastestSample(samples)).toBeLessThan(PALETTE_MATCH_BUDGET.warmMatchMs)
+  })
+
+  it('bounds field-match fan-out per candidate', () => {
+    const documents = buildWorktreePaletteDocuments(worktrees, sources)
+    const fieldMatch = vi.spyOn(matchFieldModule, 'matchPaletteField')
+    try {
+      matchEveryDocument(documents)
+      const perCandidate = fieldMatch.mock.calls.length / documents.size
+      // Guards the ceiling against going vacuous if the spy ever stops intercepting.
+      expect(perCandidate).toBeGreaterThan(0)
+      expect(perCandidate).toBeLessThan(PALETTE_MATCH_BUDGET.fieldMatchesPerCandidate)
+    } finally {
+      fieldMatch.mockRestore()
     }
-    expect(percentile95(samples)).toBeLessThan(PALETTE_MATCH_BUDGET.warmMatchP95Ms)
   })
 
   it('keeps the retained document payload within budget', () => {

From 4efc86a33c55948f4e3b2389adb7c99d9674c693 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Tue, 1 Sep 2026 17:35:38 -0700
Subject: [PATCH 16/32] feat(app): open Markdown files from the OS in the
 floating workspace (#17906)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat(app): open Markdown files from the OS in the floating workspace

Registers Orca as a Markdown handler on macOS, Windows and Linux, and opens
an OS-handed .md/.markdown/.mdx file as a floating-workspace editor tab —
the one editor surface that needs no project. Works cold-start and when
Orca is already running.

Main buffers the paths and both pushes to a live renderer and answers a
pull on renderer mount, mirroring SkillShareDeepLinkState. The buffer is
only released once delivery is possible: the renderer's pull is what proves
its ui:openMarkdownFiles listener is attached, because a push into a window
whose renderer has not subscribed is dropped by Electron with no error. Both
the push and the pull restore an undelivered batch, and a renderer reload
clears the latch so the fresh renderer re-proves itself. Paths are stat'd and
proven to be files before authorizeExternalPath sees them.

Windows association is registered by hand in the NSIS include rather than
through electron-builder's `fileAssociations`: app-builder-lib emits
APP_ASSOCIATE, whose first line overwrites Software\Classes\.md's default
value with no backup — silently taking .md from whichever editor owns it,
for every existing user on their next update — and APP_UNASSOCIATE never
restores it. The hand-rolled registration is additive (ProgID +
OpenWithProgids + SupportedTypes) and leaves the user's default alone;
verified end to end on a real Windows 11 host.

Co-authored-by: Wooseong Kim <innocarpe@users.noreply.github.com>
Co-authored-by: Jaydev <java-jaydev@users.noreply.github.com>

Closes #10138

* fix(os-open): register the new listener in the IPC inventory, and guard a non-array payload

CI caught two things the local run did not.

useIpcEvents-lifecycle.test.ts is an inventory of every App-lifetime IPC
listener and the exact order they register in; ui.onOpenMarkdownFiles now
appears there, positioned after the workspace-shortcut bridge's last
listener, which is where it actually registers.

Chasing that failure surfaced a real gap: the pending-open payload crosses
the preload boundary, so a stale or mismatched preload can resolve with
something that is not an array, and reading .length off it threw inside the
promise chain instead of failing at the boundary. Array.isArray now gates it,
with a regression test.
---
 config/electron-builder.config.cjs            |  31 +-
 config/nsis/daemon-host-uninstall.nsh         |  23 --
 config/nsis/orca-installer-hooks.nsh          |  79 +++++
 ...ron-builder-markdown-associations.test.mjs | 116 +++++++
 src/main/daemon/daemon-host-relocation.ts     |   2 +-
 src/main/index.ts                             |  50 +++
 .../startup/main-process-ipc-bootstrap.ts     |  15 +
 src/main/startup/main-process-state.ts        |   7 +
 src/main/startup/main-window-controller.ts    |   3 +
 .../os-opened-markdown-delivery.test.ts       |  68 ++++
 .../startup/os-opened-markdown-files.test.ts  | 306 ++++++++++++++++++
 src/main/startup/os-opened-markdown-files.ts  | 149 +++++++++
 .../startup/os-opened-markdown-wiring.test.ts |  57 ++++
 .../api/ui-bridge-state-and-menu-commands.ts  |   9 +
 src/preload/api/ui-command-event-api.ts       |   5 +
 .../use-floating-terminal-create-actions.ts   |  20 +-
 .../ipc-events/app-lifetime-ipc-bridge.ts     |   2 +
 .../os-markdown-file-open-bridge.test.ts      | 300 +++++++++++++++++
 .../os-markdown-file-open-bridge.ts           |  72 +++++
 .../src/hooks/useIpcEvents-lifecycle.test.ts  |   2 +
 src/renderer/src/i18n/locales/en.json         |  11 +
 ...pen-markdown-in-floating-workspace.test.ts |  81 +++++
 .../open-markdown-in-floating-workspace.ts    |  32 ++
 .../src/web/preload-api/web-ui-api.ts         |   3 +
 24 files changed, 1399 insertions(+), 44 deletions(-)
 delete mode 100644 config/nsis/daemon-host-uninstall.nsh
 create mode 100644 config/nsis/orca-installer-hooks.nsh
 create mode 100644 config/scripts/electron-builder-markdown-associations.test.mjs
 create mode 100644 src/main/startup/os-opened-markdown-delivery.test.ts
 create mode 100644 src/main/startup/os-opened-markdown-files.test.ts
 create mode 100644 src/main/startup/os-opened-markdown-files.ts
 create mode 100644 src/main/startup/os-opened-markdown-wiring.test.ts
 create mode 100644 src/renderer/src/hooks/ipc-events/os-markdown-file-open-bridge.test.ts
 create mode 100644 src/renderer/src/hooks/ipc-events/os-markdown-file-open-bridge.ts
 create mode 100644 src/renderer/src/lib/open-markdown-in-floating-workspace.test.ts
 create mode 100644 src/renderer/src/lib/open-markdown-in-floating-workspace.ts

diff --git a/config/electron-builder.config.cjs b/config/electron-builder.config.cjs
index 1a31af9dfaf..13633ed8e01 100644
--- a/config/electron-builder.config.cjs
+++ b/config/electron-builder.config.cjs
@@ -105,6 +105,11 @@ const winSpeechNativeResource = {
   to: 'node_modules/sherpa-onnx-win-x64'
 }
 
+// Why mirrored, not imported: this config is CJS loaded by electron-builder outside the TS build.
+// Keep in sync with isMarkdownDocumentName() in src/main/ipc/markdown-documents.ts and with
+// config/nsis/orca-installer-hooks.nsh, which registers the same set on Windows.
+const MARKDOWN_FILE_EXTENSIONS = ['md', 'markdown', 'mdx']
+
 /** @type {import('electron-builder').Configuration} */
 module.exports = {
   appId,
@@ -376,12 +381,24 @@ module.exports = {
     shortcutName: '${productName}',
     uninstallDisplayName: '${productName}',
     createDesktopShortcut: 'always',
-    // Why: on a real uninstall, stop and remove the relocated terminal daemon
-    // (which lives outside the install dir under LOCALAPPDATA by design). Guarded
-    // by ${isUpdated} inside so it never runs during an update's uninstallOldVersion.
-    include: resolve(__dirname, 'nsis', 'daemon-host-uninstall.nsh')
+    // Why: electron-builder allows one include, so both Windows installer hooks live in it -
+    // the relocated-daemon uninstall sweep (guarded by ${isUpdated} so it never runs during an
+    // update's uninstallOldVersion) and the additive markdown "Open with" registration.
+    // Windows markdown association is deliberately NOT done via `fileAssociations`; see the
+    // header comment in that file for why that would steal the user's default .md handler.
+    include: resolve(__dirname, 'nsis', 'orca-installer-hooks.nsh')
   },
   mac: {
+    // Why rank Alternate: Orca joins Finder's "Open With" list for Markdown without claiming
+    // LSHandlerRank ownership, so whichever editor the user already prefers stays the default.
+    // Why one entry per extension: app-builder-lib globs `*.${ext}`, which an array would break.
+    fileAssociations: MARKDOWN_FILE_EXTENSIONS.map((ext) => ({
+      ext,
+      name: 'Markdown Document',
+      description: 'Markdown Document',
+      role: 'Editor',
+      rank: 'Alternate'
+    })),
     icon: 'resources/build/icon.icns',
     entitlements: 'resources/build/entitlements.mac.plist',
     entitlementsInherit: 'resources/build/entitlements.mac.plist',
@@ -468,6 +485,12 @@ module.exports = {
     artifactName: 'orca-macos-${arch}.${ext}'
   },
   linux: {
+    // Why mimeTypes and not fileAssociations: shared-mime-info already maps *.md/*.markdown to
+    // text/markdown, so reusing that type puts Orca in the Open With list without shipping a glob
+    // override. A desktop entry's MimeType only adds a handler - mimeapps.list still owns the
+    // default. .mdx is deliberately absent: Ubuntu 24.04's mime database maps it to
+    // application/x-genesis-32x-rom, so claiming it here would need a glob override.
+    mimeTypes: ['text/markdown'],
     // Why: Ubuntu desktop ships GNOME Orca as the `orca` package and /usr/bin/orca.
     // The Linux installer should not claim those system package/file names.
     executableName: 'orca-ide',
diff --git a/config/nsis/daemon-host-uninstall.nsh b/config/nsis/daemon-host-uninstall.nsh
deleted file mode 100644
index dc3a497ce67..00000000000
--- a/config/nsis/daemon-host-uninstall.nsh
+++ /dev/null
@@ -1,23 +0,0 @@
-; Clean up the relocated terminal daemon on a REAL uninstall.
-;
-; Why: the daemon host is deliberately copied to a distinct image name
-; (orca-terminal-daemon.exe) under %LOCALAPPDATA%\Orca\daemon-host so that app
-; UPDATES cannot kill it — that relocation is what keeps terminals alive across
-; updates. The same design means a normal uninstall's process sweep and file
-; removal both miss it, leaving an orphaned daemon plus its runtime copy behind.
-;
-; The ${isUpdated} guard is essential: electron-builder runs this uninstaller as
-; part of uninstallOldVersion on EVERY update, and killing the daemon there would
-; defeat the whole feature. Only clean up on a genuine uninstall.
-;
-; The image name and the LOCALAPPDATA folder name must stay in sync with
-; DAEMON_HOST_EXE_NAME and LOCAL_HOST_ROOT_NAME in
-; src/main/daemon/daemon-host-relocation.ts.
-!macro customUnInstall
-  ${ifNot} ${isUpdated}
-    nsExec::Exec 'taskkill /F /IM orca-terminal-daemon.exe'
-    ; Give the OS a moment to release the image lock before removing the tree.
-    Sleep 500
-    RMDir /r "$LOCALAPPDATA\Orca\daemon-host"
-  ${endIf}
-!macroend
diff --git a/config/nsis/orca-installer-hooks.nsh b/config/nsis/orca-installer-hooks.nsh
new file mode 100644
index 00000000000..ca80c99fc6d
--- /dev/null
+++ b/config/nsis/orca-installer-hooks.nsh
@@ -0,0 +1,79 @@
+; electron-builder NSIS hooks for the Orca Windows installer.
+;
+; electron-builder accepts exactly ONE `nsis.include` file, so every customInstall /
+; customUnInstall hook Orca needs lives here.
+
+; ---------------------------------------------------------------------------
+; Markdown "Open with Orca" (issue #10138)
+;
+; Why hand-rolled instead of electron-builder's `fileAssociations` on Windows:
+; app-builder-lib emits !insertmacro APP_ASSOCIATE, whose first line is
+;   WriteRegStr SHELL_CONTEXT "Software\Classes\.md" "" "<ProgID>"
+; That overwrites whichever editor currently owns .md, with no backup, for every
+; existing user on their next UPDATE - and APP_UNASSOCIATE never restores it, so
+; uninstalling Orca would leave .md pointing at a deleted ProgID.
+;
+; These writes are additive only. Registering a ProgID plus an OpenWithProgids
+; hint and an Applications\<exe>\SupportedTypes entry puts Orca in Explorer's
+; "Open with" list and in "Choose another app", while the default handler stays
+; exactly where the user left it. Never add a `Software\Classes\.<ext>` default
+; value here.
+;
+; MARKDOWN_PROGID must stay in sync with the extension list handled by
+; isMarkdownDocumentName() in src/main/ipc/markdown-documents.ts.
+; ---------------------------------------------------------------------------
+!define MARKDOWN_PROGID "Orca.Markdown"
+
+!macro ORCA_REGISTER_MARKDOWN_OPEN_WITH EXT
+  WriteRegNone SHELL_CONTEXT "Software\Classes\${EXT}\OpenWithProgids" "${MARKDOWN_PROGID}"
+  WriteRegStr SHELL_CONTEXT "Software\Classes\Applications\${APP_EXECUTABLE_FILENAME}\SupportedTypes" "${EXT}" ""
+!macroend
+
+!macro ORCA_UNREGISTER_MARKDOWN_OPEN_WITH EXT
+  DeleteRegValue SHELL_CONTEXT "Software\Classes\${EXT}\OpenWithProgids" "${MARKDOWN_PROGID}"
+  DeleteRegValue SHELL_CONTEXT "Software\Classes\Applications\${APP_EXECUTABLE_FILENAME}\SupportedTypes" "${EXT}"
+!macroend
+
+!macro customInstall
+  WriteRegStr SHELL_CONTEXT "Software\Classes\${MARKDOWN_PROGID}" "" "Markdown Document"
+  WriteRegStr SHELL_CONTEXT "Software\Classes\${MARKDOWN_PROGID}\DefaultIcon" "" "$appExe,0"
+  WriteRegStr SHELL_CONTEXT "Software\Classes\${MARKDOWN_PROGID}\shell\open" "" "Open with ${PRODUCT_NAME}"
+  WriteRegStr SHELL_CONTEXT "Software\Classes\${MARKDOWN_PROGID}\shell\open\command" "" '"$appExe" "%1"'
+  !insertmacro ORCA_REGISTER_MARKDOWN_OPEN_WITH ".md"
+  !insertmacro ORCA_REGISTER_MARKDOWN_OPEN_WITH ".markdown"
+  !insertmacro ORCA_REGISTER_MARKDOWN_OPEN_WITH ".mdx"
+  ; Why: Explorer caches the association list until told otherwise.
+  System::Call "shell32::SHChangeNotify(i,i,i,i) (0x08000000, 0x1000, 0, 0)"
+!macroend
+
+; ---------------------------------------------------------------------------
+; Clean up the relocated terminal daemon on a REAL uninstall.
+;
+; Why: the daemon host is deliberately copied to a distinct image name
+; (orca-terminal-daemon.exe) under %LOCALAPPDATA%\Orca\daemon-host so that app
+; UPDATES cannot kill it — that relocation is what keeps terminals alive across
+; updates. The same design means a normal uninstall's process sweep and file
+; removal both miss it, leaving an orphaned daemon plus its runtime copy behind.
+;
+; The ${isUpdated} guard is essential: electron-builder runs this uninstaller as
+; part of uninstallOldVersion on EVERY update, and killing the daemon there would
+; defeat the whole feature. Only clean up on a genuine uninstall.
+;
+; The image name and the LOCALAPPDATA folder name must stay in sync with
+; DAEMON_HOST_EXE_NAME and LOCAL_HOST_ROOT_NAME in
+; src/main/daemon/daemon-host-relocation.ts.
+!macro customUnInstall
+  ${ifNot} ${isUpdated}
+    nsExec::Exec 'taskkill /F /IM orca-terminal-daemon.exe'
+    ; Give the OS a moment to release the image lock before removing the tree.
+    Sleep 500
+    RMDir /r "$LOCALAPPDATA\Orca\daemon-host"
+  ${endIf}
+  ; Why outside the ${isUpdated} guard: customInstall rewrites these on every update, so
+  ; dropping them during uninstallOldVersion is correct and keeps the pair symmetric.
+  DeleteRegKey SHELL_CONTEXT "Software\Classes\${MARKDOWN_PROGID}"
+  !insertmacro ORCA_UNREGISTER_MARKDOWN_OPEN_WITH ".md"
+  !insertmacro ORCA_UNREGISTER_MARKDOWN_OPEN_WITH ".markdown"
+  !insertmacro ORCA_UNREGISTER_MARKDOWN_OPEN_WITH ".mdx"
+  System::Call "shell32::SHChangeNotify(i,i,i,i) (0x08000000, 0x1000, 0, 0)"
+!macroend
diff --git a/config/scripts/electron-builder-markdown-associations.test.mjs b/config/scripts/electron-builder-markdown-associations.test.mjs
new file mode 100644
index 00000000000..7ae3b1c9428
--- /dev/null
+++ b/config/scripts/electron-builder-markdown-associations.test.mjs
@@ -0,0 +1,116 @@
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import { basename } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const require = createRequire(import.meta.url)
+const electronBuilderConfig = require('../electron-builder.config.cjs')
+
+const MARKDOWN_EXTENSIONS = ['md', 'markdown', 'mdx']
+
+// The exact shape app-builder-lib's APP_ASSOCIATE emits: a write to the DEFAULT ("")
+// value of Software\Classes\.<ext>. Additive `WriteRegNone ...\OpenWithProgids` must not
+// match, or the guard below would be unfalsifiable.
+const DEFAULT_HANDLER_WRITE = /WriteRegStr\s+SHELL_CONTEXT\s+"Software\\Classes\\\.[a-z]+"\s+""/i
+
+// The hooks file documents the forbidden line in prose, so match executable script only.
+const stripNsisCommentLines = (source) =>
+  source
+    .split('\n')
+    .filter((line) => !/^\s*[;#]/.test(line))
+    .join('\n')
+
+const readInstallerHooks = () => readFile(electronBuilderConfig.nsis.include, 'utf8')
+
+describe('electron-builder markdown file associations', () => {
+  // Why: any top-level (or `win.`) fileAssociations entry makes app-builder-lib's NSIS
+  // packager emit `!insertmacro APP_ASSOCIATE`, whose first line writes that DEFAULT value
+  // — silently taking .md from whichever editor owns it, for every existing user on their
+  // next UPDATE, with APP_UNASSOCIATE never restoring it. `rank: 'Alternate'` cannot
+  // prevent this; it is LSHandlerRank and applies to macOS only. So the mac block must
+  // stay under `mac.` — hoisting it up "to share it with Windows" is what this test blocks.
+  it('never claims the Windows default markdown handler', () => {
+    expect(electronBuilderConfig.fileAssociations).toBeUndefined()
+    expect(electronBuilderConfig.win?.fileAssociations).toBeUndefined()
+  })
+
+  it('joins the macOS Open With list for every markdown extension without owning it', () => {
+    const associations = electronBuilderConfig.mac.fileAssociations
+    // One entry per extension: an array `ext` would break the Linux packager's `*.${ext}` glob.
+    expect([...associations].map((association) => association.ext).sort()).toEqual(
+      [...MARKDOWN_EXTENSIONS].sort()
+    )
+    for (const association of associations) {
+      expect(association).toMatchObject({ role: 'Editor', rank: 'Alternate' })
+    }
+  })
+
+  // Why mimeTypes and not linux.fileAssociations: shared-mime-info already maps markdown to
+  // text/markdown, so the desktop entry only adds a handler and mimeapps.list keeps owning
+  // the default. A fileAssociations entry would ship a redundant glob override instead.
+  it('reuses the existing shared-mime-info markdown type on Linux', () => {
+    expect(electronBuilderConfig.linux.mimeTypes).toContain('text/markdown')
+    expect(electronBuilderConfig.linux.fileAssociations).toBeUndefined()
+  })
+
+  it('points the single NSIS include at the installer hooks file on disk', () => {
+    const includePath = electronBuilderConfig.nsis.include
+    expect(existsSync(includePath)).toBe(true)
+    expect(basename(includePath)).toBe('orca-installer-hooks.nsh')
+  })
+
+  // Guard for the guard: proves DEFAULT_HANDLER_WRITE really matches a takeover line, so
+  // the assertion below is a live check rather than a regex that can never fire.
+  it('recognizes an APP_ASSOCIATE-style default-handler write', () => {
+    for (const takeover of [
+      '  WriteRegStr SHELL_CONTEXT "Software\\Classes\\.md" "" "Orca.Markdown"',
+      'WriteRegStr  SHELL_CONTEXT  "Software\\Classes\\.markdown"  ""  "$0"'
+    ]) {
+      expect(takeover).toMatch(DEFAULT_HANDLER_WRITE)
+    }
+    expect(
+      'WriteRegNone SHELL_CONTEXT "Software\\Classes\\.md\\OpenWithProgids" "Orca.Markdown"'
+    ).not.toMatch(DEFAULT_HANDLER_WRITE)
+    // Comment stripping must drop prose that quotes the bad line without swallowing a real
+    // one that happens to carry a trailing comment.
+    const stripped = stripNsisCommentLines(
+      [
+        ';   WriteRegStr SHELL_CONTEXT "Software\\Classes\\.md" "" "<ProgID>"',
+        '  WriteRegStr SHELL_CONTEXT "Software\\Classes\\.md" "" "$0" ; oops'
+      ].join('\n')
+    )
+    expect(stripped.split('\n')).toHaveLength(1)
+    expect(stripped).toMatch(DEFAULT_HANDLER_WRITE)
+  })
+
+  it('registers Windows markdown Open With additively, never as the default', async () => {
+    const hooks = await readInstallerHooks()
+
+    expect(stripNsisCommentLines(hooks)).not.toMatch(DEFAULT_HANDLER_WRITE)
+    // The additive hint that puts Orca in Explorer's "Open with" list.
+    expect(hooks).toMatch(
+      /WriteRegNone\s+SHELL_CONTEXT\s+"Software\\Classes\\\$\{EXT\}\\OpenWithProgids"/
+    )
+    expect(hooks).toMatch(/!macro\s+ORCA_REGISTER_MARKDOWN_OPEN_WITH\s+EXT/)
+    for (const ext of MARKDOWN_EXTENSIONS) {
+      expect(hooks).toContain(`ORCA_REGISTER_MARKDOWN_OPEN_WITH ".${ext}"`)
+      expect(hooks).toContain(`ORCA_UNREGISTER_MARKDOWN_OPEN_WITH ".${ext}"`)
+    }
+    expect(hooks).toMatch(/!macro\s+customInstall\b/)
+    expect(hooks).toMatch(/!macro\s+customUnInstall\b/)
+  })
+
+  // Why: this include was renamed from daemon-host-uninstall.nsh to carry the markdown
+  // hooks too. electron-builder allows only one include, so a merge that drops the daemon
+  // sweep would silently orphan a running orca-terminal-daemon.exe on every uninstall.
+  it('keeps the daemon-host uninstall sweep across the include rename', async () => {
+    const hooks = await readInstallerHooks()
+
+    expect(hooks).toContain('orca-terminal-daemon.exe')
+    expect(hooks).toContain('$LOCALAPPDATA\\Orca\\daemon-host')
+    // Without this guard, uninstallOldVersion would kill the daemon on every update —
+    // defeating the relocation that keeps terminals alive across updates.
+    expect(hooks).toMatch(/\$\{ifNot\}\s+\$\{isUpdated\}/)
+  })
+})
diff --git a/src/main/daemon/daemon-host-relocation.ts b/src/main/daemon/daemon-host-relocation.ts
index a7e8f2b6db2..6d94bea06e4 100644
--- a/src/main/daemon/daemon-host-relocation.ts
+++ b/src/main/daemon/daemon-host-relocation.ts
@@ -34,7 +34,7 @@ export type RelocatedDaemonHost = {
 const HOST_SUBDIR = 'daemon-host'
 const MARKER_NAME = '.materialized.json'
 
-// LOCAL appData (not roaming) so OneDrive/roaming never syncs this ~260MB runtime. Shared with NSIS uninstall (config/nsis/daemon-host-uninstall.nsh) — keep in sync.
+// LOCAL appData (not roaming) so OneDrive/roaming never syncs this ~260MB runtime. Shared with NSIS uninstall (config/nsis/orca-installer-hooks.nsh) — keep in sync.
 const LOCAL_HOST_ROOT_NAME = 'Orca'
 
 // Copy of Orca.exe renamed to a distinct image name so the NSIS updater's `taskkill /IM Orca.exe` can't match it.
diff --git a/src/main/index.ts b/src/main/index.ts
index acf913b2c7a..522e59b908f 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -12,6 +12,7 @@ import { registerMainProcessIpcHandlers } from './startup/main-process-ipc-boots
 import { initializeMainProcessReady } from './startup/main-process-ready'
 import { installMainProcessQuitHandlers } from './startup/main-process-quit'
 import { shouldActivateDesktopForSecondInstance } from './startup/single-instance-lock'
+import { resolveOpenedMarkdownDocuments } from './startup/os-opened-markdown-files'
 
 function openMainWindow(options: { revealOnDidFinishLoad?: boolean } = {}): BrowserWindow {
   return openMainWindowController(options)
@@ -27,6 +28,7 @@ function requestDesktopActivation(argv: readonly string[] = []): void {
   state.skillShareDeepLinks.capture(argv, (shareId) => {
     state.mainWindow?.webContents.send('ui:openSkillShare', shareId)
   })
+  state.osOpenedMarkdownFiles.capture(argv, publishOsOpenedMarkdownFiles)
   // Why: a duplicate `orca serve` must not drag a headless server into opening a desktop window (#11935).
   if (!shouldActivateDesktopForSecondInstance(argv)) {
     return
@@ -34,6 +36,39 @@ function requestDesktopActivation(argv: readonly string[] = []): void {
   state.desktopActivationGate?.requestActivation()
 }
 
+/**
+ * Hands buffered OS-opened markdown paths to a renderer that has proven it is listening.
+ *
+ * Until that proof arrives the paths stay buffered, because `webContents.send` to a renderer
+ * with no listener attached is dropped silently and the queue would be gone.
+ */
+function publishOsOpenedMarkdownFiles(): void {
+  const targetWindow = state.mainWindow
+  if (!state.markdownFileOpenListenerReady || !targetWindow || targetWindow.isDestroyed()) {
+    return
+  }
+  // Why consumed before the await: a renderer pull racing this resolve must not take the same
+  // batch again. The restore() calls hand it back if delivery turns out to be impossible.
+  const filePaths = state.osOpenedMarkdownFiles.consume()
+  if (filePaths.length === 0) {
+    return
+  }
+  void resolveOpenedMarkdownDocuments(filePaths)
+    .then((documents) => {
+      if (targetWindow.isDestroyed() || targetWindow.webContents.isDestroyed()) {
+        state.osOpenedMarkdownFiles.restore(filePaths)
+        return
+      }
+      if (documents.length > 0) {
+        targetWindow.webContents.send('ui:openMarkdownFiles', documents)
+      }
+    })
+    .catch((error) => {
+      state.osOpenedMarkdownFiles.restore(filePaths)
+      console.warn('[os-open] Failed to resolve OS-opened markdown files:', error)
+    })
+}
+
 const handleMacAppActivation = createMacAppActivationHandler({
   getWindow: () => state.mainWindow,
   requestActivation: requestDesktopActivation
@@ -53,7 +88,22 @@ if (preflightReady) {
     event.preventDefault()
     requestDesktopActivation([url])
   })
+  // Why: macOS delivers "Open With" as open-file, often before `ready`, and only to a handler
+  // that claims the event. Non-markdown paths stay unclaimed so the OS default handler wins.
+  app.on('open-file', (event, filePath) => {
+    if (!state.osOpenedMarkdownFiles.captureFilePaths([filePath], publishOsOpenedMarkdownFiles)) {
+      return
+    }
+    event.preventDefault()
+    // Why gated on isReady: pre-ready the cold-start window is already on its way, and
+    // activating the gate here would try to open one before Electron can.
+    if (app.isReady()) {
+      requestDesktopActivation()
+    }
+  })
   state.skillShareDeepLinks.capture(process.argv)
+  // Why no publish: nothing is listening this early, so the first renderer pulls these on mount.
+  state.osOpenedMarkdownFiles.capture(process.argv)
   registerMainProcessIpcHandlers()
   installMainProcessQuitHandlers()
   void app.whenReady().then(async () => {
diff --git a/src/main/startup/main-process-ipc-bootstrap.ts b/src/main/startup/main-process-ipc-bootstrap.ts
index 3f364a9335c..89be84d2119 100644
--- a/src/main/startup/main-process-ipc-bootstrap.ts
+++ b/src/main/startup/main-process-ipc-bootstrap.ts
@@ -2,6 +2,7 @@ import { ipcMain } from 'electron'
 import { recoverLegacyWorkerTerminalsForRendererStartup } from './legacy-worker-renderer-recovery'
 import { logStartupMilestone } from './startup-diagnostics'
 import { mainProcessState as state } from './main-process-state'
+import { resolveOpenedMarkdownDocuments } from './os-opened-markdown-files'
 
 export function registerMainProcessIpcHandlers(): void {
   ipcMain.handle('app:awaitFirstWindowStartupServices', async () => {
@@ -36,6 +37,20 @@ export function registerMainProcessIpcHandlers(): void {
     state.pendingOpenSettings.matches(event.sender.id, { consume: true })
   )
   ipcMain.handle('ui:consumePendingSkillShare', () => state.skillShareDeepLinks.consume())
+  // Why: the renderer pulls this once its ui:openMarkdownFiles listener attaches, so a
+  // cold-start "Open With" queued before mount still opens. The pull doubles as the proof
+  // that the listener is live, which is what lets main start pushing.
+  ipcMain.handle('ui:consumePendingMarkdownFileOpens', async () => {
+    state.markdownFileOpenListenerReady = true
+    const filePaths = state.osOpenedMarkdownFiles.consume()
+    try {
+      return await resolveOpenedMarkdownDocuments(filePaths)
+    } catch (error) {
+      // Why restored: the renderer never received these, so a later mount must still get them.
+      state.osOpenedMarkdownFiles.restore(filePaths)
+      throw error
+    }
+  })
   ipcMain.handle(
     'app:startupDiagnostic',
     (_event, event: string, details?: Record<string, unknown>) => {
diff --git a/src/main/startup/main-process-state.ts b/src/main/startup/main-process-state.ts
index ea1e0a33299..05c45d5b567 100644
--- a/src/main/startup/main-process-state.ts
+++ b/src/main/startup/main-process-state.ts
@@ -36,6 +36,7 @@ import type { ServeOptions } from './main-process-serve'
 import type { HangDetectionMarker } from '../hang-watchdog/hang-detection-marker'
 import { ServeReadinessPublisher } from '../server/serve-readiness'
 import { SkillShareDeepLinkState } from './skill-share-deep-link-state'
+import { OsOpenedMarkdownFileState } from './os-opened-markdown-files'
 import {
   DEFAULT_GPU_CRASH_FALLBACK_THRESHOLD,
   DEFAULT_GPU_CRASH_FALLBACK_WINDOW_MS,
@@ -90,6 +91,12 @@ export const mainProcessState = {
   // Why: a tray "Settings…" click can precede the renderer's ui:openSettings listener; it pulls this one-shot on mount.
   pendingOpenSettings: createWebContentsTimedFlag(),
   skillShareDeepLinks: new SkillShareDeepLinkState(),
+  // Why: a Finder/Explorer "Open With" can land before any window exists; the renderer pulls this buffer on mount.
+  osOpenedMarkdownFiles: new OsOpenedMarkdownFileState(),
+  // Why a latch and not just "a window exists": a window can be up while its renderer has not
+  // attached the ui:openMarkdownFiles listener yet, and a push into that gap is dropped by
+  // Electron with no error. Only the renderer's own pull proves the listener is live.
+  markdownFileOpenListenerReady: false,
   firstWindowStartupServicesReady: Promise.resolve(),
   managedWslCliReconciliationReady: Promise.resolve(),
   managedWslCliStartupBarrierReady: Promise.resolve(),
diff --git a/src/main/startup/main-window-controller.ts b/src/main/startup/main-window-controller.ts
index 57763b23ab1..0d935d5f84a 100644
--- a/src/main/startup/main-window-controller.ts
+++ b/src/main/startup/main-window-controller.ts
@@ -145,6 +145,9 @@ export function openMainWindow(options: { revealOnDidFinishLoad?: boolean } = {}
     clearExpectedRendererReload(rendererWebContentsId)
     recordCrashBreadcrumb('main_window_loaded')
     logStartupMilestone('did-finish-load')
+    // Why cleared here: a reload drops the old ui:openMarkdownFiles listener, and the fresh
+    // renderer re-attaches by pulling. Pushing into the gap between would be silently lost.
+    state.markdownFileOpenListenerReady = false
     const currentStore = state.store
     if (currentStore && resolveConsent(currentStore.getSettings()).effective === 'enabled') {
       trackAppOpenedOnce()
diff --git a/src/main/startup/os-opened-markdown-delivery.test.ts b/src/main/startup/os-opened-markdown-delivery.test.ts
new file mode 100644
index 00000000000..0647516e3fa
--- /dev/null
+++ b/src/main/startup/os-opened-markdown-delivery.test.ts
@@ -0,0 +1,68 @@
+import { describe, expect, it, vi } from 'vitest'
+import { OsOpenedMarkdownFileState } from './os-opened-markdown-files'
+
+/**
+ * The two ways a queued "Open With" can be lost between main and the renderer. Both are
+ * about ownership: main must not drop paths it has not proven the renderer received.
+ */
+describe('os-opened markdown delivery ownership', () => {
+  it('keeps the batch when resolution rejects on the pull path', async () => {
+    const state = new OsOpenedMarkdownFileState()
+    state.captureFilePaths(['/notes/a.md'])
+    const resolve = vi.fn().mockRejectedValue(new Error('floating root unavailable'))
+
+    // Mirrors the ipcMain.handle('ui:consumePendingMarkdownFileOpens') body.
+    const pull = async (): Promise<unknown> => {
+      const filePaths = state.consume()
+      try {
+        return await resolve(filePaths)
+      } catch (error) {
+        state.restore(filePaths)
+        throw error
+      }
+    }
+
+    await expect(pull()).rejects.toThrow('floating root unavailable')
+    // Without the restore the file would be gone and no later mount could ever open it.
+    expect(state.consume()).toEqual(['/notes/a.md'])
+  })
+
+  it('holds the batch while the renderer listener is not yet attached', () => {
+    const state = new OsOpenedMarkdownFileState()
+    const send = vi.fn()
+    let listenerReady = false
+
+    // Mirrors publishOsOpenedMarkdownFiles()'s guard.
+    const publish = (): void => {
+      if (!listenerReady) {
+        return
+      }
+      const filePaths = state.consume()
+      if (filePaths.length > 0) {
+        send(filePaths)
+      }
+    }
+
+    // A window exists, but the renderer has not mounted its bridge yet: send() here would be
+    // dropped by Electron with no error, and consuming would destroy the queue.
+    state.captureFilePaths(['/notes/a.md'], publish)
+    expect(send).not.toHaveBeenCalled()
+
+    // The renderer's pull is what proves the listener is live.
+    listenerReady = true
+    state.captureFilePaths(['/notes/b.md'], publish)
+    expect(send).toHaveBeenCalledExactlyOnceWith(['/notes/a.md', '/notes/b.md'])
+    expect(state.consume()).toEqual([])
+  })
+
+  it('restores a batch the window could no longer receive', () => {
+    const state = new OsOpenedMarkdownFileState()
+    state.captureFilePaths(['/notes/a.md'])
+    const filePaths = state.consume()
+
+    // Window died between consume and send.
+    state.restore(filePaths)
+
+    expect(state.consume()).toEqual(['/notes/a.md'])
+  })
+})
diff --git a/src/main/startup/os-opened-markdown-files.test.ts b/src/main/startup/os-opened-markdown-files.test.ts
new file mode 100644
index 00000000000..f174e10d834
--- /dev/null
+++ b/src/main/startup/os-opened-markdown-files.test.ts
@@ -0,0 +1,306 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join, resolve, sep } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { isMarkdownDocumentName } from '../ipc/markdown-documents'
+import {
+  MAX_PENDING_OS_OPENED_MARKDOWN_FILES,
+  OsOpenedMarkdownFileState,
+  markdownPathsFromArguments,
+  resolveOpenedMarkdownDocuments
+} from './os-opened-markdown-files'
+
+vi.mock('../ipc/filesystem-auth', () => ({
+  authorizeExternalPath: vi.fn()
+}))
+vi.mock('../ipc/floating-workspace-directory', () => ({
+  ensureDefaultFloatingWorkspacePath: vi.fn()
+}))
+
+const { authorizeExternalPath } = await import('../ipc/filesystem-auth')
+const { ensureDefaultFloatingWorkspacePath } = await import('../ipc/floating-workspace-directory')
+
+describe('markdownPathsFromArguments', () => {
+  it('keeps absolute markdown paths and drops other extensions', () => {
+    expect(
+      markdownPathsFromArguments(
+        [
+          '/Users/dev/notes/a.md',
+          '/Users/dev/notes/b.markdown',
+          '/Users/dev/notes/c.mdx',
+          '/Users/dev/notes/d.txt',
+          '/Users/dev/src/e.tsx',
+          '/Users/dev/notes/README'
+        ],
+        'darwin'
+      )
+    ).toEqual(['/Users/dev/notes/a.md', '/Users/dev/notes/b.markdown', '/Users/dev/notes/c.mdx'])
+  })
+
+  it('drops switches, including Chromium-style ones that would otherwise look like values', () => {
+    expect(
+      markdownPathsFromArguments(
+        ['--serve', '-v', '--allow-file-access-from-files', '/Users/dev/notes/a.md'],
+        'darwin'
+      )
+    ).toEqual(['/Users/dev/notes/a.md'])
+  })
+
+  it('drops the executable and dev entries because none of them end in a markdown extension', () => {
+    const nonDocumentEntries = [
+      '/Applications/Orca.app/Contents/MacOS/Orca',
+      '/Users/dev/orca/out/main/index.js',
+      '/Applications/Orca.app/Contents/Resources/app.asar'
+    ]
+    // The module documents that the extension check alone excludes these; hold it to that.
+    for (const entry of nonDocumentEntries) {
+      expect(isMarkdownDocumentName(entry), entry).toBe(false)
+    }
+    expect(
+      markdownPathsFromArguments([...nonDocumentEntries, '/Users/dev/notes/a.md'], 'darwin')
+    ).toEqual(['/Users/dev/notes/a.md'])
+  })
+
+  it('drops relative paths because a second instance has no meaningful cwd', () => {
+    expect(
+      markdownPathsFromArguments(['readme.md', './docs/a.md', '../up.md', ''], 'darwin')
+    ).toEqual([])
+  })
+
+  it('accepts win32 drive-letter and UNC paths', () => {
+    expect(
+      markdownPathsFromArguments(
+        ['C:\\Users\\dev\\todo.md', '\\\\server\\share\\a.md', 'C:\\Users\\dev\\todo.txt'],
+        'win32'
+      )
+    ).toEqual(['C:\\Users\\dev\\todo.md', '\\\\server\\share\\a.md'])
+  })
+
+  it('dedupes case-insensitively on win32 and keeps the first spelling', () => {
+    expect(markdownPathsFromArguments(['C:\\notes\\A.md', 'c:\\notes\\a.md'], 'win32')).toEqual([
+      'C:\\notes\\A.md'
+    ])
+  })
+
+  it('normalizes parent segments before deduping', () => {
+    expect(
+      markdownPathsFromArguments(['C:\\notes\\sub\\..\\a.md', 'C:\\notes\\a.md'], 'win32')
+    ).toEqual(['C:\\notes\\a.md'])
+    expect(markdownPathsFromArguments(['/docs/../notes/a.md', '/notes/a.md'], 'darwin')).toEqual([
+      '/notes/a.md'
+    ])
+  })
+
+  it('does not dedupe case-insensitively on posix, where casing is a different file', () => {
+    expect(markdownPathsFromArguments(['/a/A.md', '/a/a.md'], 'linux')).toEqual([
+      '/a/A.md',
+      '/a/a.md'
+    ])
+  })
+
+  it('accepts a file:// URI, which the desktop entry %U field code permits', () => {
+    // Why defensive rather than load-bearing: GLib decodes a local file:// URI to a plain
+    // path before spawning (measured on Ubuntu 24.04), so Linux hits the plain-path branch
+    // today. The %U spec still allows a URI, and a launcher that passes one literally would
+    // otherwise be dropped without a trace.
+    expect(
+      markdownPathsFromArguments(
+        ['file:///home/me/notes/a.md', 'file:///home/me/notes/b.txt'],
+        'linux'
+      )
+    ).toEqual(['/home/me/notes/a.md'])
+  })
+
+  it('percent-decodes a file:// URI so a path with spaces still opens', () => {
+    expect(markdownPathsFromArguments(['file:///home/me/design%20notes.md'], 'linux')).toEqual([
+      '/home/me/design notes.md'
+    ])
+  })
+
+  it('decodes win32 file:// URIs, including UNC authority form', () => {
+    expect(
+      markdownPathsFromArguments(
+        ['file:///C:/Users/me/todo.md', 'file://server/share/a.md'],
+        'win32'
+      )
+    ).toEqual(['C:\\Users\\me\\todo.md', '\\\\server\\share\\a.md'])
+  })
+
+  it('dedupes a path delivered as both a URI and a bare path', () => {
+    expect(markdownPathsFromArguments(['file:///home/me/a.md', '/home/me/a.md'], 'linux')).toEqual([
+      '/home/me/a.md'
+    ])
+  })
+
+  it('drops a malformed or non-file URL instead of throwing', () => {
+    expect(() =>
+      markdownPathsFromArguments(['file://', 'file:///%zz.md', 'https://example.com/a.md'], 'linux')
+    ).not.toThrow()
+    expect(
+      markdownPathsFromArguments(['file://', 'file:///%zz.md', 'https://example.com/a.md'], 'linux')
+    ).toEqual([])
+  })
+
+  it('honours the platform argument rather than the host OS', () => {
+    const argv = ['C:\\notes\\a.md', '/notes/b.md']
+    // Same argv, two platforms: a win32 path is not absolute to posix, and posix input is
+    // renormalized to backslashes on win32. Neither result may depend on where the suite runs.
+    expect(markdownPathsFromArguments(argv, 'darwin')).toEqual(['/notes/b.md'])
+    expect(markdownPathsFromArguments(argv, 'win32')).toEqual(['C:\\notes\\a.md', '\\notes\\b.md'])
+  })
+})
+
+// Why resolve(): the state uses the host platform by default, so fixture paths must already be
+// spelled the way the host's path module normalizes them (`\n\a.md` and a drive on Windows).
+const hostPath = (name: string): string => resolve(sep, 'notes', name)
+
+describe('OsOpenedMarkdownFileState', () => {
+  it('reports no capture and does not publish when argv carries no markdown', () => {
+    const state = new OsOpenedMarkdownFileState()
+    const publish = vi.fn()
+
+    expect(state.capture(['/Applications/Orca.app/Contents/MacOS/Orca', '--serve'], publish)).toBe(
+      false
+    )
+    expect(publish).not.toHaveBeenCalled()
+    expect(state.consume()).toEqual([])
+  })
+
+  it('buffers and publishes when argv carries markdown', () => {
+    const state = new OsOpenedMarkdownFileState()
+    const publish = vi.fn()
+    const filePath = hostPath('a.md')
+
+    expect(state.capture(['/Applications/Orca.app/Contents/MacOS/Orca', filePath], publish)).toBe(
+      true
+    )
+    expect(publish).toHaveBeenCalledTimes(1)
+    expect(state.consume()).toEqual([filePath])
+  })
+
+  it('captures a single macOS open-file path', () => {
+    const state = new OsOpenedMarkdownFileState()
+    const publish = vi.fn()
+    const filePath = hostPath('a.md')
+
+    expect(state.captureFilePaths([filePath], publish)).toBe(true)
+    expect(state.captureFilePaths([hostPath('a.png')], publish)).toBe(false)
+    expect(publish).toHaveBeenCalledTimes(1)
+    expect(state.consume()).toEqual([filePath])
+  })
+
+  it('does not duplicate a path captured twice', () => {
+    const state = new OsOpenedMarkdownFileState()
+    const filePath = hostPath('a.md')
+
+    state.captureFilePaths([filePath])
+    state.captureFilePaths([filePath])
+    state.capture(['orca', filePath])
+
+    expect(state.consume()).toEqual([filePath])
+  })
+
+  it('drains the buffer on consume', () => {
+    const state = new OsOpenedMarkdownFileState()
+    const paths = [hostPath('a.md'), hostPath('b.md')]
+    state.captureFilePaths(paths)
+
+    expect(state.consume()).toEqual(paths)
+    expect(state.consume()).toEqual([])
+  })
+
+  it('restores an undelivered batch at the front of the buffer', () => {
+    const state = new OsOpenedMarkdownFileState()
+    state.captureFilePaths([hostPath('later.md')])
+
+    state.restore([hostPath('undelivered.md')])
+
+    expect(state.consume()).toEqual([hostPath('undelivered.md'), hostPath('later.md')])
+  })
+
+  it('caps the buffer when captures overflow it', () => {
+    const state = new OsOpenedMarkdownFileState()
+    const overflow = MAX_PENDING_OS_OPENED_MARKDOWN_FILES + 5
+    const paths = Array.from({ length: overflow }, (_, index) => hostPath(`file-${index}.md`))
+
+    expect(state.captureFilePaths(paths)).toBe(true)
+
+    expect(state.consume()).toEqual(paths.slice(0, MAX_PENDING_OS_OPENED_MARKDOWN_FILES))
+  })
+
+  it('caps the buffer when a restore overflows it', () => {
+    const state = new OsOpenedMarkdownFileState()
+    state.captureFilePaths([hostPath('pending.md')])
+    const restored = Array.from({ length: MAX_PENDING_OS_OPENED_MARKDOWN_FILES }, (_, index) =>
+      hostPath(`restored-${index}.md`)
+    )
+
+    state.restore(restored)
+
+    const pending = state.consume()
+    expect(pending).toHaveLength(MAX_PENDING_OS_OPENED_MARKDOWN_FILES)
+    expect(pending).toEqual(restored)
+  })
+})
+
+describe('resolveOpenedMarkdownDocuments', () => {
+  let floatingRoot: string
+  let fileRoot: string
+
+  beforeEach(async () => {
+    vi.mocked(authorizeExternalPath).mockClear()
+    vi.mocked(ensureDefaultFloatingWorkspacePath).mockClear()
+    floatingRoot = await mkdtemp(join(tmpdir(), 'orca-os-open-root-'))
+    fileRoot = await mkdtemp(join(tmpdir(), 'orca-os-open-files-'))
+    vi.mocked(ensureDefaultFloatingWorkspacePath).mockResolvedValue(floatingRoot)
+  })
+
+  afterEach(async () => {
+    await rm(floatingRoot, { recursive: true, force: true })
+    await rm(fileRoot, { recursive: true, force: true })
+  })
+
+  it('resolves a real file outside the floating root to a basename-relative document', async () => {
+    const filePath = join(fileRoot, 'design notes.md')
+    await writeFile(filePath, '# hi\n', 'utf8')
+
+    const documents = await resolveOpenedMarkdownDocuments([filePath])
+
+    expect(documents).toEqual([
+      {
+        filePath,
+        relativePath: 'design notes.md',
+        basename: 'design notes.md',
+        name: 'design notes'
+      }
+    ])
+    expect(authorizeExternalPath).toHaveBeenCalledWith(filePath)
+  })
+
+  it('drops a directory that merely looks like a markdown file', async () => {
+    const bundlePath = join(fileRoot, 'bundle.md')
+    await mkdir(bundlePath)
+    const filePath = join(fileRoot, 'real.md')
+    await writeFile(filePath, '# hi\n', 'utf8')
+
+    const documents = await resolveOpenedMarkdownDocuments([bundlePath, filePath])
+
+    expect(documents.map((document) => document.filePath)).toEqual([filePath])
+    // Security contract: a path we never validated must never be authorized for renderer reads.
+    expect(authorizeExternalPath).toHaveBeenCalledTimes(1)
+    expect(authorizeExternalPath).toHaveBeenCalledWith(filePath)
+  })
+
+  it('drops a path that no longer exists without authorizing it', async () => {
+    const missingPath = join(fileRoot, 'gone.md')
+
+    expect(await resolveOpenedMarkdownDocuments([missingPath])).toEqual([])
+    expect(authorizeExternalPath).not.toHaveBeenCalled()
+  })
+
+  it('returns nothing for an empty input without touching the filesystem', async () => {
+    expect(await resolveOpenedMarkdownDocuments([])).toEqual([])
+    expect(ensureDefaultFloatingWorkspacePath).not.toHaveBeenCalled()
+    expect(authorizeExternalPath).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/main/startup/os-opened-markdown-files.ts b/src/main/startup/os-opened-markdown-files.ts
new file mode 100644
index 00000000000..dae27fb7a78
--- /dev/null
+++ b/src/main/startup/os-opened-markdown-files.ts
@@ -0,0 +1,149 @@
+import { stat } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { MarkdownDocument } from '../../shared/filesystem-entry-types'
+import { authorizeExternalPath } from '../ipc/filesystem-auth'
+import { ensureDefaultFloatingWorkspacePath } from '../ipc/floating-workspace-directory'
+import { isMarkdownDocumentName, markdownDocumentFromFilePath } from '../ipc/markdown-documents'
+
+// Why: a shell can only ever hand over the files the user selected; anything past this is a
+// runaway argv, and buffering it unbounded would pin the paths for the whole session.
+export const MAX_PENDING_OS_OPENED_MARKDOWN_FILES = 32
+
+/**
+ * Resolves one argv entry to a local absolute path, or null if it is not one.
+ *
+ * Why file:// is accepted defensively: electron-builder appends the `%U` field code to the
+ * generated Linux `Exec=` line, and `%U` is specified as "URLs". GLib turns out to decode a
+ * local `file://` URI back to a plain path before spawning (measured on Ubuntu 24.04, via
+ * the same `launch_uris` call a file manager makes), so the branch below is not what fires
+ * there today — but the spec permits a URI, and a launcher that honours it literally would
+ * otherwise be silently dropped. macOS `open-file` and the Windows shell `%1` pass paths.
+ */
+function localPathFromArgument(argument: string, platform: NodeJS.Platform): string | null {
+  const pathApi = platform === 'win32' ? path.win32 : path.posix
+  if (argument.startsWith('file://')) {
+    try {
+      // Why the explicit windows flag: this must decode the same way on any host so the
+      // behaviour is testable, and it is what turns `file://server/share` back into a UNC path.
+      return fileURLToPath(argument, { windows: platform === 'win32' })
+    } catch {
+      return null
+    }
+  }
+  return pathApi.isAbsolute(argument) ? argument : null
+}
+
+/**
+ * Absolute markdown paths an OS "Open With" put on a launch or second-instance argv.
+ *
+ * Why no executable/asar/dev-entry filtering: none of those argv entries end in a markdown
+ * extension, so the extension check already excludes them. Relative entries are dropped
+ * because the shell always passes absolute paths and `cwd` is meaningless for a second instance.
+ */
+export function markdownPathsFromArguments(
+  argv: readonly string[],
+  platform: NodeJS.Platform = process.platform
+): string[] {
+  const pathApi = platform === 'win32' ? path.win32 : path.posix
+  const seen = new Set<string>()
+  const paths: string[] = []
+  for (const rawArgument of argv) {
+    if (!rawArgument || rawArgument.startsWith('-')) {
+      continue
+    }
+    const argument = localPathFromArgument(rawArgument, platform)
+    if (!argument || !isMarkdownDocumentName(argument)) {
+      continue
+    }
+    const normalized = pathApi.normalize(argument)
+    // Why lowercased on win32: the shell round-trips drive letters and 8.3 casing
+    // inconsistently, and two spellings of one path must not open two tabs.
+    const key = platform === 'win32' ? normalized.toLowerCase() : normalized
+    if (seen.has(key)) {
+      continue
+    }
+    seen.add(key)
+    paths.push(normalized)
+  }
+  return paths
+}
+
+/**
+ * Buffers markdown paths the OS handed us until a renderer can receive them.
+ *
+ * Mirrors SkillShareDeepLinkState: main pushes when a window is already live, and the
+ * renderer pulls the same buffer when its listener attaches, so a cold-start "Open With"
+ * that lands before mount is not dropped.
+ */
+export class OsOpenedMarkdownFileState {
+  private pending: string[] = []
+
+  /** Returns true when argv carried at least one markdown path. */
+  capture(argv: readonly string[], publish?: () => void): boolean {
+    return this.add(markdownPathsFromArguments(argv), publish)
+  }
+
+  /** Returns true when at least one path was a markdown document. */
+  captureFilePaths(filePaths: readonly string[], publish?: () => void): boolean {
+    return this.add(markdownPathsFromArguments(filePaths), publish)
+  }
+
+  consume(): string[] {
+    const pending = this.pending
+    this.pending = []
+    return pending
+  }
+
+  /** Puts an undelivered batch back at the front so the next renderer still receives it. */
+  restore(filePaths: readonly string[]): void {
+    this.pending = [...filePaths, ...this.pending].slice(0, MAX_PENDING_OS_OPENED_MARKDOWN_FILES)
+  }
+
+  private add(filePaths: readonly string[], publish?: () => void): boolean {
+    if (filePaths.length === 0) {
+      return false
+    }
+    const merged = [...this.pending]
+    for (const filePath of filePaths) {
+      if (!merged.includes(filePath)) {
+        merged.push(filePath)
+      }
+    }
+    this.pending = merged.slice(0, MAX_PENDING_OS_OPENED_MARKDOWN_FILES)
+    publish?.()
+    return true
+  }
+}
+
+/**
+ * Turns OS-handed paths into the same `MarkdownDocument` shape the floating workspace's own
+ * file picker produces, authorizing each one for the renderer's later read.
+ */
+export async function resolveOpenedMarkdownDocuments(
+  filePaths: readonly string[]
+): Promise<MarkdownDocument[]> {
+  if (filePaths.length === 0) {
+    return []
+  }
+  const floatingRoot = await ensureDefaultFloatingWorkspacePath()
+  const documents: MarkdownDocument[] = []
+  for (const filePath of filePaths) {
+    try {
+      // Why: the shell can hand over a bundle directory named `*.md`, or a path already
+      // deleted by the time we resolve. Authorize only something that is really a file.
+      if (!(await stat(filePath)).isFile()) {
+        continue
+      }
+    } catch {
+      continue
+    }
+    authorizeExternalPath(filePath)
+    documents.push(
+      markdownDocumentFromFilePath(floatingRoot, filePath, {
+        outsideRootRelativePath: 'basename'
+      })
+    )
+  }
+  return documents
+}
diff --git a/src/main/startup/os-opened-markdown-wiring.test.ts b/src/main/startup/os-opened-markdown-wiring.test.ts
new file mode 100644
index 00000000000..179ca0820ca
--- /dev/null
+++ b/src/main/startup/os-opened-markdown-wiring.test.ts
@@ -0,0 +1,57 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const read = (relativePath: string): string =>
+  // Why source text: this wiring is module-scope side effects in the entry point, which no
+  // unit test can import without booting Electron. These guards pin the call shapes instead.
+  readFileSync(join(process.cwd(), relativePath), 'utf8').replaceAll('"', "'")
+
+describe('os-opened markdown wiring', () => {
+  const index = read('src/main/index.ts')
+  const bootstrap = read('src/main/startup/main-process-ipc-bootstrap.ts')
+  const controller = read('src/main/startup/main-window-controller.ts')
+
+  it('captures argv before the serve-duplicate early return', () => {
+    const captureIndex = index.indexOf(
+      'state.osOpenedMarkdownFiles.capture(argv, publishOsOpenedMarkdownFiles)'
+    )
+    const serveGuardIndex = index.indexOf('if (!shouldActivateDesktopForSecondInstance(argv)) {')
+
+    expect(captureIndex).toBeGreaterThanOrEqual(0)
+    expect(serveGuardIndex).toBeGreaterThanOrEqual(0)
+    // A duplicate `orca serve` returns early; capturing after that would drop the user's files.
+    expect(captureIndex).toBeLessThan(serveGuardIndex)
+  })
+
+  it('claims the macOS open-file event so the default handler does not win it', () => {
+    const handlerIndex = index.indexOf("app.on('open-file'")
+    expect(handlerIndex).toBeGreaterThanOrEqual(0)
+
+    const preventDefaultIndex = index.indexOf('event.preventDefault()', handlerIndex)
+    const nextRegistrationIndex = index.indexOf('app.on(', handlerIndex + 1)
+    expect(preventDefaultIndex).toBeGreaterThan(handlerIndex)
+    if (nextRegistrationIndex !== -1) {
+      expect(preventDefaultIndex).toBeLessThan(nextRegistrationIndex)
+    }
+  })
+
+  it('captures the cold-start argv and lets the renderer pull it after mount', () => {
+    expect(index).toContain('state.osOpenedMarkdownFiles.capture(process.argv)')
+    expect(bootstrap).toContain("ipcMain.handle('ui:consumePendingMarkdownFileOpens'")
+  })
+
+  // Why: `webContents.send` to a renderer that has not attached the listener is dropped with no
+  // error, so publishing on "a window exists" alone would consume the queue into a void.
+  it('only pushes once the renderer has proven its listener is attached', () => {
+    expect(index).toContain('!state.markdownFileOpenListenerReady')
+    expect(bootstrap).toContain('state.markdownFileOpenListenerReady = true')
+    // A reload drops the listener; the fresh renderer re-proves itself by pulling again.
+    expect(controller).toContain('state.markdownFileOpenListenerReady = false')
+  })
+
+  it('restores an undelivered batch on both the push and the pull path', () => {
+    expect(index).toContain('state.osOpenedMarkdownFiles.restore(filePaths)')
+    expect(bootstrap).toContain('state.osOpenedMarkdownFiles.restore(filePaths)')
+  })
+})
diff --git a/src/preload/api/ui-bridge-state-and-menu-commands.ts b/src/preload/api/ui-bridge-state-and-menu-commands.ts
index 25476165cfb..34eb83886c8 100644
--- a/src/preload/api/ui-bridge-state-and-menu-commands.ts
+++ b/src/preload/api/ui-bridge-state-and-menu-commands.ts
@@ -1,3 +1,4 @@
+import type { MarkdownDocument } from '../../shared/filesystem-entry-types'
 import { ipcRenderer } from 'electron'
 import type { PersistedUIState } from '../../shared/persisted-ui-state-types'
 import type { KeybindingActionId } from '../../shared/keybindings'
@@ -26,6 +27,14 @@ export const uiStateAndMenuCommandsApi = {
   },
   consumePendingSkillShare: (): Promise<string | null> =>
     ipcRenderer.invoke('ui:consumePendingSkillShare'),
+  onOpenMarkdownFiles: (callback: (documents: MarkdownDocument[]) => void): (() => void) => {
+    const listener = (_event: Electron.IpcRendererEvent, documents: MarkdownDocument[]): void =>
+      callback(documents)
+    ipcRenderer.on('ui:openMarkdownFiles', listener)
+    return () => ipcRenderer.removeListener('ui:openMarkdownFiles', listener)
+  },
+  consumePendingMarkdownFileOpens: (): Promise<MarkdownDocument[]> =>
+    ipcRenderer.invoke('ui:consumePendingMarkdownFileOpens'),
   onOpenSetupGuide: (callback: () => void): (() => void) => {
     const listener = (_event: Electron.IpcRendererEvent) => callback()
     ipcRenderer.on('ui:openSetupGuide', listener)
diff --git a/src/preload/api/ui-command-event-api.ts b/src/preload/api/ui-command-event-api.ts
index e63034b5233..0876104e471 100644
--- a/src/preload/api/ui-command-event-api.ts
+++ b/src/preload/api/ui-command-event-api.ts
@@ -1,3 +1,4 @@
+import type { MarkdownDocument } from '../../shared/filesystem-entry-types'
 import type { PersistedUIState } from '../../shared/persisted-ui-state-types'
 import type { TuiAgent } from '../../shared/tui-agent'
 import type {
@@ -48,6 +49,10 @@ export type UiCommandEventApi = {
   consumePendingOpenSettings: () => Promise<boolean>
   onOpenSkillShare: (callback: (shareId: string) => void) => () => void
   consumePendingSkillShare: () => Promise<string | null>
+  /** OS "Open With" markdown paths pushed while a renderer is already listening. */
+  onOpenMarkdownFiles: (callback: (documents: MarkdownDocument[]) => void) => () => void
+  /** Drains the "Open With" paths queued before this renderer's listener attached. */
+  consumePendingMarkdownFileOpens: () => Promise<MarkdownDocument[]>
   onOpenSetupGuide: (callback: () => void) => () => void
   onOpenFeatureTour: (callback: () => void) => () => void
   onOpenCrashReport: (callback: () => void) => () => void
diff --git a/src/renderer/src/components/floating-terminal/use-floating-terminal-create-actions.ts b/src/renderer/src/components/floating-terminal/use-floating-terminal-create-actions.ts
index a60cdc7d93e..8ef85f7e556 100644
--- a/src/renderer/src/components/floating-terminal/use-floating-terminal-create-actions.ts
+++ b/src/renderer/src/components/floating-terminal/use-floating-terminal-create-actions.ts
@@ -4,7 +4,7 @@ import { resolveGroupTabFromVisibleId } from '@/components/tab-group/tab-group-v
 import { getConnectionId } from '@/lib/connection-context'
 import { createUntitledMarkdownFileWithTemplateSelection } from '@/lib/create-untitled-markdown'
 import { ensureClientCreationActionAllowed } from '@/lib/client-creation-action-error'
-import { detectLanguage } from '@/lib/language-detect'
+import { openMarkdownDocumentInFloatingWorkspace } from '@/lib/open-markdown-in-floating-workspace'
 import { extractIpcErrorMessage } from '@/lib/ipc-error'
 import { focusTerminalTabSurface } from '@/lib/focus-terminal-tab-surface'
 import { translate } from '@/i18n/i18n'
@@ -123,21 +123,9 @@ export function useFloatingTerminalCreateActions({
         if (!document) {
           return
         }
-        openFile(
-          {
-            filePath: document.filePath,
-            relativePath: document.relativePath,
-            worktreeId: FLOATING_TERMINAL_WORKTREE_ID,
-            language: detectLanguage(document.relativePath),
-            mode: 'edit',
-            runtimeEnvironmentId: null
-          },
-          {
-            preview: false,
-            targetGroupId: activeGroup?.id,
-            suppressActiveRuntimeFallback: true
-          }
-        )
+        openMarkdownDocumentInFloatingWorkspace(openFile, document, {
+          targetGroupId: activeGroup?.id
+        })
       } catch (error) {
         toast.error(extractIpcErrorMessage(error, 'Failed to open markdown file.'))
       }
diff --git a/src/renderer/src/hooks/ipc-events/app-lifetime-ipc-bridge.ts b/src/renderer/src/hooks/ipc-events/app-lifetime-ipc-bridge.ts
index 7aa5dd418cf..d105db1d3e9 100644
--- a/src/renderer/src/hooks/ipc-events/app-lifetime-ipc-bridge.ts
+++ b/src/renderer/src/hooks/ipc-events/app-lifetime-ipc-bridge.ts
@@ -12,6 +12,7 @@ import { createDirectSshBridgeRuntime } from './direct-ssh-bridge-runtime'
 import { registerDirectSshStateIpcBridge } from './direct-ssh-state-ipc-bridge'
 import { registerMobileAndTerminalCloseIpcBridge } from './mobile-terminal-close-ipc-bridge'
 import { registerMobileDriverIpcBridge } from './mobile-driver-ipc-bridge'
+import { registerOsMarkdownFileOpenBridge } from './os-markdown-file-open-bridge'
 import { registerProjectCatalogIpcBridge } from './project-catalog-ipc-bridge'
 import { registerRateLimitIpcBridge } from './rate-limit-ipc-bridge'
 import { registerRemoteWorkspaceIpcBridge } from './remote-workspace-ipc-bridge'
@@ -77,6 +78,7 @@ export function installAppLifetimeIpcEvents(
   )
   registerSettingsAndSidebarIpcBridge(unsubs)
   registerWorkspaceShortcutIpcBridge(unsubs)
+  registerOsMarkdownFileOpenBridge(unsubs)
   unsubs.push(
     window.api.ui.onActivateWorktree(({ repoId, worktreeId, setup, startup, defaultTabs }) => {
       void worktreeRuntime
diff --git a/src/renderer/src/hooks/ipc-events/os-markdown-file-open-bridge.test.ts b/src/renderer/src/hooks/ipc-events/os-markdown-file-open-bridge.test.ts
new file mode 100644
index 00000000000..d4825e89206
--- /dev/null
+++ b/src/renderer/src/hooks/ipc-events/os-markdown-file-open-bridge.test.ts
@@ -0,0 +1,300 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { TOGGLE_FLOATING_TERMINAL_EVENT } from '@/lib/floating-terminal'
+import type { EditorFilesSlice } from '@/store/slices/editor/types/editor-files-slice'
+import type { MarkdownDocument } from '../../../../shared/filesystem-entry-types'
+import { FLOATING_TERMINAL_WORKTREE_ID } from '../../../../shared/constants'
+import { registerOsMarkdownFileOpenBridge } from './os-markdown-file-open-bridge'
+
+const mocks = vi.hoisted(() => ({
+  openFile: vi.fn<EditorFilesSlice['openFile']>(() => 'file-1'),
+  updateSettings: vi.fn(async () => {}),
+  isFloatingWorkspacePanelVisible: vi.fn(() => false),
+  toastError: vi.fn()
+}))
+
+let storeState: {
+  openFile: typeof mocks.openFile
+  updateSettings: typeof mocks.updateSettings
+  settings: { floatingTerminalEnabled?: boolean } | undefined
+}
+
+vi.mock('../../store', () => ({ useAppStore: { getState: () => storeState } }))
+vi.mock('@/lib/floating-workspace-terminal-actions', () => ({
+  isFloatingWorkspacePanelVisible: mocks.isFloatingWorkspacePanelVisible
+}))
+vi.mock('sonner', () => ({ toast: { error: mocks.toastError } }))
+vi.mock('@/i18n/i18n', () => ({ translate: (_key: string, fallback: string) => fallback }))
+
+type MarkdownFileOpenListener = (documents: MarkdownDocument[]) => void
+
+let frames: FrameRequestCallback[] = []
+let dispatchEvent = vi.fn()
+let unhandledRejections: unknown[] = []
+const recordUnhandledRejection = (reason: unknown): void => void unhandledRejections.push(reason)
+
+function markdownDocument(overrides: Partial<MarkdownDocument> = {}): MarkdownDocument {
+  return {
+    filePath: '/Users/me/notes/README.md',
+    relativePath: 'README.md',
+    basename: 'README.md',
+    name: 'README',
+    ...overrides
+  }
+}
+
+function stubPreload(ui: Record<string, unknown>): void {
+  dispatchEvent = vi.fn()
+  vi.stubGlobal('window', { api: { ui }, dispatchEvent })
+}
+
+/** Runs the callbacks the bridge deferred to the next frame. */
+function runFrames(): void {
+  const pending = frames
+  frames = []
+  for (const frame of pending) {
+    frame(0)
+  }
+}
+
+/** Drains microtasks and lets Node emit any unhandled rejection the bridge leaked. */
+async function settle(): Promise<void> {
+  await new Promise((resolve) => setImmediate(resolve))
+  await new Promise((resolve) => setImmediate(resolve))
+}
+
+describe('registerOsMarkdownFileOpenBridge', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    frames = []
+    unhandledRejections = []
+    storeState = {
+      openFile: mocks.openFile,
+      updateSettings: mocks.updateSettings,
+      settings: { floatingTerminalEnabled: true }
+    }
+    mocks.openFile.mockReturnValue('file-1')
+    mocks.updateSettings.mockResolvedValue(undefined)
+    mocks.isFloatingWorkspacePanelVisible.mockReturnValue(false)
+    vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) =>
+      frames.push(callback)
+    )
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+    process.on('unhandledRejection', recordUnhandledRejection)
+  })
+
+  afterEach(() => {
+    process.off('unhandledRejection', recordUnhandledRejection)
+    vi.unstubAllGlobals()
+    vi.restoreAllMocks()
+  })
+
+  it('opens every document main queued before the listener attached', async () => {
+    stubPreload({
+      onOpenMarkdownFiles: () => () => {},
+      consumePendingMarkdownFileOpens: () =>
+        Promise.resolve([
+          markdownDocument(),
+          markdownDocument({ filePath: '/Users/me/notes/plan.md', relativePath: 'plan.md' })
+        ])
+    })
+
+    registerOsMarkdownFileOpenBridge([])
+    await settle()
+
+    expect(mocks.openFile).toHaveBeenCalledTimes(2)
+    expect(mocks.openFile.mock.calls.map((call) => call[0].filePath)).toEqual([
+      '/Users/me/notes/README.md',
+      '/Users/me/notes/plan.md'
+    ])
+    expect(mocks.openFile.mock.calls[0][0].worktreeId).toBe(FLOATING_TERMINAL_WORKTREE_ID)
+  })
+
+  it('opens documents pushed after startup and hands back the unsubscribe', async () => {
+    const listeners: MarkdownFileOpenListener[] = []
+    const unsubscribe = vi.fn()
+    stubPreload({
+      onOpenMarkdownFiles: (next: MarkdownFileOpenListener) => {
+        listeners.push(next)
+        return unsubscribe
+      },
+      consumePendingMarkdownFileOpens: () => Promise.resolve([])
+    })
+
+    const unsubs: (() => void)[] = []
+    registerOsMarkdownFileOpenBridge(unsubs)
+    expect(unsubs).toEqual([unsubscribe])
+
+    listeners[0]([
+      markdownDocument({ filePath: '/Users/me/notes/live.md', relativePath: 'live.md' })
+    ])
+    await settle()
+
+    expect(mocks.openFile).toHaveBeenCalledTimes(1)
+    expect(mocks.openFile.mock.calls[0][0].filePath).toBe('/Users/me/notes/live.md')
+
+    unsubs.forEach((teardown) => teardown())
+    expect(unsubscribe).toHaveBeenCalledOnce()
+  })
+
+  it('enables the floating workspace when the setting is off', async () => {
+    storeState.settings = { floatingTerminalEnabled: false }
+    stubPreload({
+      onOpenMarkdownFiles: () => () => {},
+      consumePendingMarkdownFileOpens: () => Promise.resolve([markdownDocument()])
+    })
+
+    registerOsMarkdownFileOpenBridge([])
+    await settle()
+
+    expect(mocks.updateSettings).toHaveBeenCalledWith({ floatingTerminalEnabled: true })
+  })
+
+  it('leaves settings alone when the floating workspace is already enabled', async () => {
+    stubPreload({
+      onOpenMarkdownFiles: () => () => {},
+      consumePendingMarkdownFileOpens: () => Promise.resolve([markdownDocument()])
+    })
+
+    registerOsMarkdownFileOpenBridge([])
+    await settle()
+
+    expect(mocks.updateSettings).not.toHaveBeenCalled()
+  })
+
+  it('defers the reveal a frame and toggles only while the panel is hidden', async () => {
+    stubPreload({
+      onOpenMarkdownFiles: () => () => {},
+      consumePendingMarkdownFileOpens: () => Promise.resolve([markdownDocument()])
+    })
+
+    registerOsMarkdownFileOpenBridge([])
+    await settle()
+
+    expect(dispatchEvent).not.toHaveBeenCalled()
+    runFrames()
+
+    expect(dispatchEvent).toHaveBeenCalledTimes(1)
+    expect(dispatchEvent.mock.calls[0][0].type).toBe(TOGGLE_FLOATING_TERMINAL_EVENT)
+  })
+
+  it('does not toggle when the panel is already visible', async () => {
+    mocks.isFloatingWorkspacePanelVisible.mockReturnValue(true)
+    stubPreload({
+      onOpenMarkdownFiles: () => () => {},
+      consumePendingMarkdownFileOpens: () => Promise.resolve([markdownDocument()])
+    })
+
+    registerOsMarkdownFileOpenBridge([])
+    await settle()
+    runFrames()
+
+    expect(dispatchEvent).not.toHaveBeenCalled()
+  })
+
+  it('ignores an empty batch', async () => {
+    storeState.settings = { floatingTerminalEnabled: false }
+    stubPreload({
+      onOpenMarkdownFiles: () => () => {},
+      consumePendingMarkdownFileOpens: () => Promise.resolve([])
+    })
+
+    registerOsMarkdownFileOpenBridge([])
+    await settle()
+    runFrames()
+
+    expect(mocks.openFile).not.toHaveBeenCalled()
+    expect(mocks.updateSettings).not.toHaveBeenCalled()
+    expect(dispatchEvent).not.toHaveBeenCalled()
+  })
+
+  it('reports a rejected pending drain without leaking an unhandled rejection', async () => {
+    stubPreload({
+      onOpenMarkdownFiles: () => () => {},
+      consumePendingMarkdownFileOpens: () => Promise.reject(new Error('ipc unavailable'))
+    })
+
+    registerOsMarkdownFileOpenBridge([])
+    await settle()
+
+    expect(mocks.toastError).toHaveBeenCalledWith('Failed to open the Markdown file.')
+    // Why: App.tsx awaits hydration around this registration and treats any throw as
+    // "session restore failed", so the bridge must swallow its own failures.
+    expect(unhandledRejections).toEqual([])
+  })
+
+  it('reports a throwing openFile without leaking an unhandled rejection', async () => {
+    mocks.openFile.mockImplementation(() => {
+      throw new Error('editor slice exploded')
+    })
+    const listeners: MarkdownFileOpenListener[] = []
+    stubPreload({
+      onOpenMarkdownFiles: (next: MarkdownFileOpenListener) => {
+        listeners.push(next)
+        return () => {}
+      },
+      consumePendingMarkdownFileOpens: () => Promise.resolve([])
+    })
+
+    registerOsMarkdownFileOpenBridge([])
+    expect(() => listeners[0]([markdownDocument()])).not.toThrow()
+    await settle()
+
+    expect(mocks.toastError).toHaveBeenCalledWith('Failed to open the Markdown file.')
+    expect(unhandledRejections).toEqual([])
+    expect(dispatchEvent).not.toHaveBeenCalled()
+  })
+
+  it('keeps opening the rest of a batch when one document fails', async () => {
+    mocks.openFile.mockImplementationOnce(() => {
+      throw new Error('first document exploded')
+    })
+    stubPreload({
+      onOpenMarkdownFiles: () => () => {},
+      consumePendingMarkdownFileOpens: () =>
+        Promise.resolve([
+          markdownDocument({ filePath: '/Users/me/notes/bad.md', relativePath: 'bad.md' }),
+          markdownDocument({ filePath: '/Users/me/notes/good.md', relativePath: 'good.md' })
+        ])
+    })
+
+    registerOsMarkdownFileOpenBridge([])
+    await settle()
+    runFrames()
+
+    // Why: a multi-file selection arrives as one batch; one bad file must not cost the rest.
+    expect(mocks.openFile).toHaveBeenCalledTimes(2)
+    expect(mocks.toastError).toHaveBeenCalledTimes(1)
+    expect(dispatchEvent).toHaveBeenCalledTimes(1)
+    expect(unhandledRejections).toEqual([])
+  })
+
+  it('ignores a non-array payload from a mismatched preload', async () => {
+    stubPreload({
+      onOpenMarkdownFiles: () => () => {},
+      // Why: the payload crosses the preload boundary, so a stale preload can resolve with
+      // something that is not an array. Reading .length off it would throw inside the chain.
+      consumePendingMarkdownFileOpens: () => Promise.resolve(null as unknown as MarkdownDocument[])
+    })
+
+    registerOsMarkdownFileOpenBridge([])
+    await settle()
+    runFrames()
+
+    expect(mocks.openFile).not.toHaveBeenCalled()
+    expect(mocks.updateSettings).not.toHaveBeenCalled()
+    expect(mocks.toastError).not.toHaveBeenCalled()
+    expect(unhandledRejections).toEqual([])
+  })
+
+  it('tolerates a preload without the markdown open channel', async () => {
+    stubPreload({})
+
+    const unsubs: (() => void)[] = []
+    expect(() => registerOsMarkdownFileOpenBridge(unsubs)).not.toThrow()
+    await settle()
+
+    expect(unsubs).toEqual([])
+    expect(mocks.openFile).not.toHaveBeenCalled()
+    expect(mocks.toastError).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/renderer/src/hooks/ipc-events/os-markdown-file-open-bridge.ts b/src/renderer/src/hooks/ipc-events/os-markdown-file-open-bridge.ts
new file mode 100644
index 00000000000..3dd345da07c
--- /dev/null
+++ b/src/renderer/src/hooks/ipc-events/os-markdown-file-open-bridge.ts
@@ -0,0 +1,72 @@
+import { toast } from 'sonner'
+import type { MarkdownDocument } from '../../../../shared/filesystem-entry-types'
+import { TOGGLE_FLOATING_TERMINAL_EVENT } from '@/lib/floating-terminal'
+import { isFloatingWorkspacePanelVisible } from '@/lib/floating-workspace-terminal-actions'
+import { openMarkdownDocumentInFloatingWorkspace } from '@/lib/open-markdown-in-floating-workspace'
+import { translate } from '@/i18n/i18n'
+import { useAppStore } from '../../store'
+
+/**
+ * Opens markdown files the OS shell handed to Orca ("Open With" / double-click) in the
+ * floating workspace, which is the one editor surface that needs no project.
+ */
+async function openOsRequestedMarkdownFiles(documents: MarkdownDocument[]): Promise<void> {
+  // Why the shape check: this payload crosses the preload boundary, so a stale or mismatched
+  // preload can hand back something that is not an array. Reading .length off that throws
+  // inside the promise chain rather than failing loudly at the boundary.
+  if (!Array.isArray(documents) || documents.length === 0) {
+    return
+  }
+  const store = useAppStore.getState()
+  let opened = 0
+  for (const document of documents) {
+    // Why isolated: selecting several files hands us one batch, and one unopenable file
+    // must not cost the user the rest of the selection.
+    try {
+      openMarkdownDocumentInFloatingWorkspace(store.openFile, document)
+      opened += 1
+    } catch (error) {
+      reportOsRequestedMarkdownFailure(error)
+    }
+  }
+  if (opened === 0) {
+    return
+  }
+  // Why enabled here: the user asked the OS for this file, and the tabs above are already in a
+  // surface a disabled floating workspace never renders. Same enable-then-reveal as the
+  // Settings "Edit keybindings in Orca" action.
+  if (store.settings?.floatingTerminalEnabled !== true) {
+    await store.updateSettings({ floatingTerminalEnabled: true })
+  }
+  // Why deferred a frame: the panel only honors the toggle once the enabled flag has reached React.
+  requestAnimationFrame(() => {
+    if (!isFloatingWorkspacePanelVisible()) {
+      window.dispatchEvent(new CustomEvent(TOGGLE_FLOATING_TERMINAL_EVENT))
+    }
+  })
+}
+
+function reportOsRequestedMarkdownFailure(error: unknown): void {
+  console.error('Failed to open markdown files requested by the OS:', error)
+  toast.error(
+    translate(
+      'auto.hooks.ipc.events.os.markdown.file.open.bridge.1e9a1a63c4',
+      'Failed to open the Markdown file.'
+    )
+  )
+}
+
+export function registerOsMarkdownFileOpenBridge(unsubs: (() => void)[]): void {
+  const unsubscribe = window.api.ui.onOpenMarkdownFiles?.((documents) => {
+    void openOsRequestedMarkdownFiles(documents).catch(reportOsRequestedMarkdownFailure)
+  })
+  if (unsubscribe) {
+    unsubs.push(unsubscribe)
+  }
+
+  // Why: a cold-start "Open With" resolves before this listener attaches; drain what main queued.
+  const pending = window.api.ui.consumePendingMarkdownFileOpens?.()
+  if (pending && typeof pending.then === 'function') {
+    void pending.then(openOsRequestedMarkdownFiles).catch(reportOsRequestedMarkdownFailure)
+  }
+}
diff --git a/src/renderer/src/hooks/useIpcEvents-lifecycle.test.ts b/src/renderer/src/hooks/useIpcEvents-lifecycle.test.ts
index 5155aa6881f..67872949590 100644
--- a/src/renderer/src/hooks/useIpcEvents-lifecycle.test.ts
+++ b/src/renderer/src/hooks/useIpcEvents-lifecycle.test.ts
@@ -55,6 +55,7 @@ const EXPECTED_DIRECT_CALLBACK_METHODS = [
   'ui.onOpenDiffFromMobile',
   'ui.onOpenFeatureTour',
   'ui.onOpenFileFromMobile',
+  'ui.onOpenMarkdownFiles',
   'ui.onOpenNewWorkspace',
   'ui.onOpenQuickOpen',
   'ui.onOpenSettings',
@@ -135,6 +136,7 @@ const EXPECTED_CALLBACK_REGISTRATION_SEQUENCE = [
   'ui.onJumpToTabIndex',
   'ui.onWorktreeHistoryNavigate',
   'ui.onToggleStatusBar',
+  'ui.onOpenMarkdownFiles',
   'ui.onActivateWorktree',
   'ui.onCreateTerminal',
   'ui.onRequestTerminalTabMount',
diff --git a/src/renderer/src/i18n/locales/en.json b/src/renderer/src/i18n/locales/en.json
index c04b2f260e9..7fc9c837ebc 100644
--- a/src/renderer/src/i18n/locales/en.json
+++ b/src/renderer/src/i18n/locales/en.json
@@ -1112,6 +1112,17 @@
         "events": {
           "browserStateIpcBridge": {
             "docPreviewLinkFailed": "Could not open this link in Orca Browser."
+          },
+          "os": {
+            "markdown": {
+              "file": {
+                "open": {
+                  "bridge": {
+                    "1e9a1a63c4": "Failed to open the Markdown file."
+                  }
+                }
+              }
+            }
           }
         }
       }
diff --git a/src/renderer/src/lib/open-markdown-in-floating-workspace.test.ts b/src/renderer/src/lib/open-markdown-in-floating-workspace.test.ts
new file mode 100644
index 00000000000..62fc278fc7a
--- /dev/null
+++ b/src/renderer/src/lib/open-markdown-in-floating-workspace.test.ts
@@ -0,0 +1,81 @@
+import { describe, expect, it, vi } from 'vitest'
+import { FLOATING_TERMINAL_WORKTREE_ID } from '../../../shared/constants'
+import type { MarkdownDocument } from '../../../shared/filesystem-entry-types'
+import type { EditorFilesSlice } from '@/store/slices/editor/types/editor-files-slice'
+import { openMarkdownDocumentInFloatingWorkspace } from './open-markdown-in-floating-workspace'
+
+function openFileMock(): ReturnType<typeof vi.fn<EditorFilesSlice['openFile']>> {
+  return vi.fn<EditorFilesSlice['openFile']>(() => 'file-1')
+}
+
+function markdownDocument(overrides: Partial<MarkdownDocument> = {}): MarkdownDocument {
+  return {
+    filePath: '/Users/me/notes/README.md',
+    relativePath: 'README.md',
+    basename: 'README.md',
+    name: 'README',
+    ...overrides
+  }
+}
+
+describe('openMarkdownDocumentInFloatingWorkspace', () => {
+  it('opens the document as a permanent floating-workspace edit tab', () => {
+    const openFile = openFileMock()
+
+    const fileId = openMarkdownDocumentInFloatingWorkspace(openFile, markdownDocument())
+
+    expect(fileId).toBe('file-1')
+    expect(openFile).toHaveBeenCalledTimes(1)
+    expect(openFile.mock.calls[0][0]).toEqual({
+      filePath: '/Users/me/notes/README.md',
+      relativePath: 'README.md',
+      worktreeId: FLOATING_TERMINAL_WORKTREE_ID,
+      language: 'markdown',
+      mode: 'edit',
+      runtimeEnvironmentId: null
+    })
+    expect(openFile.mock.calls[0][1]).toEqual({
+      preview: false,
+      targetGroupId: undefined,
+      suppressActiveRuntimeFallback: true
+    })
+  })
+
+  it('pins the open to this machine instead of the active runtime', () => {
+    const openFile = openFileMock()
+
+    openMarkdownDocumentInFloatingWorkspace(openFile, markdownDocument())
+
+    // Why: the caller already resolved an absolute local path, so a null runtime plus the
+    // fallback suppression is what keeps the read off a remote SSH host the user is focused on.
+    // Dropping either one silently reads the file on the wrong machine.
+    expect(openFile.mock.calls[0][0].runtimeEnvironmentId).toBeNull()
+    expect(openFile.mock.calls[0][1]?.suppressActiveRuntimeFallback).toBe(true)
+  })
+
+  it('derives the language from the relative path', () => {
+    const openFile = openFileMock()
+
+    openMarkdownDocumentInFloatingWorkspace(
+      openFile,
+      markdownDocument({
+        filePath: '/Users/me/notes/plan.mdx',
+        relativePath: 'plan.mdx',
+        basename: 'plan.mdx',
+        name: 'plan'
+      })
+    )
+
+    expect(openFile.mock.calls[0][0].language).toBe('markdown')
+  })
+
+  it('forwards a requested target group', () => {
+    const openFile = openFileMock()
+
+    openMarkdownDocumentInFloatingWorkspace(openFile, markdownDocument(), {
+      targetGroupId: 'group-2'
+    })
+
+    expect(openFile.mock.calls[0][1]?.targetGroupId).toBe('group-2')
+  })
+})
diff --git a/src/renderer/src/lib/open-markdown-in-floating-workspace.ts b/src/renderer/src/lib/open-markdown-in-floating-workspace.ts
new file mode 100644
index 00000000000..3b1bd4cd08b
--- /dev/null
+++ b/src/renderer/src/lib/open-markdown-in-floating-workspace.ts
@@ -0,0 +1,32 @@
+import type { MarkdownDocument } from '../../../shared/filesystem-entry-types'
+import { FLOATING_TERMINAL_WORKTREE_ID } from '../../../shared/constants'
+import type { EditorFilesSlice } from '@/store/slices/editor/types/editor-files-slice'
+import { detectLanguage } from './language-detect'
+
+/**
+ * Opens a markdown file that belongs to no workspace as a floating-workspace editor tab.
+ *
+ * Why local-only: every caller resolves an absolute path on this machine (a native picker or
+ * the OS shell), so routing it through the active runtime would read it on the wrong host.
+ */
+export function openMarkdownDocumentInFloatingWorkspace(
+  openFile: EditorFilesSlice['openFile'],
+  document: MarkdownDocument,
+  options: { targetGroupId?: string } = {}
+): string {
+  return openFile(
+    {
+      filePath: document.filePath,
+      relativePath: document.relativePath,
+      worktreeId: FLOATING_TERMINAL_WORKTREE_ID,
+      language: detectLanguage(document.relativePath),
+      mode: 'edit',
+      runtimeEnvironmentId: null
+    },
+    {
+      preview: false,
+      targetGroupId: options.targetGroupId,
+      suppressActiveRuntimeFallback: true
+    }
+  )
+}
diff --git a/src/renderer/src/web/preload-api/web-ui-api.ts b/src/renderer/src/web/preload-api/web-ui-api.ts
index 8c6e4d73a95..ca67f5664a9 100644
--- a/src/renderer/src/web/preload-api/web-ui-api.ts
+++ b/src/renderer/src/web/preload-api/web-ui-api.ts
@@ -157,6 +157,9 @@ export function createWebUiApi(): NonNullable<Partial<PreloadApi>['ui']> {
     consumePendingOpenSettings: () => Promise.resolve(false),
     onOpenSkillShare: () => noopUnsubscribe,
     consumePendingSkillShare: () => Promise.resolve(null),
+    // Why: the web client has no OS shell handing it files, so there is never a queued open.
+    onOpenMarkdownFiles: () => noopUnsubscribe,
+    consumePendingMarkdownFileOpens: () => Promise.resolve([]),
     onOpenSetupGuide: () => noopUnsubscribe,
     onOpenFeatureTour: () => noopUnsubscribe,
     onOpenCrashReport: () => noopUnsubscribe,

From 894c5fe36a7755325407ccc745ce450fbf7c737a Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Tue, 1 Sep 2026 17:06:16 -0700
Subject: [PATCH 17/32] test(orchestration): fail loudly on an unexpected
 second detection call

The mock overwrote resolveDetection on every call, so a second invocation would
strand the first promise and hang to a 30s timeout instead of naming what
changed. A test that hangs rather than fails is how a real bug gets mistaken for
infrastructure noise.
---
 .../orchestration-legacy-coordinator-race.test.ts  | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/src/main/runtime/rpc/orchestration-legacy-coordinator-race.test.ts b/src/main/runtime/rpc/orchestration-legacy-coordinator-race.test.ts
index 9236d643e40..3040c37a9ef 100644
--- a/src/main/runtime/rpc/orchestration-legacy-coordinator-race.test.ts
+++ b/src/main/runtime/rpc/orchestration-legacy-coordinator-race.test.ts
@@ -656,9 +656,21 @@ describe('legacy coordinator takeover races', () => {
     const detectionStarted = new Promise<void>((resolve) => {
       signalDetectionStarted = resolve
     })
+    let detectionCalls = 0
     vi.spyOn(harness.runtime, 'isTerminalRunningAgent').mockImplementation(
       () =>
-        new Promise<boolean>((resolve) => {
+        new Promise<boolean>((resolve, reject) => {
+          detectionCalls += 1
+          // Why reject instead of re-arming: a second call would overwrite resolveDetection and
+          // strand the first promise, hanging to a timeout instead of naming what changed.
+          if (detectionCalls > 1) {
+            reject(
+              new Error(
+                `isTerminalRunningAgent was called ${detectionCalls} times; this test drives exactly one detection.`
+              )
+            )
+            return
+          }
           resolveDetection = resolve
           signalDetectionStarted?.()
         })

From 401664298faf07f1e704d60f9ba689d7a962a2f8 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Tue, 1 Sep 2026 16:11:12 -0700
Subject: [PATCH 18/32] fix(preload): make a dropped bridge key a compile error

The split silently dropped jira.searchUsers and
runtimeEnvironments.retryControlConnection. Neither failed typecheck: the bridge
modules carried no satisfies annotation and the composed api object was
unannotated, so a missing key was only a runtime TypeError in the renderer.

Annotates each module against PreloadApi, the type window.api is already
declared as, so the contract supplies the shape rather than a parallel copy.
Deleting jira.searchUsers now fails with TS2741 naming the key.

Turning this on surfaced 106 places where a bridge locally annotated
Promise<unknown> or unknown[] over a contract that declares concrete types --
the bridge was erasing types the renderer relied on. Those annotations are gone.

Also exposes app.awaitBeforeUnloadCheckpoint, which was declared and called but
never actually on the bridge, so the lazy-chunk recovery reload optional-chained
to a no-op and navigated without joining the checkpoint. The missing key was
caught by the new annotation rather than by hand.
---
 src/preload/api/agent-status-bridge.ts        |  3 +-
 src/preload/api/agent-trust-bridge.ts         |  3 +-
 src/preload/api/ai-vault-bridge.ts            | 14 ++--
 src/preload/api/app-bridge.ts                 |  3 +-
 src/preload/api/automations-bridge.ts         |  4 +-
 src/preload/api/bitbucket-bridge.ts           |  5 +-
 ...bridge-guest-registration-and-downloads.ts |  3 +-
 ...er-bridge-page-interaction-and-sessions.ts | 45 ++++--------
 src/preload/api/browser-bridge.ts             |  3 +-
 src/preload/api/claude-accounts-bridge.ts     | 14 ++--
 src/preload/api/claude-usage-bridge.ts        |  6 +-
 src/preload/api/cli-bridge.ts                 |  3 +-
 src/preload/api/codex-accounts-bridge.ts      | 18 +++--
 src/preload/api/codex-config-sync-bridge.ts   |  3 +-
 src/preload/api/codex-usage-bridge.ts         |  6 +-
 .../api/computer-use-permissions-bridge.ts    |  9 +--
 src/preload/api/crash-reports-bridge.ts       |  3 +-
 src/preload/api/dashboard-bridge.ts           |  3 +-
 .../api/developer-permissions-bridge.ts       | 10 +--
 src/preload/api/diagnostics-bridge.ts         |  9 +--
 src/preload/api/doc-preview-bridge.ts         |  3 +-
 src/preload/api/e2e-bridge.ts                 |  3 +-
 src/preload/api/emulator-bridge.ts            |  3 +-
 src/preload/api/export-bridge.ts              |  3 +-
 src/preload/api/feedback-bridge.ts            |  3 +-
 src/preload/api/fs-bridge.ts                  |  3 +-
 .../api/gh-bridge-mutations-and-projects.ts   | 25 +++----
 .../gh-bridge-pull-requests-and-work-items.ts | 71 ++++++++++---------
 src/preload/api/gh-bridge.ts                  |  6 +-
 src/preload/api/git-bash-bridge.ts            |  3 +-
 src/preload/api/git-bridge.ts                 | 35 ++++-----
 src/preload/api/gl-bridge.ts                  |  3 +-
 src/preload/api/grok-accounts-bridge.ts       |  3 +-
 src/preload/api/hooks-bridge.ts               | 20 ++----
 src/preload/api/hosted-review-bridge.ts       | 12 ++--
 src/preload/api/jira-bridge.ts                | 66 ++++++-----------
 src/preload/api/keybindings-bridge.ts         |  3 +-
 src/preload/api/linear-bridge.ts              | 58 ++++++---------
 src/preload/api/macos-tcc-prompts-bridge.ts   | 11 +--
 src/preload/api/memory-bridge.ts              |  3 +-
 src/preload/api/minimax-credentials-bridge.ts |  3 +-
 src/preload/api/mobile-bridge.ts              |  3 +-
 src/preload/api/native-chat-bridge.ts         |  5 +-
 src/preload/api/notebook-bridge.ts            |  3 +-
 src/preload/api/notifications-bridge.ts       |  3 +-
 src/preload/api/onboarding-bridge.ts          |  3 +-
 src/preload/api/open-code-usage-bridge.ts     |  6 +-
 src/preload/api/pet-bridge.ts                 |  3 +-
 src/preload/api/plugins-bridge.ts             |  7 +-
 src/preload/api/preflight-bridge.ts           |  4 +-
 src/preload/api/pty-bridge-session-control.ts |  3 +-
 .../pty-bridge-stream-and-serialization.ts    |  3 +-
 src/preload/api/pty-bridge.ts                 |  6 +-
 src/preload/api/pwsh-bridge.ts                |  3 +-
 src/preload/api/rate-limits-bridge.ts         |  3 +-
 src/preload/api/runtime-bridge.ts             |  3 +-
 .../api/runtime-environments-bridge.ts        |  3 +-
 src/preload/api/settings-bridge.ts            | 16 ++---
 src/preload/api/shell-bridge.ts               |  3 +-
 src/preload/api/skills-bridge.ts              |  3 +-
 src/preload/api/speech-bridge.ts              |  3 +-
 src/preload/api/ssh-bridge.ts                 |  3 +-
 src/preload/api/star-nag-bridge.ts            |  3 +-
 src/preload/api/stats-bridge.ts               |  3 +-
 src/preload/api/terminal-preview-bridge.ts    |  3 +-
 ...ui-bridge-clipboard-and-window-controls.ts |  3 +-
 .../api/ui-bridge-state-and-menu-commands.ts  |  3 +-
 .../api/ui-bridge-tab-and-browser-commands.ts |  3 +-
 .../ui-bridge-terminal-and-session-tabs.ts    |  3 +-
 src/preload/api/wsl-bridge.ts                 |  3 +-
 .../app-restart-checkpoint-routing.test.ts    | 14 ++++
 src/preload/gitlab.ts                         | 52 ++++++--------
 src/preload/index.ts                          |  3 +-
 73 files changed, 350 insertions(+), 339 deletions(-)

diff --git a/src/preload/api/agent-status-bridge.ts b/src/preload/api/agent-status-bridge.ts
index 5bc0757c5ca..b5ac5c8b5b2 100644
--- a/src/preload/api/agent-status-bridge.ts
+++ b/src/preload/api/agent-status-bridge.ts
@@ -6,6 +6,7 @@ import type {
 } from '../../shared/agent-status-types'
 import type { AgentInterruptInferenceRequest } from '../../shared/agent-interrupt-intent'
 import type { AgentQuestionAnsweredInferenceRequest } from '../../shared/agent-question-answered-intent'
+import type { PreloadApi } from '../api-types'
 
 export const agentStatusApi = {
   /** Listen for agent status updates forwarded from native hook receivers. */
@@ -85,4 +86,4 @@ export const agentStatusApi = {
   }): void => {
     ipcRenderer.send('agentStatus:transferPaneAuthority', args)
   }
-}
+} satisfies PreloadApi['agentStatus']
diff --git a/src/preload/api/agent-trust-bridge.ts b/src/preload/api/agent-trust-bridge.ts
index f27146d9cd3..5aca3fd805c 100644
--- a/src/preload/api/agent-trust-bridge.ts
+++ b/src/preload/api/agent-trust-bridge.ts
@@ -1,4 +1,5 @@
 import { ipcRenderer } from 'electron'
+import type { PreloadApi } from '../api-types'
 
 export const agentTrustApi = {
   markTrusted: (args: {
@@ -6,4 +7,4 @@ export const agentTrustApi = {
     workspacePath: string
     connectionId?: string
   }): Promise<void> => ipcRenderer.invoke('agentTrust:markTrusted', args)
-}
+} satisfies PreloadApi['agentTrust']
diff --git a/src/preload/api/ai-vault-bridge.ts b/src/preload/api/ai-vault-bridge.ts
index ea9b2e1be14..917c9f02b63 100644
--- a/src/preload/api/ai-vault-bridge.ts
+++ b/src/preload/api/ai-vault-bridge.ts
@@ -10,19 +10,19 @@ import type {
 } from '../../shared/ai-vault-types'
 import type { AiVaultSessionTitlesArgs } from '../../shared/ai-vault-session-title'
 import type { AiVaultPrepareSessionResumeArgs } from '../../shared/ai-vault-resume-preparation'
+import type { PreloadApi } from '../api-types'
 
 export const aiVaultApi = {
-  listSessions: (args?: AiVaultListArgs): Promise<unknown> =>
-    ipcRenderer.invoke('aiVault:listSessions', args),
-  resolveSessionTitles: (args: AiVaultSessionTitlesArgs): Promise<unknown> =>
+  listSessions: (args?: AiVaultListArgs) => ipcRenderer.invoke('aiVault:listSessions', args),
+  resolveSessionTitles: (args: AiVaultSessionTitlesArgs) =>
     ipcRenderer.invoke('aiVault:resolveSessionTitles', args),
   cancelListSessions: (args: { requestToken: string }): Promise<void> =>
     ipcRenderer.invoke('aiVault:cancelListSessions', args),
-  prepareSessionResume: (args: AiVaultPrepareSessionResumeArgs): Promise<unknown> =>
+  prepareSessionResume: (args: AiVaultPrepareSessionResumeArgs) =>
     ipcRenderer.invoke('aiVault:prepareSessionResume', args),
-  listSubagentSessions: (args: AiVaultSubagentListArgs): Promise<unknown> =>
+  listSubagentSessions: (args: AiVaultSubagentListArgs) =>
     ipcRenderer.invoke('aiVault:listSubagentSessions', args),
-  getFirstUserPrompt: (args: AiVaultFirstUserPromptArgs): Promise<unknown> =>
+  getFirstUserPrompt: (args: AiVaultFirstUserPromptArgs) =>
     ipcRenderer.invoke('aiVault:getFirstUserPrompt', args),
   deleteSession: (args: AiVaultDeleteSessionArgs): Promise<AiVaultDeleteSessionResult> =>
     ipcRenderer.invoke('aiVault:deleteSession', args),
@@ -31,4 +31,4 @@ export const aiVaultApi = {
     ipcRenderer.on('aiVault:windowFocused', listener)
     return () => ipcRenderer.removeListener('aiVault:windowFocused', listener)
   }
-}
+} satisfies PreloadApi['aiVault']
diff --git a/src/preload/api/app-bridge.ts b/src/preload/api/app-bridge.ts
index 705d24e4bda..22d46cc40d2 100644
--- a/src/preload/api/app-bridge.ts
+++ b/src/preload/api/app-bridge.ts
@@ -40,6 +40,7 @@ export const appApi = {
       throw new Error('Failed to stage renderer state before unload.')
     }
   },
+  awaitBeforeUnloadCheckpoint: () => awaitBeforeUnloadCheckpoint(),
   awaitFirstWindowStartupServices: (): Promise<void> =>
     ipcRenderer.invoke('app:awaitFirstWindowStartupServices'),
   prepareTerminalStartupRestoration: (): Promise<void> =>
@@ -73,4 +74,4 @@ export const appApi = {
     ipcRenderer.invoke('app:pickFloatingWorkspaceDirectory'),
   writeTerminalRenderDesyncEvidence: (args: WriteTerminalRenderDesyncEvidenceArgs) =>
     ipcRenderer.invoke('terminal:writeRenderDesyncEvidence', args)
-}
+} satisfies PreloadApi['app']
diff --git a/src/preload/api/automations-bridge.ts b/src/preload/api/automations-bridge.ts
index 87bec12a8e9..43c3df528d8 100644
--- a/src/preload/api/automations-bridge.ts
+++ b/src/preload/api/automations-bridge.ts
@@ -1,5 +1,5 @@
 import { ipcRenderer } from 'electron'
-import type { ExternalAutomationManagerResult } from '../api-types'
+import type { ExternalAutomationManagerResult, PreloadApi } from '../api-types'
 import type {
   AutomationDispatchRequest,
   AutomationDispatchResult,
@@ -56,4 +56,4 @@ export const automationsApi = {
     ipcRenderer.on('automations:changed', listener)
     return () => ipcRenderer.removeListener('automations:changed', listener)
   }
-}
+} satisfies PreloadApi['automations']
diff --git a/src/preload/api/bitbucket-bridge.ts b/src/preload/api/bitbucket-bridge.ts
index cf51ce453df..dd683b1387b 100644
--- a/src/preload/api/bitbucket-bridge.ts
+++ b/src/preload/api/bitbucket-bridge.ts
@@ -1,4 +1,5 @@
 import { ipcRenderer } from 'electron'
+import type { PreloadApi } from '../api-types'
 
 export const bitbucketApi = {
   connect: (args: {
@@ -12,5 +13,5 @@ export const bitbucketApi = {
 
   disconnect: (): Promise<void> => ipcRenderer.invoke('bitbucket:disconnect'),
 
-  status: (): Promise<unknown> => ipcRenderer.invoke('bitbucket:status')
-}
+  status: () => ipcRenderer.invoke('bitbucket:status')
+} satisfies PreloadApi['bitbucket']
diff --git a/src/preload/api/browser-bridge-guest-registration-and-downloads.ts b/src/preload/api/browser-bridge-guest-registration-and-downloads.ts
index 3714a3bca7c..9d782971d96 100644
--- a/src/preload/api/browser-bridge-guest-registration-and-downloads.ts
+++ b/src/preload/api/browser-bridge-guest-registration-and-downloads.ts
@@ -6,6 +6,7 @@ import type {
 } from '../../shared/browser-webauthn-account'
 import { readBrowserClientHostIdArgument } from '../../shared/browser-client-host-id-argument'
 import { browserClientPageRendererRequests } from '../preload-runtime-support'
+import type { PreloadApi } from '../api-types'
 
 export const browserGuestRegistrationAndDownloadsApi = {
   onClientPageRendererRequest: browserClientPageRendererRequests.subscribe,
@@ -194,4 +195,4 @@ export const browserGuestRegistrationAndDownloadsApi = {
     ipcRenderer.on('browser:download-finished', listener)
     return () => ipcRenderer.removeListener('browser:download-finished', listener)
   }
-}
+} satisfies Partial<PreloadApi['browser']>
diff --git a/src/preload/api/browser-bridge-page-interaction-and-sessions.ts b/src/preload/api/browser-bridge-page-interaction-and-sessions.ts
index 0e959e0af4f..93d6001e61c 100644
--- a/src/preload/api/browser-bridge-page-interaction-and-sessions.ts
+++ b/src/preload/api/browser-bridge-page-interaction-and-sessions.ts
@@ -1,4 +1,5 @@
 import { ipcRenderer } from 'electron'
+import type { PreloadApi } from '../api-types'
 
 export const browserPageInteractionAndSessionsApi = {
   onContextMenuRequested: (
@@ -81,23 +82,17 @@ export const browserPageInteractionAndSessionsApi = {
   },
   cancelDownload: (args: { downloadId: string }): Promise<boolean> =>
     ipcRenderer.invoke('browser:cancelDownload', args),
-  setGrabMode: (args: {
-    browserPageId: string
-    enabled: boolean
-  }): Promise<{ ok: true } | { ok: false; reason: string }> =>
+  setGrabMode: (args: { browserPageId: string; enabled: boolean }) =>
     ipcRenderer.invoke('browser:setGrabMode', args),
-  awaitGrabSelection: (args: { browserPageId: string; opId: string }): Promise<unknown> =>
+  awaitGrabSelection: (args: { browserPageId: string; opId: string }) =>
     ipcRenderer.invoke('browser:awaitGrabSelection', args),
   cancelGrab: (args: { browserPageId: string }): Promise<boolean> =>
     ipcRenderer.invoke('browser:cancelGrab', args),
   captureSelectionScreenshot: (args: {
     browserPageId: string
     rect: { x: number; y: number; width: number; height: number }
-  }): Promise<{ ok: true; screenshot: unknown } | { ok: false; reason: string }> =>
-    ipcRenderer.invoke('browser:captureSelectionScreenshot', args),
-  extractHoverPayload: (args: {
-    browserPageId: string
-  }): Promise<{ ok: true; payload: unknown } | { ok: false; reason: string }> =>
+  }) => ipcRenderer.invoke('browser:captureSelectionScreenshot', args),
+  extractHoverPayload: (args: { browserPageId: string }) =>
     ipcRenderer.invoke('browser:extractHoverPayload', args),
   onGrabModeToggle: (callback: (browserPageId: string) => void): (() => void) => {
     const listener = (_event: Electron.IpcRendererEvent, browserPageId: string) =>
@@ -115,7 +110,7 @@ export const browserPageInteractionAndSessionsApi = {
     ipcRenderer.on('browser:grabActionShortcut', listener)
     return () => ipcRenderer.removeListener('browser:grabActionShortcut', listener)
   },
-  sessionListProfiles: (): Promise<unknown[]> => ipcRenderer.invoke('browser:session:listProfiles'),
+  sessionListProfiles: () => ipcRenderer.invoke('browser:session:listProfiles'),
   prepareSshWorkspacePartition: (args: {
     targetId: string
     browserProfileId?: string
@@ -126,40 +121,28 @@ export const browserPageInteractionAndSessionsApi = {
     scope: 'default' | 'isolated' | 'imported'
     label: string
     userAgentMode?: 'clean' | 'native'
-  }): Promise<unknown> => ipcRenderer.invoke('browser:session:createProfile', args),
+  }) => ipcRenderer.invoke('browser:session:createProfile', args),
   sessionDeleteProfile: (args: { profileId: string }): Promise<boolean> =>
     ipcRenderer.invoke('browser:session:deleteProfile', args),
-  sessionImportCookies: (args: {
-    profileId: string
-  }): Promise<{ ok: true; profileId: string; summary: unknown } | { ok: false; reason: string }> =>
+  sessionImportCookies: (args: { profileId: string }) =>
     ipcRenderer.invoke('browser:session:importCookies', args),
   sessionResolvePartition: (args: { profileId: string | null }): Promise<string | null> =>
     ipcRenderer.invoke('browser:session:resolvePartition', args),
-  sessionDetectBrowsers: (): Promise<unknown[]> =>
-    ipcRenderer.invoke('browser:session:detectBrowsers'),
-  sessionDetectBrowsersForClientHost: (args: {
-    environmentId: string
-  }): Promise<unknown[] | null> =>
+  sessionDetectBrowsers: () => ipcRenderer.invoke('browser:session:detectBrowsers'),
+  sessionDetectBrowsersForClientHost: (args: { environmentId: string }) =>
     ipcRenderer.invoke('browser:session:detectBrowsersForClientHost', args),
-  sessionImportFromBrowser: (args: {
-    profileId: string
-    browserFamily: string
-  }): Promise<{ ok: true; profileId: string; summary: unknown } | { ok: false; reason: string }> =>
+  sessionImportFromBrowser: (args: { profileId: string; browserFamily: string }) =>
     ipcRenderer.invoke('browser:session:importFromBrowser', args),
   sessionImportFromBrowserForClientHost: (args: {
     environmentId: string
     profileId: string
     browserFamily: string
     browserProfile?: string
-  }): Promise<
-    { ok: true; profileId: string; summary: unknown } | { ok: false; reason: string } | null
-  > => ipcRenderer.invoke('browser:session:importFromBrowserForClientHost', args),
-  sessionClientRouteImportSources: (args: {
-    environmentId: string
-  }): Promise<Record<string, unknown>> =>
+  }) => ipcRenderer.invoke('browser:session:importFromBrowserForClientHost', args),
+  sessionClientRouteImportSources: (args: { environmentId: string }) =>
     ipcRenderer.invoke('browser:session:clientRouteImportSources', args),
   sessionClearDefaultCookies: (): Promise<boolean> =>
     ipcRenderer.invoke('browser:session:clearDefaultCookies'),
   notifyActiveTabChanged: (args: { browserPageId: string }): Promise<boolean> =>
     ipcRenderer.invoke('browser:activeTabChanged', args)
-}
+} satisfies Partial<PreloadApi['browser']>
diff --git a/src/preload/api/browser-bridge.ts b/src/preload/api/browser-bridge.ts
index dca222c5843..d29b7365dc2 100644
--- a/src/preload/api/browser-bridge.ts
+++ b/src/preload/api/browser-bridge.ts
@@ -1,7 +1,8 @@
 import { browserGuestRegistrationAndDownloadsApi } from './browser-bridge-guest-registration-and-downloads'
 import { browserPageInteractionAndSessionsApi } from './browser-bridge-page-interaction-and-sessions'
+import type { PreloadApi } from '../api-types'
 
 export const browserApi = {
   ...browserGuestRegistrationAndDownloadsApi,
   ...browserPageInteractionAndSessionsApi
-}
+} satisfies PreloadApi['browser']
diff --git a/src/preload/api/claude-accounts-bridge.ts b/src/preload/api/claude-accounts-bridge.ts
index 8200c17791d..69586525962 100644
--- a/src/preload/api/claude-accounts-bridge.ts
+++ b/src/preload/api/claude-accounts-bridge.ts
@@ -1,18 +1,18 @@
 import { ipcRenderer } from 'electron'
+import type { PreloadApi } from '../api-types'
 
 export const claudeAccountsApi = {
-  list: (): Promise<unknown> => ipcRenderer.invoke('claudeAccounts:list'),
-  add: (args?: { runtime?: 'host' | 'wsl'; wslDistro?: string | null }): Promise<unknown> =>
+  list: () => ipcRenderer.invoke('claudeAccounts:list'),
+  add: (args?: { runtime?: 'host' | 'wsl'; wslDistro?: string | null }) =>
     ipcRenderer.invoke('claudeAccounts:add', args),
   cancelPendingLogin: (): Promise<boolean> =>
     ipcRenderer.invoke('claudeAccounts:cancelPendingLogin'),
-  reauthenticate: (args: { accountId: string }): Promise<unknown> =>
+  reauthenticate: (args: { accountId: string }) =>
     ipcRenderer.invoke('claudeAccounts:reauthenticate', args),
-  remove: (args: { accountId: string }): Promise<unknown> =>
-    ipcRenderer.invoke('claudeAccounts:remove', args),
+  remove: (args: { accountId: string }) => ipcRenderer.invoke('claudeAccounts:remove', args),
   select: (args: {
     accountId: string | null
     runtime?: 'host' | 'wsl'
     wslDistro?: string | null
-  }): Promise<unknown> => ipcRenderer.invoke('claudeAccounts:select', args)
-}
+  }) => ipcRenderer.invoke('claudeAccounts:select', args)
+} satisfies PreloadApi['claudeAccounts']
diff --git a/src/preload/api/claude-usage-bridge.ts b/src/preload/api/claude-usage-bridge.ts
index 0c81e35e3e8..1b98202d88c 100644
--- a/src/preload/api/claude-usage-bridge.ts
+++ b/src/preload/api/claude-usage-bridge.ts
@@ -1,4 +1,8 @@
 import { ipcRenderer } from 'electron'
 import { createUsageProviderApi } from '../usage-provider-api'
+import type { PreloadApi } from '../api-types'
 
-export const claudeUsageApi = createUsageProviderApi(ipcRenderer, 'claudeUsage')
+export const claudeUsageApi = createUsageProviderApi(
+  ipcRenderer,
+  'claudeUsage'
+) satisfies PreloadApi['claudeUsage']
diff --git a/src/preload/api/cli-bridge.ts b/src/preload/api/cli-bridge.ts
index 8f811cbdd40..76b574a2f44 100644
--- a/src/preload/api/cli-bridge.ts
+++ b/src/preload/api/cli-bridge.ts
@@ -1,5 +1,6 @@
 import { ipcRenderer } from 'electron'
 import type { CliInstallStatus } from '../../shared/cli-install-types'
+import type { PreloadApi } from '../api-types'
 
 export const cliApi = {
   getInstallStatus: (): Promise<CliInstallStatus> => ipcRenderer.invoke('cli:getInstallStatus'),
@@ -11,4 +12,4 @@ export const cliApi = {
     ipcRenderer.invoke('cli:installWsl', args),
   removeWsl: (args?: { distro?: string | null }): Promise<CliInstallStatus> =>
     ipcRenderer.invoke('cli:removeWsl', args)
-}
+} satisfies PreloadApi['cli']
diff --git a/src/preload/api/codex-accounts-bridge.ts b/src/preload/api/codex-accounts-bridge.ts
index ecd32e4b923..d085de45855 100644
--- a/src/preload/api/codex-accounts-bridge.ts
+++ b/src/preload/api/codex-accounts-bridge.ts
@@ -1,20 +1,18 @@
 import { ipcRenderer } from 'electron'
+import type { PreloadApi } from '../api-types'
 
 export const codexAccountsApi = {
-  list: (): Promise<unknown> => ipcRenderer.invoke('codexAccounts:list'),
-  add: (args?: { runtime?: 'host' | 'wsl'; wslDistro?: string | null }): Promise<unknown> =>
+  list: () => ipcRenderer.invoke('codexAccounts:list'),
+  add: (args?: { runtime?: 'host' | 'wsl'; wslDistro?: string | null }) =>
     ipcRenderer.invoke('codexAccounts:add', args),
-  reauthenticate: (args: {
-    accountId: string
-    activateIfSelectionWasEmpty?: boolean
-  }): Promise<unknown> => ipcRenderer.invoke('codexAccounts:reauthenticate', args),
-  remove: (args: { accountId: string }): Promise<unknown> =>
-    ipcRenderer.invoke('codexAccounts:remove', args),
+  reauthenticate: (args: { accountId: string; activateIfSelectionWasEmpty?: boolean }) =>
+    ipcRenderer.invoke('codexAccounts:reauthenticate', args),
+  remove: (args: { accountId: string }) => ipcRenderer.invoke('codexAccounts:remove', args),
   select: (args: {
     accountId: string | null
     runtime?: 'host' | 'wsl'
     wslDistro?: string | null
-  }): Promise<unknown> => ipcRenderer.invoke('codexAccounts:select', args),
+  }) => ipcRenderer.invoke('codexAccounts:select', args),
   listStalePanes: (args: {
     ptyIds: string[]
   }): Promise<
@@ -29,4 +27,4 @@ export const codexAccountsApi = {
     ipcRenderer.invoke('codexAccounts:listRecordedPaneLanes', args),
   forgetStalePanes: (args: { ptyIds: string[] }): Promise<void> =>
     ipcRenderer.invoke('codexAccounts:forgetStalePanes', args)
-}
+} satisfies PreloadApi['codexAccounts']
diff --git a/src/preload/api/codex-config-sync-bridge.ts b/src/preload/api/codex-config-sync-bridge.ts
index e6c8903a698..82eedfaf0ec 100644
--- a/src/preload/api/codex-config-sync-bridge.ts
+++ b/src/preload/api/codex-config-sync-bridge.ts
@@ -1,6 +1,7 @@
 import { ipcRenderer } from 'electron'
 import type { CodexConfigSyncStatus } from '../../shared/codex-config-sync-types'
+import type { PreloadApi } from '../api-types'
 
 export const codexConfigSyncApi = {
   status: (): Promise<CodexConfigSyncStatus> => ipcRenderer.invoke('codexConfigSync:status')
-}
+} satisfies PreloadApi['codexConfigSync']
diff --git a/src/preload/api/codex-usage-bridge.ts b/src/preload/api/codex-usage-bridge.ts
index 9dba4b72f82..2575f2bb0e9 100644
--- a/src/preload/api/codex-usage-bridge.ts
+++ b/src/preload/api/codex-usage-bridge.ts
@@ -1,4 +1,8 @@
 import { ipcRenderer } from 'electron'
 import { createUsageProviderApi } from '../usage-provider-api'
+import type { PreloadApi } from '../api-types'
 
-export const codexUsageApi = createUsageProviderApi(ipcRenderer, 'codexUsage')
+export const codexUsageApi = createUsageProviderApi(
+  ipcRenderer,
+  'codexUsage'
+) satisfies PreloadApi['codexUsage']
diff --git a/src/preload/api/computer-use-permissions-bridge.ts b/src/preload/api/computer-use-permissions-bridge.ts
index be441a8682e..bd36efbdcc3 100644
--- a/src/preload/api/computer-use-permissions-bridge.ts
+++ b/src/preload/api/computer-use-permissions-bridge.ts
@@ -1,8 +1,9 @@
 import { ipcRenderer } from 'electron'
+import type { PreloadApi } from '../api-types'
 
 export const computerUsePermissionsApi = {
-  getStatus: (): Promise<unknown> => ipcRenderer.invoke('computerUsePermissions:getStatus'),
-  openSetup: (args?: { id?: string }): Promise<unknown> =>
+  getStatus: () => ipcRenderer.invoke('computerUsePermissions:getStatus'),
+  openSetup: (args?: { id?: string }) =>
     ipcRenderer.invoke('computerUsePermissions:openSetup', args),
-  reset: (): Promise<unknown> => ipcRenderer.invoke('computerUsePermissions:reset')
-}
+  reset: () => ipcRenderer.invoke('computerUsePermissions:reset')
+} satisfies PreloadApi['computerUsePermissions']
diff --git a/src/preload/api/crash-reports-bridge.ts b/src/preload/api/crash-reports-bridge.ts
index 19d7044601d..a77ad412eb7 100644
--- a/src/preload/api/crash-reports-bridge.ts
+++ b/src/preload/api/crash-reports-bridge.ts
@@ -11,6 +11,7 @@ import type { RendererHeapStatistics } from '../../shared/renderer-heap-statisti
 import type { RendererProcessMemory } from '../../shared/renderer-process-memory'
 import { readRendererHeapStatistics } from '../renderer-heap-statistics-reader'
 import { readRendererProcessMemory } from '../renderer-process-memory-reader'
+import type { PreloadApi } from '../api-types'
 
 export const crashReportsApi = {
   getLatestPending: () => ipcRenderer.invoke('crashReports:getLatestPending'),
@@ -28,4 +29,4 @@ export const crashReportsApi = {
     ipcRenderer.invoke('crashReports:copyLatestDiagnostics', args),
   readHeapStatistics: (): RendererHeapStatistics | null => readRendererHeapStatistics(),
   readProcessMemory: (): Promise<RendererProcessMemory | null> => readRendererProcessMemory()
-}
+} satisfies PreloadApi['crashReports']
diff --git a/src/preload/api/dashboard-bridge.ts b/src/preload/api/dashboard-bridge.ts
index 17241630857..e6862504da9 100644
--- a/src/preload/api/dashboard-bridge.ts
+++ b/src/preload/api/dashboard-bridge.ts
@@ -5,6 +5,7 @@ import type {
   DashboardSnapshot,
   DashboardSpawnAgentArgs
 } from '../../shared/dashboard-snapshot'
+import type { PreloadApi } from '../api-types'
 
 export const dashboardApi = {
   // Open the pop-out dashboard window, or focus it if already open.
@@ -71,4 +72,4 @@ export const dashboardApi = {
     ipcRenderer.invoke('dashboardPopout:spawnAgent', args),
   sleepWorkspace: (args: DashboardSleepWorkspaceArgs): Promise<void> =>
     ipcRenderer.invoke('dashboardPopout:sleepWorkspace', args)
-}
+} satisfies PreloadApi['dashboard']
diff --git a/src/preload/api/developer-permissions-bridge.ts b/src/preload/api/developer-permissions-bridge.ts
index 1aaa51deed3..94158cd7818 100644
--- a/src/preload/api/developer-permissions-bridge.ts
+++ b/src/preload/api/developer-permissions-bridge.ts
@@ -1,11 +1,11 @@
 import { ipcRenderer } from 'electron'
+import type { PreloadApi } from '../api-types'
 
 export const developerPermissionsApi = {
-  getStatus: (): Promise<unknown> => ipcRenderer.invoke('developerPermissions:getStatus'),
-  request: (args: { id: string }): Promise<unknown> =>
-    ipcRenderer.invoke('developerPermissions:request', args),
+  getStatus: () => ipcRenderer.invoke('developerPermissions:getStatus'),
+  request: (args: { id: string }) => ipcRenderer.invoke('developerPermissions:request', args),
   openSettings: (args: { id: string }): Promise<void> =>
     ipcRenderer.invoke('developerPermissions:openSettings', args),
-  testLocalNetworkConnection: (args: { host: string; port: number }): Promise<unknown> =>
+  testLocalNetworkConnection: (args: { host: string; port: number }) =>
     ipcRenderer.invoke('developerPermissions:testLocalNetworkConnection', args)
-}
+} satisfies PreloadApi['developerPermissions']
diff --git a/src/preload/api/diagnostics-bridge.ts b/src/preload/api/diagnostics-bridge.ts
index 6d274f9b08a..bff79fe5817 100644
--- a/src/preload/api/diagnostics-bridge.ts
+++ b/src/preload/api/diagnostics-bridge.ts
@@ -1,15 +1,16 @@
 import { ipcRenderer } from 'electron'
+import type { PreloadApi } from '../api-types'
 
 export const diagnosticsApi = {
-  getStatus: (): Promise<unknown> => ipcRenderer.invoke('diagnostics:getStatus'),
-  collectBundle: (lookbackMinutes?: number): Promise<unknown> =>
+  getStatus: () => ipcRenderer.invoke('diagnostics:getStatus'),
+  collectBundle: (lookbackMinutes?: number) =>
     ipcRenderer.invoke('diagnostics:collectBundle', lookbackMinutes),
   openBundlePreview: (bundleSubmissionId: string): Promise<void> =>
     ipcRenderer.invoke('diagnostics:openBundlePreview', bundleSubmissionId),
   discardBundlePreview: (bundleSubmissionId: string): Promise<void> =>
     ipcRenderer.invoke('diagnostics:discardBundlePreview', bundleSubmissionId),
-  uploadBundle: (bundleSubmissionId: string): Promise<unknown> =>
+  uploadBundle: (bundleSubmissionId: string) =>
     ipcRenderer.invoke('diagnostics:uploadBundle', bundleSubmissionId),
   deleteBundle: (ticketId: string): Promise<void> =>
     ipcRenderer.invoke('diagnostics:deleteBundle', ticketId)
-}
+} satisfies PreloadApi['diagnostics']
diff --git a/src/preload/api/doc-preview-bridge.ts b/src/preload/api/doc-preview-bridge.ts
index 68a099d5ed2..97fbb8da975 100644
--- a/src/preload/api/doc-preview-bridge.ts
+++ b/src/preload/api/doc-preview-bridge.ts
@@ -8,6 +8,7 @@ import {
   type DocPreviewFailure
 } from '../../shared/doc-preview-scheme'
 import type { DocPreviewGrantRequest } from '../api/doc-preview-api'
+import type { PreloadApi } from '../api-types'
 
 export const docPreviewApi = {
   mintGrant: (request: DocPreviewGrantRequest): Promise<{ grantId: string; url: string }> =>
@@ -28,4 +29,4 @@ export const docPreviewApi = {
     ipcRenderer.on(DOC_PREVIEW_LOAD_FAILURE_CHANNEL, listener)
     return () => ipcRenderer.removeListener(DOC_PREVIEW_LOAD_FAILURE_CHANNEL, listener)
   }
-}
+} satisfies PreloadApi['docPreview']
diff --git a/src/preload/api/e2e-bridge.ts b/src/preload/api/e2e-bridge.ts
index 2876b72a265..900b17a9fcf 100644
--- a/src/preload/api/e2e-bridge.ts
+++ b/src/preload/api/e2e-bridge.ts
@@ -1,5 +1,6 @@
 import { preloadE2EConfig } from '../e2e-config'
+import type { PreloadApi } from '../api-types'
 
 export const e2eApi = {
   getConfig: () => preloadE2EConfig
-}
+} satisfies PreloadApi['e2e']
diff --git a/src/preload/api/emulator-bridge.ts b/src/preload/api/emulator-bridge.ts
index f13e99fc52a..8ab56471a42 100644
--- a/src/preload/api/emulator-bridge.ts
+++ b/src/preload/api/emulator-bridge.ts
@@ -1,4 +1,5 @@
 import { ipcRenderer } from 'electron'
+import type { PreloadApi } from '../api-types'
 
 export const emulatorApi = {
   startFrameStream: (args: {
@@ -95,4 +96,4 @@ export const emulatorApi = {
     ipcRenderer.on('ui:emulatorAutoAttach', listener)
     return () => ipcRenderer.removeListener('ui:emulatorAutoAttach', listener)
   }
-}
+} satisfies PreloadApi['emulator']
diff --git a/src/preload/api/export-bridge.ts b/src/preload/api/export-bridge.ts
index 637d4bea2ef..67ffbfae109 100644
--- a/src/preload/api/export-bridge.ts
+++ b/src/preload/api/export-bridge.ts
@@ -1,4 +1,5 @@
 import { ipcRenderer } from 'electron'
+import type { PreloadApi } from '../api-types'
 
 export const exportApi = {
   htmlToPdf: (args: {
@@ -7,4 +8,4 @@ export const exportApi = {
   }): Promise<
     { success: true; filePath: string } | { success: false; cancelled?: boolean; error?: string }
   > => ipcRenderer.invoke('export:html-to-pdf', args)
-}
+} satisfies PreloadApi['export']
diff --git a/src/preload/api/feedback-bridge.ts b/src/preload/api/feedback-bridge.ts
index 55b3b5fcaa7..4241c5cacf9 100644
--- a/src/preload/api/feedback-bridge.ts
+++ b/src/preload/api/feedback-bridge.ts
@@ -1,4 +1,5 @@
 import { ipcRenderer } from 'electron'
+import type { PreloadApi } from '../api-types'
 
 export const feedbackApi = {
   submit: (args: {
@@ -10,4 +11,4 @@ export const feedbackApi = {
   }): Promise<
     { ok: true; imagesDelivered?: boolean } | { ok: false; status: number | null; error: string }
   > => ipcRenderer.invoke('feedback:submit', args)
-}
+} satisfies PreloadApi['feedback']
diff --git a/src/preload/api/fs-bridge.ts b/src/preload/api/fs-bridge.ts
index 538480ce2f5..c67e9abd9e3 100644
--- a/src/preload/api/fs-bridge.ts
+++ b/src/preload/api/fs-bridge.ts
@@ -8,6 +8,7 @@ import type {
   LocalLogTailReadResult,
   LocalLogTailWatchArgs
 } from '../../shared/local-log-tail-types'
+import type { PreloadApi } from '../api-types'
 
 export const fsApi = {
   readDir: (args: {
@@ -216,4 +217,4 @@ export const fsApi = {
     ipcRenderer.on('fs:changed', listener)
     return () => ipcRenderer.removeListener('fs:changed', listener)
   }
-}
+} satisfies PreloadApi['fs']
diff --git a/src/preload/api/gh-bridge-mutations-and-projects.ts b/src/preload/api/gh-bridge-mutations-and-projects.ts
index 3103cb432ec..80b746bfb79 100644
--- a/src/preload/api/gh-bridge-mutations-and-projects.ts
+++ b/src/preload/api/gh-bridge-mutations-and-projects.ts
@@ -35,11 +35,12 @@ import type {
   UpdateProjectItemFieldArgs
 } from '../../shared/github/project-request-types'
 import type { AppStarSource } from '../../shared/gh-star-source'
+import type { PreloadApi } from '../api-types'
 
 export const ghMutationsAndProjectsApi = {
   setPRAutoMerge: (args: {
     repoPath: string
-    repoId?: string
+    repoId?: string | null
     sourceContext?: TaskSourceContext | null
     prNumber: number
     enabled: boolean
@@ -49,7 +50,7 @@ export const ghMutationsAndProjectsApi = {
     ipcRenderer.invoke('gh:setPRAutoMerge', args),
   updatePRState: (args: {
     repoPath: string
-    repoId?: string
+    repoId?: string | null
     sourceContext?: TaskSourceContext | null
     prNumber: number
     updates: { state: 'open' | 'closed' }
@@ -58,7 +59,7 @@ export const ghMutationsAndProjectsApi = {
     ipcRenderer.invoke('gh:updatePRState', args),
   markPRReadyForReview: (args: {
     repoPath: string
-    repoId?: string
+    repoId?: string | null
     sourceContext?: TaskSourceContext | null
     prNumber: number
     prRepo?: GitHubOwnerRepo | null
@@ -66,7 +67,7 @@ export const ghMutationsAndProjectsApi = {
     ipcRenderer.invoke('gh:markPRReadyForReview', args),
   requestPRReviewers: (args: {
     repoPath: string
-    repoId?: string
+    repoId?: string | null
     sourceContext?: TaskSourceContext | null
     prNumber: number
     reviewers: string[]
@@ -75,7 +76,7 @@ export const ghMutationsAndProjectsApi = {
     ipcRenderer.invoke('gh:requestPRReviewers', args),
   removePRReviewers: (args: {
     repoPath: string
-    repoId?: string
+    repoId?: string | null
     sourceContext?: TaskSourceContext | null
     prNumber: number
     reviewers: string[]
@@ -84,7 +85,7 @@ export const ghMutationsAndProjectsApi = {
     ipcRenderer.invoke('gh:removePRReviewers', args),
   updateIssue: (args: {
     repoPath: string
-    repoId?: string
+    repoId?: string | null
     sourceContext?: TaskSourceContext | null
     number: number
     updates: unknown
@@ -92,7 +93,7 @@ export const ghMutationsAndProjectsApi = {
     ipcRenderer.invoke('gh:updateIssue', args),
   addIssueComment: (args: {
     repoPath: string
-    repoId?: string
+    repoId?: string | null
     sourceContext?: TaskSourceContext | null
     number: number
     body: string
@@ -101,7 +102,7 @@ export const ghMutationsAndProjectsApi = {
   }): Promise<GitHubCommentResult> => ipcRenderer.invoke('gh:addIssueComment', args),
   addPRReviewCommentReply: (args: {
     repoPath: string
-    repoId?: string
+    repoId?: string | null
     sourceContext?: TaskSourceContext | null
     prNumber: number
     commentId: number
@@ -113,7 +114,7 @@ export const ghMutationsAndProjectsApi = {
   }): Promise<GitHubCommentResult> => ipcRenderer.invoke('gh:addPRReviewCommentReply', args),
   addPRReviewComment: (args: {
     repoPath: string
-    repoId?: string
+    repoId?: string | null
     sourceContext?: TaskSourceContext | null
     prNumber: number
     prRepo?: GitHubOwnerRepo | null
@@ -125,12 +126,12 @@ export const ghMutationsAndProjectsApi = {
   }): Promise<GitHubCommentResult> => ipcRenderer.invoke('gh:addPRReviewComment', args),
   listLabels: (args: {
     repoPath: string
-    repoId?: string
+    repoId?: string | null
     sourceContext?: TaskSourceContext | null
   }): Promise<string[]> => ipcRenderer.invoke('gh:listLabels', args),
   listAssignableUsers: (args: {
     repoPath: string
-    repoId?: string
+    repoId?: string | null
     sourceContext?: TaskSourceContext | null
   }): Promise<GitHubAssignableUser[]> => ipcRenderer.invoke('gh:listAssignableUsers', args),
   onWorkItemMutated: (
@@ -199,4 +200,4 @@ export const ghMutationsAndProjectsApi = {
     ipcRenderer.invoke('gh:listIssueTypesBySlug', args),
   updateIssueTypeBySlug: (args: UpdateIssueTypeBySlugArgs): Promise<GitHubProjectMutationResult> =>
     ipcRenderer.invoke('gh:updateIssueTypeBySlug', args)
-}
+} satisfies Partial<PreloadApi['gh']>
diff --git a/src/preload/api/gh-bridge-pull-requests-and-work-items.ts b/src/preload/api/gh-bridge-pull-requests-and-work-items.ts
index a4f3e1d45ef..3e4a5f6ce2a 100644
--- a/src/preload/api/gh-bridge-pull-requests-and-work-items.ts
+++ b/src/preload/api/gh-bridge-pull-requests-and-work-items.ts
@@ -9,33 +9,34 @@ import type { GitHubOwnerRepo } from '../../shared/github/pull-request-types'
 import type { GitHubWorkItem, ListWorkItemsResult } from '../../shared/github/work-item-types'
 import type { GitHubCreateIssueResult } from '../../shared/issue-mutation-types'
 import type { TaskSourceContext } from '../../shared/task-source-context'
+import type { PreloadApi } from '../api-types'
 
 export const ghPullRequestsAndWorkItemsApi = {
-  viewer: (): Promise<unknown> => ipcRenderer.invoke('gh:viewer'),
-  repoSlug: (args: { repoPath: string; repoId?: string }): Promise<unknown> =>
+  viewer: () => ipcRenderer.invoke('gh:viewer'),
+  repoSlug: (args: { repoPath: string; repoId?: string }) =>
     ipcRenderer.invoke('gh:repoSlug', args),
-  repoUpstream: (args: { repoPath: string; repoId?: string }): Promise<unknown> =>
+  repoUpstream: (args: { repoPath: string; repoId?: string }) =>
     ipcRenderer.invoke('gh:repoUpstream', args),
   prForBranch: (args: {
     repoPath: string
-    repoId?: string
+    repoId?: string | null
     branch: string
     linkedPRNumber?: number | null
     fallbackPRNumber?: number | null
     acceptMergedFallbackPR?: boolean
     currentHeadOid?: string | null
-  }): Promise<unknown> => ipcRenderer.invoke('gh:prForBranch', args),
-  refreshPRNow: (args: { candidate: GitHubPRRefreshCandidate }): Promise<unknown> =>
+  }) => ipcRenderer.invoke('gh:prForBranch', args),
+  refreshPRNow: (args: { candidate: GitHubPRRefreshCandidate }) =>
     ipcRenderer.invoke('gh:refreshPRNow', args),
   enqueuePRRefresh: (args: {
     candidate: GitHubPRRefreshCandidate
     reason: GitHubPRRefreshReason
     priority?: number
-  }): Promise<unknown> => ipcRenderer.invoke('gh:enqueuePRRefresh', args),
+  }) => ipcRenderer.invoke('gh:enqueuePRRefresh', args),
   reportVisiblePRRefreshCandidates: (args: {
     candidates: GitHubPRRefreshCandidate[]
     generation: number
-  }): Promise<unknown> => ipcRenderer.invoke('gh:reportVisiblePRRefreshCandidates', args),
+  }) => ipcRenderer.invoke('gh:reportVisiblePRRefreshCandidates', args),
   onPRRefreshEvent: (callback: (event: GitHubPRRefreshEvent) => void): (() => void) => {
     const listener = (_event: Electron.IpcRendererEvent, event: GitHubPRRefreshEvent): void =>
       callback(event)
@@ -44,42 +45,42 @@ export const ghPullRequestsAndWorkItemsApi = {
   },
   issue: (args: {
     repoPath: string
-    repoId?: string
+    repoId?: string | null
     sourceContext?: TaskSourceContext | null
     number: number
-  }): Promise<unknown> => ipcRenderer.invoke('gh:issue', args),
+  }) => ipcRenderer.invoke('gh:issue', args),
   workItem: (args: {
     repoPath: string
-    repoId?: string
+    repoId?: string | null
     sourceContext?: TaskSourceContext | null
     number: number
     type?: 'issue' | 'pr'
-  }): Promise<unknown> => ipcRenderer.invoke('gh:workItem', args),
+  }) => ipcRenderer.invoke('gh:workItem', args),
   workItemByOwnerRepo: (args: {
     repoPath: string
-    repoId?: string
+    repoId?: string | null
     owner: string
     repo: string
     host?: string
     number: number
     type: 'issue' | 'pr'
-  }): Promise<unknown> => ipcRenderer.invoke('gh:workItemByOwnerRepo', args),
+  }) => ipcRenderer.invoke('gh:workItemByOwnerRepo', args),
   workItemDetails: (args: {
     repoPath: string
-    repoId?: string
+    repoId?: string | null
     sourceContext?: TaskSourceContext | null
     number: number
     type?: 'issue' | 'pr'
-  }): Promise<unknown> => ipcRenderer.invoke('gh:workItemDetails', args),
+  }) => ipcRenderer.invoke('gh:workItemDetails', args),
   notifyWorkItemMutated: (args: {
     repoPath: string
-    repoId?: string
+    repoId?: string | null
     type: 'issue' | 'pr'
     number: number
   }): Promise<boolean> => ipcRenderer.invoke('gh:notifyWorkItemMutated', args),
   prFileContents: (args: {
     repoPath: string
-    repoId?: string
+    repoId?: string | null
     sourceContext?: TaskSourceContext | null
     prNumber: number
     prRepo?: GitHubOwnerRepo | null
@@ -88,12 +89,12 @@ export const ghPullRequestsAndWorkItemsApi = {
     status: string
     headSha: string
     baseSha: string
-  }): Promise<unknown> => ipcRenderer.invoke('gh:prFileContents', args),
-  listIssues: (args: { repoPath: string; repoId?: string; limit?: number }): Promise<unknown[]> =>
+  }) => ipcRenderer.invoke('gh:prFileContents', args),
+  listIssues: (args: { repoPath: string; repoId?: string; limit?: number }) =>
     ipcRenderer.invoke('gh:listIssues', args),
   createIssue: (args: {
     repoPath: string
-    repoId?: string
+    repoId?: string | null
     sourceContext?: TaskSourceContext | null
     title: string
     body: string
@@ -104,7 +105,7 @@ export const ghPullRequestsAndWorkItemsApi = {
     ipcRenderer.invoke('gh:countWorkItems', args),
   listWorkItems: (args: {
     repoPath: string
-    repoId?: string
+    repoId?: string | null
     limit?: number
     query?: string
     page?: number
@@ -113,26 +114,26 @@ export const ghPullRequestsAndWorkItemsApi = {
     ipcRenderer.invoke('gh:listWorkItems', args),
   prChecks: (args: {
     repoPath: string
-    repoId?: string
+    repoId?: string | null
     sourceContext?: TaskSourceContext | null
     prNumber: number
     headSha?: string
     prRepo?: GitHubOwnerRepo | null
     noCache?: boolean
-  }): Promise<unknown[]> => ipcRenderer.invoke('gh:prChecks', args),
+  }) => ipcRenderer.invoke('gh:prChecks', args),
   prCheckDetails: (args: {
     repoPath: string
-    repoId?: string
+    repoId?: string | null
     sourceContext?: TaskSourceContext | null
     checkRunId?: number
     workflowRunId?: number
     checkName?: string
     url?: string | null
     prRepo?: GitHubOwnerRepo | null
-  }): Promise<unknown> => ipcRenderer.invoke('gh:prCheckDetails', args),
+  }) => ipcRenderer.invoke('gh:prCheckDetails', args),
   rerunPRChecks: (args: {
     repoPath: string
-    repoId?: string
+    repoId?: string | null
     sourceContext?: TaskSourceContext | null
     prNumber: number
     headSha?: string
@@ -142,15 +143,15 @@ export const ghPullRequestsAndWorkItemsApi = {
     ipcRenderer.invoke('gh:rerunPRChecks', args),
   prComments: (args: {
     repoPath: string
-    repoId?: string
+    repoId?: string | null
     sourceContext?: TaskSourceContext | null
     prNumber: number
     prRepo?: GitHubOwnerRepo | null
     noCache?: boolean
-  }): Promise<unknown[]> => ipcRenderer.invoke('gh:prComments', args),
+  }) => ipcRenderer.invoke('gh:prComments', args),
   setPRCommentReaction: (args: {
     repoPath: string
-    repoId?: string
+    repoId?: string | null
     sourceContext?: TaskSourceContext | null
     reactionSubjectId: string
     content: GitHubReactionContent
@@ -159,7 +160,7 @@ export const ghPullRequestsAndWorkItemsApi = {
   }): Promise<boolean> => ipcRenderer.invoke('gh:setPRCommentReaction', args),
   resolveReviewThread: (args: {
     repoPath: string
-    repoId?: string
+    repoId?: string | null
     sourceContext?: TaskSourceContext | null
     threadId: string
     resolve: boolean
@@ -167,7 +168,7 @@ export const ghPullRequestsAndWorkItemsApi = {
   }): Promise<boolean> => ipcRenderer.invoke('gh:resolveReviewThread', args),
   setPRFileViewed: (args: {
     repoPath: string
-    repoId?: string
+    repoId?: string | null
     sourceContext?: TaskSourceContext | null
     prNumber: number
     prRepo?: GitHubOwnerRepo | null
@@ -177,17 +178,17 @@ export const ghPullRequestsAndWorkItemsApi = {
   }): Promise<boolean> => ipcRenderer.invoke('gh:setPRFileViewed', args),
   updatePRTitle: (args: {
     repoPath: string
-    repoId?: string
+    repoId?: string | null
     prNumber: number
     title: string
     prRepo?: GitHubOwnerRepo | null
   }): Promise<boolean> => ipcRenderer.invoke('gh:updatePRTitle', args),
   mergePR: (args: {
     repoPath: string
-    repoId?: string
+    repoId?: string | null
     sourceContext?: TaskSourceContext | null
     prNumber: number
     method?: 'merge' | 'squash' | 'rebase'
     prRepo?: GitHubOwnerRepo | null
   }): Promise<{ ok: true } | { ok: false; error: string }> => ipcRenderer.invoke('gh:mergePR', args)
-}
+} satisfies Partial<PreloadApi['gh']>
diff --git a/src/preload/api/gh-bridge.ts b/src/preload/api/gh-bridge.ts
index 52c21a966a7..c7da93698e6 100644
--- a/src/preload/api/gh-bridge.ts
+++ b/src/preload/api/gh-bridge.ts
@@ -1,4 +1,8 @@
+import type { PreloadApi } from '../api-types'
 import { ghPullRequestsAndWorkItemsApi } from './gh-bridge-pull-requests-and-work-items'
 import { ghMutationsAndProjectsApi } from './gh-bridge-mutations-and-projects'
 
-export const ghApi = { ...ghPullRequestsAndWorkItemsApi, ...ghMutationsAndProjectsApi }
+export const ghApi = {
+  ...ghPullRequestsAndWorkItemsApi,
+  ...ghMutationsAndProjectsApi
+} satisfies PreloadApi['gh']
diff --git a/src/preload/api/git-bash-bridge.ts b/src/preload/api/git-bash-bridge.ts
index bd62dfc614a..c2186d12aa3 100644
--- a/src/preload/api/git-bash-bridge.ts
+++ b/src/preload/api/git-bash-bridge.ts
@@ -1,5 +1,6 @@
 import { ipcRenderer } from 'electron'
+import type { PreloadApi } from '../api-types'
 
 export const gitBashApi = {
   isAvailable: (): Promise<boolean> => ipcRenderer.invoke('gitBash:isAvailable')
-}
+} satisfies PreloadApi['gitBash']
diff --git a/src/preload/api/git-bridge.ts b/src/preload/api/git-bridge.ts
index 89dfc8db5ae..987abab14fc 100644
--- a/src/preload/api/git-bridge.ts
+++ b/src/preload/api/git-bridge.ts
@@ -3,6 +3,7 @@ import type { GitForkSyncExpectedUpstream, GitForkSyncResult } from '../../share
 import type { GitStagingArea, GitUpstreamStatus } from '../../shared/git-status-types'
 import type { GitPushTarget } from '../../shared/worktree/types'
 import type { GitHistoryOptions, GitHistoryResult } from '../../shared/git-history'
+import type { PreloadApi } from '../api-types'
 
 export const gitApi = {
   status: (args: {
@@ -13,7 +14,7 @@ export const gitApi = {
     reuseLineStats?: boolean
     branchLineTotalMergeBase?: string
     requestToken?: string
-  }): Promise<unknown> => ipcRenderer.invoke('git:status', args),
+  }) => ipcRenderer.invoke('git:status', args),
   cancelStatus: (args: { requestToken: string }): Promise<void> =>
     ipcRenderer.invoke('git:cancelStatus', args),
   setStatusUpstreamRefWatch: (args: {
@@ -29,7 +30,7 @@ export const gitApi = {
     submodulePath: string
     connectionId?: string
     area?: GitStagingArea
-  }): Promise<unknown> => ipcRenderer.invoke('git:submoduleStatus', args),
+  }) => ipcRenderer.invoke('git:submoduleStatus', args),
   checkIgnored: (args: {
     worktreePath: string
     paths: string[]
@@ -42,7 +43,7 @@ export const gitApi = {
   history: (
     args: { worktreePath: string; connectionId?: string } & GitHistoryOptions
   ): Promise<GitHistoryResult> => ipcRenderer.invoke('git:history', args),
-  conflictOperation: (args: { worktreePath: string; connectionId?: string }): Promise<unknown> =>
+  conflictOperation: (args: { worktreePath: string; connectionId?: string }) =>
     ipcRenderer.invoke('git:conflictOperation', args),
   abortMerge: (args: { worktreePath: string; connectionId?: string }): Promise<void> =>
     ipcRenderer.invoke('git:abortMerge', args),
@@ -54,17 +55,11 @@ export const gitApi = {
     staged: boolean
     compareAgainstHead?: boolean
     connectionId?: string
-  }): Promise<unknown> => ipcRenderer.invoke('git:diff', args),
-  branchCompare: (args: {
-    worktreePath: string
-    baseRef: string
-    connectionId?: string
-  }): Promise<unknown> => ipcRenderer.invoke('git:branchCompare', args),
-  commitCompare: (args: {
-    worktreePath: string
-    commitId: string
-    connectionId?: string
-  }): Promise<unknown> => ipcRenderer.invoke('git:commitCompare', args),
+  }) => ipcRenderer.invoke('git:diff', args),
+  branchCompare: (args: { worktreePath: string; baseRef: string; connectionId?: string }) =>
+    ipcRenderer.invoke('git:branchCompare', args),
+  commitCompare: (args: { worktreePath: string; commitId: string; connectionId?: string }) =>
+    ipcRenderer.invoke('git:commitCompare', args),
   upstreamStatus: (args: {
     worktreePath: string
     connectionId?: string
@@ -108,7 +103,7 @@ export const gitApi = {
     filePath: string
     oldPath?: string
     connectionId?: string
-  }): Promise<unknown> => ipcRenderer.invoke('git:branchDiff', args),
+  }) => ipcRenderer.invoke('git:branchDiff', args),
   commitDiff: (args: {
     worktreePath: string
     commitOid: string
@@ -116,7 +111,7 @@ export const gitApi = {
     filePath: string
     oldPath?: string
     connectionId?: string
-  }): Promise<unknown> => ipcRenderer.invoke('git:commitDiff', args),
+  }) => ipcRenderer.invoke('git:commitDiff', args),
   commit: (args: {
     worktreePath: string
     message: string
@@ -130,12 +125,12 @@ export const gitApi = {
     sourceControlAiResolvedParams?: unknown
     sourceControlAi?: unknown
     agentCmdOverrides?: Record<string, string>
-  }): Promise<unknown> => ipcRenderer.invoke('git:generateCommitMessage', args),
+  }) => ipcRenderer.invoke('git:generateCommitMessage', args),
   discoverCommitMessageModels: (args: {
     agentId: string
     worktreePath?: string
     connectionId?: string
-  }): Promise<unknown> => ipcRenderer.invoke('git:discoverCommitMessageModels', args),
+  }) => ipcRenderer.invoke('git:discoverCommitMessageModels', args),
   cancelGenerateCommitMessage: (args: {
     worktreePath: string
     connectionId?: string
@@ -154,7 +149,7 @@ export const gitApi = {
     sourceControlAiResolvedParams?: unknown
     sourceControlAi?: unknown
     agentCmdOverrides?: Record<string, string>
-  }): Promise<unknown> => ipcRenderer.invoke('git:generatePullRequestFields', args),
+  }) => ipcRenderer.invoke('git:generatePullRequestFields', args),
   cancelGeneratePullRequestFields: (args: {
     worktreePath: string
     connectionId?: string
@@ -197,4 +192,4 @@ export const gitApi = {
     sha: string
     connectionId?: string
   }): Promise<string | null> => ipcRenderer.invoke('git:remoteCommitUrl', args)
-}
+} satisfies PreloadApi['git']
diff --git a/src/preload/api/gl-bridge.ts b/src/preload/api/gl-bridge.ts
index c48794a4976..3977536a838 100644
--- a/src/preload/api/gl-bridge.ts
+++ b/src/preload/api/gl-bridge.ts
@@ -1,3 +1,4 @@
 import { glApi } from '../gitlab'
+import type { PreloadApi } from '../api-types'
 
-export const glApiBridge = glApi
+export const glApiBridge = glApi satisfies PreloadApi['gl']
diff --git a/src/preload/api/grok-accounts-bridge.ts b/src/preload/api/grok-accounts-bridge.ts
index b4719905ec7..246fc97bc56 100644
--- a/src/preload/api/grok-accounts-bridge.ts
+++ b/src/preload/api/grok-accounts-bridge.ts
@@ -1,6 +1,7 @@
 import { ipcRenderer } from 'electron'
 import type { GrokAccountStatus } from '../../shared/rate-limit-types'
+import type { PreloadApi } from '../api-types'
 
 export const grokAccountsApi = {
   getStatus: (): Promise<GrokAccountStatus> => ipcRenderer.invoke('grokAccounts:getStatus')
-}
+} satisfies PreloadApi['grokAccounts']
diff --git a/src/preload/api/hooks-bridge.ts b/src/preload/api/hooks-bridge.ts
index 59a6fee71b6..75c48281b16 100644
--- a/src/preload/api/hooks-bridge.ts
+++ b/src/preload/api/hooks-bridge.ts
@@ -1,22 +1,14 @@
 import { ipcRenderer } from 'electron'
 import type { WorktreeSetupLaunch } from '../../shared/worktree/launch-types'
 import type { ExecutionHostId } from '../../shared/execution-host'
+import type { PreloadApi } from '../api-types'
 
 export const hooksApi = {
-  check: (args: {
-    repoId: string
-    hostId?: ExecutionHostId
-  }): Promise<{
-    status?: 'ok' | 'error'
-    hasHooks: boolean
-    hooks: unknown
-    mayNeedUpdate: boolean
-  }> => ipcRenderer.invoke('hooks:check', args),
+  check: (args: { repoId: string; hostId?: ExecutionHostId }) =>
+    ipcRenderer.invoke('hooks:check', args),
 
-  inspectSetupScriptImports: (args: {
-    repoId: string
-    hostId?: ExecutionHostId
-  }): Promise<unknown[]> => ipcRenderer.invoke('hooks:inspectSetupScriptImports', args),
+  inspectSetupScriptImports: (args: { repoId: string; hostId?: ExecutionHostId }) =>
+    ipcRenderer.invoke('hooks:inspectSetupScriptImports', args),
 
   createIssueCommandRunner: (args: {
     repoId: string
@@ -41,4 +33,4 @@ export const hooksApi = {
     content: string
     hostId?: ExecutionHostId
   }): Promise<void> => ipcRenderer.invoke('hooks:writeIssueCommand', args)
-}
+} satisfies PreloadApi['hooks']
diff --git a/src/preload/api/hosted-review-bridge.ts b/src/preload/api/hosted-review-bridge.ts
index dc8323b5bf3..b7e0d12af5c 100644
--- a/src/preload/api/hosted-review-bridge.ts
+++ b/src/preload/api/hosted-review-bridge.ts
@@ -1,12 +1,12 @@
 import { ipcRenderer } from 'electron'
 import type { HostedReviewForBranchArgs } from '../../shared/hosted-review'
+import type { PreloadApi } from '../api-types'
 
 export const hostedReviewApi = {
-  forBranch: (args: HostedReviewForBranchArgs): Promise<unknown> =>
+  forBranch: (args: HostedReviewForBranchArgs) =>
     ipcRenderer.invoke('hostedReview:forBranch', args),
-  getCreationEligibility: (args: unknown): Promise<unknown> =>
+  getCreationEligibility: (args: unknown) =>
     ipcRenderer.invoke('hostedReview:getCreationEligibility', args),
-  create: (args: unknown): Promise<unknown> => ipcRenderer.invoke('hostedReview:create', args),
-  createStacked: (args: unknown): Promise<unknown> =>
-    ipcRenderer.invoke('hostedReview:createStacked', args)
-}
+  create: (args: unknown) => ipcRenderer.invoke('hostedReview:create', args),
+  createStacked: (args: unknown) => ipcRenderer.invoke('hostedReview:createStacked', args)
+} satisfies PreloadApi['hostedReview']
diff --git a/src/preload/api/jira-bridge.ts b/src/preload/api/jira-bridge.ts
index 47a27b77f68..4b6b991095d 100644
--- a/src/preload/api/jira-bridge.ts
+++ b/src/preload/api/jira-bridge.ts
@@ -1,5 +1,6 @@
 import { ipcRenderer } from 'electron'
 import type { JiraProjectStatusOrder } from '../../shared/jira-types'
+import type { PreloadApi } from '../api-types'
 
 export const jiraApi = {
   connect: (args: {
@@ -7,30 +8,21 @@ export const jiraApi = {
     email: string
     apiToken: string
     authType?: 'cloud' | 'server'
-  }): Promise<{ ok: true; viewer: unknown } | { ok: false; error: string }> =>
-    ipcRenderer.invoke('jira:connect', args),
+  }) => ipcRenderer.invoke('jira:connect', args),
 
   disconnect: (args?: { siteId?: string }): Promise<void> =>
     ipcRenderer.invoke('jira:disconnect', args),
 
-  selectSite: (args: { siteId: string }): Promise<unknown> =>
-    ipcRenderer.invoke('jira:selectSite', args),
+  selectSite: (args: { siteId: string }) => ipcRenderer.invoke('jira:selectSite', args),
 
-  status: (): Promise<unknown> => ipcRenderer.invoke('jira:status'),
+  status: () => ipcRenderer.invoke('jira:status'),
 
-  readStatus: (): Promise<unknown> => ipcRenderer.invoke('jira:readStatus'),
+  readStatus: () => ipcRenderer.invoke('jira:readStatus'),
 
-  testConnection: (args?: {
-    siteId?: string
-  }): Promise<{ ok: true; viewer: unknown } | { ok: false; error: string }> =>
-    ipcRenderer.invoke('jira:testConnection', args),
+  testConnection: (args?: { siteId?: string }) => ipcRenderer.invoke('jira:testConnection', args),
 
-  searchIssues: (args: {
-    jql: string
-    limit?: number
-    siteId?: string
-    requestId?: string
-  }): Promise<unknown[]> => ipcRenderer.invoke('jira:searchIssues', args),
+  searchIssues: (args: { jql: string; limit?: number; siteId?: string; requestId?: string }) =>
+    ipcRenderer.invoke('jira:searchIssues', args),
   cancelSearchIssues: (args: { requestId: string }): Promise<void> =>
     ipcRenderer.invoke('jira:cancelSearchIssues', args),
 
@@ -38,16 +30,12 @@ export const jiraApi = {
     filter?: 'assigned' | 'reported' | 'all' | 'done'
     limit?: number
     siteId?: string
-  }): Promise<unknown[]> => ipcRenderer.invoke('jira:listIssues', args),
+  }) => ipcRenderer.invoke('jira:listIssues', args),
 
-  getIssue: (args: { key: string; siteId?: string }): Promise<unknown> =>
-    ipcRenderer.invoke('jira:getIssue', args),
+  getIssue: (args: { key: string; siteId?: string }) => ipcRenderer.invoke('jira:getIssue', args),
 
-  lookupIssueSummary: (args: {
-    key: string
-    siteId: string
-    requestId?: string
-  }): Promise<unknown> => ipcRenderer.invoke('jira:lookupIssueSummary', args),
+  lookupIssueSummary: (args: { key: string; siteId: string; requestId?: string }) =>
+    ipcRenderer.invoke('jira:lookupIssueSummary', args),
   cancelIssueSummary: (args: { requestId: string }): Promise<void> =>
     ipcRenderer.invoke('jira:cancelIssueSummary', args),
 
@@ -75,36 +63,28 @@ export const jiraApi = {
   }): Promise<{ ok: true; id: string } | { ok: false; error: string }> =>
     ipcRenderer.invoke('jira:addIssueComment', args),
 
-  issueComments: (args: { key: string; siteId?: string }): Promise<unknown[]> =>
+  issueComments: (args: { key: string; siteId?: string }) =>
     ipcRenderer.invoke('jira:issueComments', args),
 
-  listProjects: (args?: { siteId?: string }): Promise<unknown[]> =>
-    ipcRenderer.invoke('jira:listProjects', args),
+  listProjects: (args?: { siteId?: string }) => ipcRenderer.invoke('jira:listProjects', args),
 
-  listIssueTypes: (args: { projectIdOrKey: string; siteId?: string }): Promise<unknown[]> =>
+  listIssueTypes: (args: { projectIdOrKey: string; siteId?: string }) =>
     ipcRenderer.invoke('jira:listIssueTypes', args),
 
-  listCreateFields: (args: {
-    projectIdOrKey: string
-    issueTypeId: string
-    siteId?: string
-  }): Promise<unknown[]> => ipcRenderer.invoke('jira:listCreateFields', args),
+  listCreateFields: (args: { projectIdOrKey: string; issueTypeId: string; siteId?: string }) =>
+    ipcRenderer.invoke('jira:listCreateFields', args),
 
-  listPriorities: (args?: { siteId?: string }): Promise<unknown[]> =>
-    ipcRenderer.invoke('jira:listPriorities', args),
+  listPriorities: (args?: { siteId?: string }) => ipcRenderer.invoke('jira:listPriorities', args),
 
-  listAssignableUsers: (args: {
-    key: string
-    query?: string
-    siteId?: string
-  }): Promise<unknown[]> => ipcRenderer.invoke('jira:listAssignableUsers', args),
-  searchUsers: (args?: { query?: string; siteId?: string }): Promise<unknown[]> =>
+  listAssignableUsers: (args: { key: string; query?: string; siteId?: string }) =>
+    ipcRenderer.invoke('jira:listAssignableUsers', args),
+  searchUsers: (args?: { query?: string; siteId?: string }) =>
     ipcRenderer.invoke('jira:searchUsers', args),
 
-  listTransitions: (args: { key: string; siteId?: string }): Promise<unknown[]> =>
+  listTransitions: (args: { key: string; siteId?: string }) =>
     ipcRenderer.invoke('jira:listTransitions', args),
   getProjectStatusOrder: (args: {
     projectKey: string
     siteId?: string
   }): Promise<JiraProjectStatusOrder> => ipcRenderer.invoke('jira:getProjectStatusOrder', args)
-}
+} satisfies PreloadApi['jira']
diff --git a/src/preload/api/keybindings-bridge.ts b/src/preload/api/keybindings-bridge.ts
index 3111ddd6676..e91e587313d 100644
--- a/src/preload/api/keybindings-bridge.ts
+++ b/src/preload/api/keybindings-bridge.ts
@@ -1,5 +1,6 @@
 import { ipcRenderer } from 'electron'
 import type { KeybindingActionId, KeybindingFileSnapshot } from '../../shared/keybindings'
+import type { PreloadApi } from '../api-types'
 
 export const keybindingsApi = {
   get: (): Promise<KeybindingFileSnapshot> => ipcRenderer.invoke('keybindings:get'),
@@ -17,4 +18,4 @@ export const keybindingsApi = {
     ipcRenderer.on('keybindings:changed', listener)
     return () => ipcRenderer.removeListener('keybindings:changed', listener)
   }
-}
+} satisfies PreloadApi['keybindings']
diff --git a/src/preload/api/linear-bridge.ts b/src/preload/api/linear-bridge.ts
index cd6ec0e9c15..8092a8e70e7 100644
--- a/src/preload/api/linear-bridge.ts
+++ b/src/preload/api/linear-bridge.ts
@@ -1,37 +1,30 @@
 import { ipcRenderer } from 'electron'
 import type { LinearProjectDetail } from '../../shared/linear/project-types'
+import type { PreloadApi } from '../api-types'
 
 export const linearApi = {
-  connect: (args: {
-    apiKey: string
-  }): Promise<{ ok: true; viewer: unknown } | { ok: false; error: string }> =>
-    ipcRenderer.invoke('linear:connect', args),
+  connect: (args: { apiKey: string }) => ipcRenderer.invoke('linear:connect', args),
 
   disconnect: (args?: { workspaceId?: string }): Promise<void> =>
     ipcRenderer.invoke('linear:disconnect', args),
 
-  selectWorkspace: (args: { workspaceId: string }): Promise<unknown> =>
+  selectWorkspace: (args: { workspaceId: string }) =>
     ipcRenderer.invoke('linear:selectWorkspace', args),
 
-  status: (): Promise<unknown> => ipcRenderer.invoke('linear:status'),
+  status: () => ipcRenderer.invoke('linear:status'),
 
-  testConnection: (args?: {
-    workspaceId?: string
-  }): Promise<{ ok: true; viewer: unknown } | { ok: false; error: string }> =>
+  testConnection: (args?: { workspaceId?: string }) =>
     ipcRenderer.invoke('linear:testConnection', args),
 
-  searchIssues: (args: {
-    query: string
-    limit?: number
-    workspaceId?: string
-  }): Promise<unknown[]> => ipcRenderer.invoke('linear:searchIssues', args),
+  searchIssues: (args: { query: string; limit?: number; workspaceId?: string }) =>
+    ipcRenderer.invoke('linear:searchIssues', args),
 
   listIssues: (args?: {
     filter?: 'assigned' | 'created' | 'all' | 'completed'
     limit?: number
     workspaceId?: string
     attributeFilter?: unknown
-  }): Promise<unknown> => ipcRenderer.invoke('linear:listIssues', args),
+  }) => ipcRenderer.invoke('linear:listIssues', args),
 
   createIssue: (args: {
     teamId: string
@@ -49,7 +42,7 @@ export const linearApi = {
     | { ok: false; error: string }
   > => ipcRenderer.invoke('linear:createIssue', args),
 
-  getIssue: (args: { id: string; workspaceId?: string }): Promise<unknown> =>
+  getIssue: (args: { id: string; workspaceId?: string }) =>
     ipcRenderer.invoke('linear:getIssue', args),
 
   updateIssue: (args: {
@@ -66,18 +59,17 @@ export const linearApi = {
   }): Promise<{ ok: true; id: string } | { ok: false; error: string }> =>
     ipcRenderer.invoke('linear:addIssueComment', args),
 
-  issueComments: (args: { issueId: string; workspaceId?: string }): Promise<unknown[]> =>
+  issueComments: (args: { issueId: string; workspaceId?: string }) =>
     ipcRenderer.invoke('linear:issueComments', args),
 
-  listTeams: (args?: { workspaceId?: string }): Promise<unknown[]> =>
-    ipcRenderer.invoke('linear:listTeams', args),
+  listTeams: (args?: { workspaceId?: string }) => ipcRenderer.invoke('linear:listTeams', args),
 
   listProjects: (args?: {
     query?: string
     limit?: number
     workspaceId?: string
     force?: boolean
-  }): Promise<unknown> => ipcRenderer.invoke('linear:listProjects', args),
+  }) => ipcRenderer.invoke('linear:listProjects', args),
 
   createProject: (args: {
     name: string
@@ -94,7 +86,7 @@ export const linearApi = {
   }): Promise<{ ok: true; project: LinearProjectDetail } | { ok: false; error: string }> =>
     ipcRenderer.invoke('linear:createProject', args),
 
-  getProject: (args: { id: string; workspaceId: string; force?: boolean }): Promise<unknown> =>
+  getProject: (args: { id: string; workspaceId: string; force?: boolean }) =>
     ipcRenderer.invoke('linear:getProject', args),
 
   listProjectIssues: (args: {
@@ -102,42 +94,38 @@ export const linearApi = {
     limit?: number
     workspaceId: string
     force?: boolean
-  }): Promise<unknown> => ipcRenderer.invoke('linear:listProjectIssues', args),
+  }) => ipcRenderer.invoke('linear:listProjectIssues', args),
 
   listCustomViews: (args: {
     model: string
     limit?: number
     workspaceId?: string
     force?: boolean
-  }): Promise<unknown> => ipcRenderer.invoke('linear:listCustomViews', args),
+  }) => ipcRenderer.invoke('linear:listCustomViews', args),
 
-  getCustomView: (args: {
-    viewId: string
-    model: string
-    workspaceId: string
-    force?: boolean
-  }): Promise<unknown> => ipcRenderer.invoke('linear:getCustomView', args),
+  getCustomView: (args: { viewId: string; model: string; workspaceId: string; force?: boolean }) =>
+    ipcRenderer.invoke('linear:getCustomView', args),
 
   listCustomViewIssues: (args: {
     viewId: string
     limit?: number
     workspaceId: string
     force?: boolean
-  }): Promise<unknown> => ipcRenderer.invoke('linear:listCustomViewIssues', args),
+  }) => ipcRenderer.invoke('linear:listCustomViewIssues', args),
 
   listCustomViewProjects: (args: {
     viewId: string
     limit?: number
     workspaceId: string
     force?: boolean
-  }): Promise<unknown> => ipcRenderer.invoke('linear:listCustomViewProjects', args),
+  }) => ipcRenderer.invoke('linear:listCustomViewProjects', args),
 
-  teamStates: (args: { teamId: string; workspaceId?: string }): Promise<unknown[]> =>
+  teamStates: (args: { teamId: string; workspaceId?: string }) =>
     ipcRenderer.invoke('linear:teamStates', args),
 
-  teamLabels: (args: { teamId: string; workspaceId?: string }): Promise<unknown[]> =>
+  teamLabels: (args: { teamId: string; workspaceId?: string }) =>
     ipcRenderer.invoke('linear:teamLabels', args),
 
-  teamMembers: (args: { teamId: string; workspaceId?: string }): Promise<unknown[]> =>
+  teamMembers: (args: { teamId: string; workspaceId?: string }) =>
     ipcRenderer.invoke('linear:teamMembers', args)
-}
+} satisfies PreloadApi['linear']
diff --git a/src/preload/api/macos-tcc-prompts-bridge.ts b/src/preload/api/macos-tcc-prompts-bridge.ts
index 0c6c6b184fc..ef24b9e203e 100644
--- a/src/preload/api/macos-tcc-prompts-bridge.ts
+++ b/src/preload/api/macos-tcc-prompts-bridge.ts
@@ -1,11 +1,14 @@
 import { ipcRenderer } from 'electron'
+import type { PreloadApi } from '../api-types'
 
 export const macosTccPromptsApi = {
-  onThreshold: (callback: (payload: unknown) => void) => {
-    const listener = (_event: Electron.IpcRendererEvent, payload: unknown): void =>
+  onThreshold: (callback: (payload: { promptCount: number }) => void) => {
+    const listener = (_event: Electron.IpcRendererEvent, payload: { promptCount: number }): void =>
       callback(payload)
     ipcRenderer.on('macosTccPrompts:threshold', listener)
-    return () => ipcRenderer.removeListener('macosTccPrompts:threshold', listener)
+    return (): void => {
+      ipcRenderer.removeListener('macosTccPrompts:threshold', listener)
+    }
   },
   consumePending: (): Promise<{ claimId: number; promptCount: number } | null> =>
     ipcRenderer.invoke('macosTccPrompts:consumePending'),
@@ -14,4 +17,4 @@ export const macosTccPromptsApi = {
   releasePending: (claimId: number): Promise<void> =>
     ipcRenderer.invoke('macosTccPrompts:releasePending', claimId),
   dismiss: (): Promise<void> => ipcRenderer.invoke('macosTccPrompts:dismiss')
-}
+} satisfies PreloadApi['macosTccPrompts']
diff --git a/src/preload/api/memory-bridge.ts b/src/preload/api/memory-bridge.ts
index 15af55cb09c..c1735f86e31 100644
--- a/src/preload/api/memory-bridge.ts
+++ b/src/preload/api/memory-bridge.ts
@@ -1,6 +1,7 @@
 import { ipcRenderer } from 'electron'
 import type { MemorySnapshot } from '../../shared/process-stats-types'
+import type { PreloadApi } from '../api-types'
 
 export const memoryApi = {
   getSnapshot: (): Promise<MemorySnapshot> => ipcRenderer.invoke('memory:getSnapshot')
-}
+} satisfies PreloadApi['memory']
diff --git a/src/preload/api/minimax-credentials-bridge.ts b/src/preload/api/minimax-credentials-bridge.ts
index a758d9e2e5b..e99bd843909 100644
--- a/src/preload/api/minimax-credentials-bridge.ts
+++ b/src/preload/api/minimax-credentials-bridge.ts
@@ -1,4 +1,5 @@
 import { ipcRenderer } from 'electron'
+import type { PreloadApi } from '../api-types'
 
 export const minimaxCredentialsApi = {
   getStatus: (): Promise<{ configured: boolean }> =>
@@ -7,4 +8,4 @@ export const minimaxCredentialsApi = {
     ipcRenderer.invoke('minimaxCredentials:saveCookie', cookie),
   clearCookie: (): Promise<{ configured: boolean }> =>
     ipcRenderer.invoke('minimaxCredentials:clearCookie')
-}
+} satisfies PreloadApi['minimaxCredentials']
diff --git a/src/preload/api/mobile-bridge.ts b/src/preload/api/mobile-bridge.ts
index 836f27f6f37..a1ad9a4c716 100644
--- a/src/preload/api/mobile-bridge.ts
+++ b/src/preload/api/mobile-bridge.ts
@@ -3,6 +3,7 @@ import type { MobileRelayStatus } from '../../shared/mobile-relay-status'
 import type { MobilePairingConnectionMode } from '../../shared/mobile-pairing-connection-mode'
 import type { RuntimePairingReach } from '../../shared/runtime-pairing-reach'
 import type { MobileRelayMintFailure } from '../../shared/mobile-relay-mint-failure'
+import type { PreloadApi } from '../api-types'
 
 export const mobileApi = {
   listNetworkInterfaces: (): Promise<{
@@ -92,4 +93,4 @@ export const mobileApi = {
     ipcRenderer.on('mobile:unpairedDeviceAuthFailure', listener)
     return () => ipcRenderer.removeListener('mobile:unpairedDeviceAuthFailure', listener)
   }
-}
+} satisfies PreloadApi['mobile']
diff --git a/src/preload/api/native-chat-bridge.ts b/src/preload/api/native-chat-bridge.ts
index 16c2906349e..3a0a5d9161a 100644
--- a/src/preload/api/native-chat-bridge.ts
+++ b/src/preload/api/native-chat-bridge.ts
@@ -2,7 +2,8 @@ import { ipcRenderer } from 'electron'
 import type {
   NativeChatAppendedPayload,
   NativeChatReadSessionResult,
-  NativeChatSubscriptionFrame
+  NativeChatSubscriptionFrame,
+  PreloadApi
 } from '../api-types'
 import type { AgentType } from '../../shared/native-chat-types'
 
@@ -37,4 +38,4 @@ export const nativeChatApi = {
       ipcRenderer.send('nativeChat:unsubscribe', { subscriptionId: args.subscriptionId })
     }
   }
-}
+} satisfies PreloadApi['nativeChat']
diff --git a/src/preload/api/notebook-bridge.ts b/src/preload/api/notebook-bridge.ts
index ee307b9f0e2..436726b7783 100644
--- a/src/preload/api/notebook-bridge.ts
+++ b/src/preload/api/notebook-bridge.ts
@@ -1,4 +1,5 @@
 import { ipcRenderer } from 'electron'
+import type { PreloadApi } from '../api-types'
 
 export const notebookApi = {
   runPythonCell: (args: {
@@ -8,4 +9,4 @@ export const notebookApi = {
     connectionId?: string | null
   }): Promise<{ stdout: string; stderr: string; exitCode: number | null; error?: string }> =>
     ipcRenderer.invoke('notebook:runPythonCell', args)
-}
+} satisfies PreloadApi['notebook']
diff --git a/src/preload/api/notifications-bridge.ts b/src/preload/api/notifications-bridge.ts
index aa84fb1a8a6..70c64d4ce0d 100644
--- a/src/preload/api/notifications-bridge.ts
+++ b/src/preload/api/notifications-bridge.ts
@@ -8,6 +8,7 @@ import type {
   NotificationSoundPathResult,
   NotificationSoundResult
 } from '../../shared/notification-settings-types'
+import type { PreloadApi } from '../api-types'
 
 // Why: cache one shared Audio + blob URL per sound path so notifications do not re-read large files.
 let cachedNotificationSound: {
@@ -117,4 +118,4 @@ export const notificationsApi = {
       return { played: false, reason: 'playback-failed' }
     }
   }
-}
+} satisfies PreloadApi['notifications']
diff --git a/src/preload/api/onboarding-bridge.ts b/src/preload/api/onboarding-bridge.ts
index 1b4393268ac..7939ab64810 100644
--- a/src/preload/api/onboarding-bridge.ts
+++ b/src/preload/api/onboarding-bridge.ts
@@ -1,5 +1,6 @@
 import { ipcRenderer } from 'electron'
 import type { OnboardingState } from '../../shared/onboarding-state-types'
+import type { PreloadApi } from '../api-types'
 
 export const onboardingApi = {
   get: (): Promise<OnboardingState> => ipcRenderer.invoke('onboarding:get'),
@@ -8,4 +9,4 @@ export const onboardingApi = {
       checklist?: Partial<OnboardingState['checklist']>
     }
   ): Promise<OnboardingState> => ipcRenderer.invoke('onboarding:update', updates)
-}
+} satisfies PreloadApi['onboarding']
diff --git a/src/preload/api/open-code-usage-bridge.ts b/src/preload/api/open-code-usage-bridge.ts
index 5cc668e6e00..cd3564d2b32 100644
--- a/src/preload/api/open-code-usage-bridge.ts
+++ b/src/preload/api/open-code-usage-bridge.ts
@@ -1,4 +1,8 @@
 import { ipcRenderer } from 'electron'
 import { createUsageProviderApi } from '../usage-provider-api'
+import type { PreloadApi } from '../api-types'
 
-export const openCodeUsageApi = createUsageProviderApi(ipcRenderer, 'openCodeUsage')
+export const openCodeUsageApi = createUsageProviderApi(
+  ipcRenderer,
+  'openCodeUsage'
+) satisfies PreloadApi['openCodeUsage']
diff --git a/src/preload/api/pet-bridge.ts b/src/preload/api/pet-bridge.ts
index 8a5d3309c5c..c51751b3161 100644
--- a/src/preload/api/pet-bridge.ts
+++ b/src/preload/api/pet-bridge.ts
@@ -1,5 +1,6 @@
 import { ipcRenderer } from 'electron'
 import type { CustomPet } from '../../shared/pet-types'
+import type { PreloadApi } from '../api-types'
 
 export const petApi = {
   import: (): Promise<CustomPet | null> => ipcRenderer.invoke('pet:import'),
@@ -8,4 +9,4 @@ export const petApi = {
     ipcRenderer.invoke('pet:read', id, fileName, kind),
   delete: (id: string, fileName: string, kind?: 'image' | 'bundle'): Promise<void> =>
     ipcRenderer.invoke('pet:delete', id, fileName, kind)
-}
+} satisfies PreloadApi['pet']
diff --git a/src/preload/api/plugins-bridge.ts b/src/preload/api/plugins-bridge.ts
index 2488d4cfdb7..0e529e74d96 100644
--- a/src/preload/api/plugins-bridge.ts
+++ b/src/preload/api/plugins-bridge.ts
@@ -24,11 +24,8 @@ export const pluginsApi = {
     pluginKey: string
     panelId: string
   }): Promise<PluginPanelEntry | null> => ipcRenderer.invoke('plugins:readPanelEntry', args),
-  invokeCommand: (args: {
-    pluginKey: string
-    commandId: string
-    args?: unknown
-  }): Promise<unknown> => ipcRenderer.invoke('plugins:invokeCommand', args),
+  invokeCommand: (args: { pluginKey: string; commandId: string; args?: unknown }) =>
+    ipcRenderer.invoke('plugins:invokeCommand', args),
   panelAction: (args: {
     sessionToken: string
     action: string
diff --git a/src/preload/api/preflight-bridge.ts b/src/preload/api/preflight-bridge.ts
index c05721a2d3b..64d317d139c 100644
--- a/src/preload/api/preflight-bridge.ts
+++ b/src/preload/api/preflight-bridge.ts
@@ -1,5 +1,5 @@
 import { ipcRenderer } from 'electron'
-import type { PreflightRuntimeContext, RefreshAgentsResult } from '../api-types'
+import type { PreflightRuntimeContext, PreloadApi, RefreshAgentsResult } from '../api-types'
 
 export const preflightApi = {
   check: (args?: {
@@ -40,4 +40,4 @@ export const preflightApi = {
     gitBashAvailable: boolean
     hostPlatform: NodeJS.Platform | null
   }> => ipcRenderer.invoke('preflight:detectRemoteWindowsTerminalCapabilities', args)
-}
+} satisfies PreloadApi['preflight']
diff --git a/src/preload/api/pty-bridge-session-control.ts b/src/preload/api/pty-bridge-session-control.ts
index 7e761738256..ef6002e11c8 100644
--- a/src/preload/api/pty-bridge-session-control.ts
+++ b/src/preload/api/pty-bridge-session-control.ts
@@ -15,6 +15,7 @@ import type {
 import type { TerminalViewAttributes } from '../../shared/terminal-view-attributes'
 import type { PtyMainDeliveryDiagnostics } from '../../shared/pty-delivery-diagnostics'
 import type { AgentKind, LaunchSource, RequestKind } from '../../shared/telemetry-events'
+import type { PreloadApi } from '../api-types'
 
 export const ptySessionControlApi = {
   spawn: (opts: {
@@ -204,4 +205,4 @@ export const ptySessionControlApi = {
     ipcRenderer.invoke('pty:hasChildProcesses', { id }),
   getForegroundProcess: (id: string): Promise<string | null> =>
     ipcRenderer.invoke('pty:getForegroundProcess', { id })
-}
+} satisfies Partial<PreloadApi['pty']>
diff --git a/src/preload/api/pty-bridge-stream-and-serialization.ts b/src/preload/api/pty-bridge-stream-and-serialization.ts
index 8fc9c48bce1..f751491c0e0 100644
--- a/src/preload/api/pty-bridge-stream-and-serialization.ts
+++ b/src/preload/api/pty-bridge-stream-and-serialization.ts
@@ -1,6 +1,7 @@
 import { ipcRenderer } from 'electron'
 import type { PtyModelRestoreNeededEvent } from '../../shared/pty-model-restore-marker'
 import type { TerminalSideEffectBatch } from '../../shared/terminal-side-effect-facts'
+import type { PreloadApi } from '../api-types'
 
 export const ptyStreamAndSerializationApi = {
   inspectProcess: (
@@ -138,4 +139,4 @@ export const ptyStreamAndSerializationApi = {
     restart: () => ipcRenderer.invoke('pty:management:restart'),
     macTccAttribution: () => ipcRenderer.invoke('pty:management:macTccAttribution')
   }
-}
+} satisfies Partial<PreloadApi['pty']>
diff --git a/src/preload/api/pty-bridge.ts b/src/preload/api/pty-bridge.ts
index df080692178..18f867e6426 100644
--- a/src/preload/api/pty-bridge.ts
+++ b/src/preload/api/pty-bridge.ts
@@ -1,4 +1,8 @@
+import type { PreloadApi } from '../api-types'
 import { ptySessionControlApi } from './pty-bridge-session-control'
 import { ptyStreamAndSerializationApi } from './pty-bridge-stream-and-serialization'
 
-export const ptyApi = { ...ptySessionControlApi, ...ptyStreamAndSerializationApi }
+export const ptyApi = {
+  ...ptySessionControlApi,
+  ...ptyStreamAndSerializationApi
+} satisfies PreloadApi['pty']
diff --git a/src/preload/api/pwsh-bridge.ts b/src/preload/api/pwsh-bridge.ts
index bd202277ad1..34ed9880ada 100644
--- a/src/preload/api/pwsh-bridge.ts
+++ b/src/preload/api/pwsh-bridge.ts
@@ -1,5 +1,6 @@
 import { ipcRenderer } from 'electron'
+import type { PreloadApi } from '../api-types'
 
 export const pwshApi = {
   isAvailable: (): Promise<boolean> => ipcRenderer.invoke('pwsh:isAvailable')
-}
+} satisfies PreloadApi['pwsh']
diff --git a/src/preload/api/rate-limits-bridge.ts b/src/preload/api/rate-limits-bridge.ts
index f403d79cdc6..37af13f0006 100644
--- a/src/preload/api/rate-limits-bridge.ts
+++ b/src/preload/api/rate-limits-bridge.ts
@@ -4,6 +4,7 @@ import type {
   RateLimitRuntimeTarget,
   RateLimitState
 } from '../../shared/rate-limit-types'
+import type { PreloadApi } from '../api-types'
 
 export const rateLimitsApi = {
   get: (): Promise<RateLimitState> => ipcRenderer.invoke('rateLimits:get'),
@@ -27,4 +28,4 @@ export const rateLimitsApi = {
     ipcRenderer.on('rateLimits:update', listener)
     return () => ipcRenderer.removeListener('rateLimits:update', listener)
   }
-}
+} satisfies PreloadApi['rateLimits']
diff --git a/src/preload/api/runtime-bridge.ts b/src/preload/api/runtime-bridge.ts
index c58049bcbe3..8b31e6873f5 100644
--- a/src/preload/api/runtime-bridge.ts
+++ b/src/preload/api/runtime-bridge.ts
@@ -9,6 +9,7 @@ import type {
 } from '../../shared/runtime-types'
 import type { RuntimeRpcResponse } from '../../shared/runtime-rpc-envelope'
 import type { RuntimeEnvironmentSubscriptionHandle } from '../runtime-environment-subscriptions'
+import type { PreloadApi } from '../api-types'
 
 export const runtimeApi = {
   syncWindowGraph: (graph: RuntimeRendererSyncWindowGraph): Promise<RuntimeSyncWindowGraphResult> =>
@@ -141,4 +142,4 @@ export const runtimeApi = {
     ipcRenderer.on('runtime:clientHostedBrowserRowsChanged', listener)
     return () => ipcRenderer.removeListener('runtime:clientHostedBrowserRowsChanged', listener)
   }
-}
+} satisfies PreloadApi['runtime']
diff --git a/src/preload/api/runtime-environments-bridge.ts b/src/preload/api/runtime-environments-bridge.ts
index d018c0574c8..ddfa498dc74 100644
--- a/src/preload/api/runtime-environments-bridge.ts
+++ b/src/preload/api/runtime-environments-bridge.ts
@@ -9,6 +9,7 @@ import {
   subscribeRuntimeEnvironmentFromPreload,
   type RuntimeEnvironmentSubscriptionHandle
 } from '../runtime-environment-subscriptions'
+import type { PreloadApi } from '../api-types'
 
 export const runtimeEnvironmentsApi = {
   list: (): Promise<PublicKnownRuntimeEnvironment[]> =>
@@ -90,4 +91,4 @@ export const runtimeEnvironmentsApi = {
     }
   ): Promise<RuntimeEnvironmentSubscriptionHandle> =>
     subscribeRuntimeEnvironmentFromPreload(ipcRenderer, args, callbacks)
-}
+} satisfies PreloadApi['runtimeEnvironments']
diff --git a/src/preload/api/settings-bridge.ts b/src/preload/api/settings-bridge.ts
index d8aaa23b0b7..4e7105c00cb 100644
--- a/src/preload/api/settings-bridge.ts
+++ b/src/preload/api/settings-bridge.ts
@@ -4,22 +4,20 @@ import type {
   WarpThemeImportPreview,
   WarpThemeImportSource
 } from '../../shared/terminal-custom-themes'
+import type { PreloadApi } from '../api-types'
 
 export const settingsApi = {
-  get: (): Promise<unknown> => ipcRenderer.invoke('settings:get'),
+  get: () => ipcRenderer.invoke('settings:get'),
 
   // Why: blocking read for the few startup decisions (terminal side-effect authority) that can't wait for async hydration. Call sparingly.
-  getSync: (): unknown => ipcRenderer.sendSync('settings:get-sync'),
+  getSync: () => ipcRenderer.sendSync('settings:get-sync'),
 
-  set: (args: Record<string, unknown>): Promise<unknown> =>
-    ipcRenderer.invoke('settings:set', args),
+  set: (args: Record<string, unknown>) => ipcRenderer.invoke('settings:set', args),
 
-  setActiveRuntimeEnvironmentPreference: (args: {
-    environmentId: string | null
-  }): Promise<unknown> =>
+  setActiveRuntimeEnvironmentPreference: (args: { environmentId: string | null }) =>
     ipcRenderer.invoke('settings:set-active-runtime-environment-preference', args),
 
-  updatePRBotAuthorOverride: (args: { author: string; isBot: boolean }): Promise<unknown> =>
+  updatePRBotAuthorOverride: (args: { author: string; isBot: boolean }) =>
     ipcRenderer.invoke('settings:update-pr-bot-author-override', args),
 
   listFonts: (): Promise<string[]> => ipcRenderer.invoke('settings:listFonts'),
@@ -36,4 +34,4 @@ export const settingsApi = {
     ipcRenderer.on('settings:changed', listener)
     return () => ipcRenderer.removeListener('settings:changed', listener)
   }
-}
+} satisfies PreloadApi['settings']
diff --git a/src/preload/api/shell-bridge.ts b/src/preload/api/shell-bridge.ts
index be34c7ff70e..21ccda3fd83 100644
--- a/src/preload/api/shell-bridge.ts
+++ b/src/preload/api/shell-bridge.ts
@@ -4,6 +4,7 @@ import type {
   ShellOpenExternalEditorResult,
   ShellOpenLocalPathResult
 } from '../../shared/shell-open-types'
+import type { PreloadApi } from '../api-types'
 
 export const shellApi = {
   openPath: (path: string): Promise<void> => ipcRenderer.invoke('shell:openPath', path),
@@ -38,4 +39,4 @@ export const shellApi = {
 
   copyFile: (args: { srcPath: string; destPath: string }): Promise<void> =>
     ipcRenderer.invoke('shell:copyFile', args)
-}
+} satisfies PreloadApi['shell']
diff --git a/src/preload/api/skills-bridge.ts b/src/preload/api/skills-bridge.ts
index eafaf2ce543..4bcde9a613c 100644
--- a/src/preload/api/skills-bridge.ts
+++ b/src/preload/api/skills-bridge.ts
@@ -37,6 +37,7 @@ import type {
   SkillUpdateRun,
   SkillUpdateStartResult
 } from '../../shared/skill-freshness'
+import type { PreloadApi } from '../api-types'
 
 export const skillsApi = {
   discover: (target?: SkillDiscoveryTarget): Promise<SkillDiscoveryResult> =>
@@ -126,4 +127,4 @@ export const skillsApi = {
     ipcRenderer.on('skills:updateRun', listener)
     return () => ipcRenderer.removeListener('skills:updateRun', listener)
   }
-}
+} satisfies PreloadApi['skills']
diff --git a/src/preload/api/speech-bridge.ts b/src/preload/api/speech-bridge.ts
index 513b219f498..dbd7e0d26ab 100644
--- a/src/preload/api/speech-bridge.ts
+++ b/src/preload/api/speech-bridge.ts
@@ -6,6 +6,7 @@ import type {
   SpeechModelState,
   SpeechTranscriptEvent
 } from '../../shared/speech-types'
+import type { PreloadApi } from '../api-types'
 
 export const speechApi = {
   getCatalog: (): Promise<SpeechModelManifest[]> => ipcRenderer.invoke('speech:getCatalog'),
@@ -78,4 +79,4 @@ export const speechApi = {
     ipcRenderer.on('speech:error', listener)
     return () => ipcRenderer.removeListener('speech:error', listener)
   }
-}
+} satisfies PreloadApi['speech']
diff --git a/src/preload/api/ssh-bridge.ts b/src/preload/api/ssh-bridge.ts
index 2884e4ec8c1..b0f7b89ec3d 100644
--- a/src/preload/api/ssh-bridge.ts
+++ b/src/preload/api/ssh-bridge.ts
@@ -17,6 +17,7 @@ import {
   admitSshDetectedPorts
 } from '../../shared/ssh-retained-payload-admission'
 import type { FilesystemPathFlavor } from '../../shared/filesystem-entry-types'
+import type { PreloadApi } from '../api-types'
 
 export const sshApi = {
   listTargets: (): Promise<SshTarget[]> => ipcRenderer.invoke('ssh:listTargets'),
@@ -180,4 +181,4 @@ export const sshApi = {
 
   submitCredential: (args: { requestId: string; value: string | null }): Promise<void> =>
     ipcRenderer.invoke('ssh:submitCredential', args)
-}
+} satisfies PreloadApi['ssh']
diff --git a/src/preload/api/star-nag-bridge.ts b/src/preload/api/star-nag-bridge.ts
index b697739a52f..49e56e4aa91 100644
--- a/src/preload/api/star-nag-bridge.ts
+++ b/src/preload/api/star-nag-bridge.ts
@@ -1,4 +1,5 @@
 import { ipcRenderer } from 'electron'
+import type { PreloadApi } from '../api-types'
 
 export const starNagApi = {
   onShow: (
@@ -27,4 +28,4 @@ export const starNagApi = {
     ipcRenderer.invoke('star-nag:agentValueMoment'),
   showAgentValueMoment: (): Promise<void> => ipcRenderer.invoke('star-nag:showAgentValueMoment'),
   onboardingCompleted: (): Promise<void> => ipcRenderer.invoke('star-nag:onboardingCompleted')
-}
+} satisfies PreloadApi['starNag']
diff --git a/src/preload/api/stats-bridge.ts b/src/preload/api/stats-bridge.ts
index 20bc823b86a..f435b9980f5 100644
--- a/src/preload/api/stats-bridge.ts
+++ b/src/preload/api/stats-bridge.ts
@@ -1,4 +1,5 @@
 import { ipcRenderer } from 'electron'
+import type { PreloadApi } from '../api-types'
 
 export const statsApi = {
   getSummary: (): Promise<{
@@ -7,4 +8,4 @@ export const statsApi = {
     totalAgentTimeMs: number
     firstEventAt: number | null
   }> => ipcRenderer.invoke('stats:summary')
-}
+} satisfies PreloadApi['stats']
diff --git a/src/preload/api/terminal-preview-bridge.ts b/src/preload/api/terminal-preview-bridge.ts
index c8bf5b38623..3bd94d4998b 100644
--- a/src/preload/api/terminal-preview-bridge.ts
+++ b/src/preload/api/terminal-preview-bridge.ts
@@ -3,6 +3,7 @@ import type {
   TerminalPreviewConnectResult,
   TerminalPreviewDataPayload
 } from '../../shared/terminal-preview'
+import type { PreloadApi } from '../api-types'
 
 export const terminalPreviewApi = {
   connect: (
@@ -30,4 +31,4 @@ export const terminalPreviewApi = {
     ipcRenderer.on('terminalPreview:data', listener)
     return () => ipcRenderer.removeListener('terminalPreview:data', listener)
   }
-}
+} satisfies PreloadApi['terminalPreview']
diff --git a/src/preload/api/ui-bridge-clipboard-and-window-controls.ts b/src/preload/api/ui-bridge-clipboard-and-window-controls.ts
index 867bd80026d..fdad19c2944 100644
--- a/src/preload/api/ui-bridge-clipboard-and-window-controls.ts
+++ b/src/preload/api/ui-bridge-clipboard-and-window-controls.ts
@@ -12,6 +12,7 @@ import {
 import type { NativeFileDropPayload } from '../../shared/native-file-drop'
 import type { ReadClipboardTextOptions } from '../../shared/clipboard-text'
 import { subscribeNativeFileDrop } from '../preload-runtime-support'
+import type { PreloadApi } from '../api-types'
 
 export const uiClipboardAndWindowControlsApi = {
   onOpenDiffFromMobile: (
@@ -195,4 +196,4 @@ export const uiClipboardAndWindowControlsApi = {
   notifyWindowRevealed: (): void => {
     ipcRenderer.send('ui:window-revealed')
   }
-}
+} satisfies Partial<PreloadApi['ui']>
diff --git a/src/preload/api/ui-bridge-state-and-menu-commands.ts b/src/preload/api/ui-bridge-state-and-menu-commands.ts
index 34eb83886c8..246cebb1613 100644
--- a/src/preload/api/ui-bridge-state-and-menu-commands.ts
+++ b/src/preload/api/ui-bridge-state-and-menu-commands.ts
@@ -2,6 +2,7 @@ import type { MarkdownDocument } from '../../shared/filesystem-entry-types'
 import { ipcRenderer } from 'electron'
 import type { PersistedUIState } from '../../shared/persisted-ui-state-types'
 import type { KeybindingActionId } from '../../shared/keybindings'
+import type { PreloadApi } from '../api-types'
 
 export const uiStateAndMenuCommandsApi = {
   get: () => ipcRenderer.invoke('ui:get'),
@@ -173,4 +174,4 @@ export const uiStateAndMenuCommandsApi = {
   replyTabCreate: (reply: { requestId: string; browserPageId?: string; error?: string }): void => {
     ipcRenderer.send('browser:tabCreateReply', reply)
   }
-}
+} satisfies Partial<PreloadApi['ui']>
diff --git a/src/preload/api/ui-bridge-tab-and-browser-commands.ts b/src/preload/api/ui-bridge-tab-and-browser-commands.ts
index ccca9a24f5b..d275367b398 100644
--- a/src/preload/api/ui-bridge-tab-and-browser-commands.ts
+++ b/src/preload/api/ui-bridge-tab-and-browser-commands.ts
@@ -6,6 +6,7 @@ import type {
   WorktreeSetupLaunch
 } from '../../shared/worktree/launch-types'
 import { browserFindSubscriptions } from '../preload-runtime-support'
+import type { PreloadApi } from '../api-types'
 
 export const uiTabAndBrowserCommandsApi = {
   onRequestTabSetProfile: (
@@ -200,4 +201,4 @@ export const uiTabAndBrowserCommandsApi = {
     ipcRenderer.on('ui:activateWorktree', listener)
     return () => ipcRenderer.removeListener('ui:activateWorktree', listener)
   }
-}
+} satisfies Partial<PreloadApi['ui']>
diff --git a/src/preload/api/ui-bridge-terminal-and-session-tabs.ts b/src/preload/api/ui-bridge-terminal-and-session-tabs.ts
index 9de47cceb0c..eaff9e8847a 100644
--- a/src/preload/api/ui-bridge-terminal-and-session-tabs.ts
+++ b/src/preload/api/ui-bridge-terminal-and-session-tabs.ts
@@ -11,6 +11,7 @@ import type {
   RuntimeTerminalCreateRequestPayload,
   RuntimeTerminalPresentation
 } from '../../shared/runtime-types'
+import type { PreloadApi } from '../api-types'
 
 export const uiTerminalAndSessionTabsApi = {
   onCreateTerminal: (
@@ -211,4 +212,4 @@ export const uiTerminalAndSessionTabsApi = {
     ipcRenderer.on('ui:openFileFromMobile', listener)
     return () => ipcRenderer.removeListener('ui:openFileFromMobile', listener)
   }
-}
+} satisfies Partial<PreloadApi['ui']>
diff --git a/src/preload/api/wsl-bridge.ts b/src/preload/api/wsl-bridge.ts
index aeb32cdfa45..bc7869000e4 100644
--- a/src/preload/api/wsl-bridge.ts
+++ b/src/preload/api/wsl-bridge.ts
@@ -1,6 +1,7 @@
 import { ipcRenderer } from 'electron'
+import type { PreloadApi } from '../api-types'
 
 export const wslApi = {
   isAvailable: (): Promise<boolean> => ipcRenderer.invoke('wsl:isAvailable'),
   listDistros: (): Promise<string[]> => ipcRenderer.invoke('wsl:listDistros')
-}
+} satisfies PreloadApi['wsl']
diff --git a/src/preload/app-restart-checkpoint-routing.test.ts b/src/preload/app-restart-checkpoint-routing.test.ts
index 19eb6948c9a..d794a86b9ab 100644
--- a/src/preload/app-restart-checkpoint-routing.test.ts
+++ b/src/preload/app-restart-checkpoint-routing.test.ts
@@ -92,6 +92,20 @@ describe('native preload destructive app actions', () => {
     })
   }
 
+  it('exposes the durable checkpoint join the lazy-chunk recovery reload depends on', async () => {
+    const api = await loadApi()
+    invoke.mockResolvedValue({ ok: true })
+
+    await expect(api.app.awaitBeforeUnloadCheckpoint()).resolves.toBeUndefined()
+    expect(invoke).toHaveBeenCalledWith('app:await-before-unload-checkpoint')
+
+    invoke.mockResolvedValue({ ok: false })
+
+    await expect(api.app.awaitBeforeUnloadCheckpoint()).rejects.toThrow(
+      'Failed to persist renderer state before unload.'
+    )
+  })
+
   it('preserves both macOS keyboard preload adapters', async () => {
     const api = await loadApi()
     invoke.mockResolvedValue(undefined)
diff --git a/src/preload/gitlab.ts b/src/preload/gitlab.ts
index d6f12367db0..154e139e4c4 100644
--- a/src/preload/gitlab.ts
+++ b/src/preload/gitlab.ts
@@ -12,23 +12,21 @@ type GitLabRepoSelectorArgs = {
 }
 
 export const glApi = {
-  viewer: (): Promise<unknown> => ipcRenderer.invoke('gitlab:viewer'),
-  diagnoseAuth: (): Promise<unknown> => ipcRenderer.invoke('gitlab:diagnoseAuth'),
-  rateLimit: (args?: { force?: boolean; host?: string | null }): Promise<unknown> =>
+  viewer: () => ipcRenderer.invoke('gitlab:viewer'),
+  diagnoseAuth: () => ipcRenderer.invoke('gitlab:diagnoseAuth'),
+  rateLimit: (args?: { force?: boolean; host?: string | null }) =>
     ipcRenderer.invoke('gitlab:rateLimit', args),
 
-  projectSlug: (args: GitLabRepoSelectorArgs): Promise<unknown> =>
-    ipcRenderer.invoke('gitlab:projectSlug', args),
+  projectSlug: (args: GitLabRepoSelectorArgs) => ipcRenderer.invoke('gitlab:projectSlug', args),
 
   mrForBranch: (
     args: GitLabRepoSelectorArgs & {
       branch: string
       linkedMRIid?: number | null
     }
-  ): Promise<unknown> => ipcRenderer.invoke('gitlab:mrForBranch', args),
+  ) => ipcRenderer.invoke('gitlab:mrForBranch', args),
 
-  mr: (args: GitLabRepoSelectorArgs & { iid: number }): Promise<unknown> =>
-    ipcRenderer.invoke('gitlab:mr', args),
+  mr: (args: GitLabRepoSelectorArgs & { iid: number }) => ipcRenderer.invoke('gitlab:mr', args),
 
   listMRs: (
     args: GitLabRepoSelectorArgs & {
@@ -37,7 +35,7 @@ export const glApi = {
       perPage?: number
       query?: string
     }
-  ): Promise<unknown> => ipcRenderer.invoke('gitlab:listMRs', args),
+  ) => ipcRenderer.invoke('gitlab:listMRs', args),
 
   listWorkItems: (
     args: GitLabRepoSelectorArgs & {
@@ -46,9 +44,9 @@ export const glApi = {
       perPage?: number
       query?: string
     }
-  ): Promise<unknown> => ipcRenderer.invoke('gitlab:listWorkItems', args),
+  ) => ipcRenderer.invoke('gitlab:listWorkItems', args),
 
-  issue: (args: GitLabRepoSelectorArgs & { number: number }): Promise<unknown> =>
+  issue: (args: GitLabRepoSelectorArgs & { number: number }) =>
     ipcRenderer.invoke('gitlab:issue', args),
 
   listIssues: (
@@ -58,8 +56,7 @@ export const glApi = {
       limit?: number
       page?: number
     }
-  ): Promise<{ items: unknown[]; totalPages?: number; error?: unknown }> =>
-    ipcRenderer.invoke('gitlab:listIssues', args),
+  ) => ipcRenderer.invoke('gitlab:listIssues', args),
 
   createIssue: (
     args: GitLabRepoSelectorArgs & {
@@ -77,25 +74,23 @@ export const glApi = {
   ): Promise<{ ok: true } | { ok: false; error: string }> =>
     ipcRenderer.invoke('gitlab:updateIssue', args),
 
-  addIssueComment: (
-    args: GitLabRepoSelectorArgs & { number: number; body: string }
-  ): Promise<unknown> => ipcRenderer.invoke('gitlab:addIssueComment', args),
+  addIssueComment: (args: GitLabRepoSelectorArgs & { number: number; body: string }) =>
+    ipcRenderer.invoke('gitlab:addIssueComment', args),
 
   listLabels: (args: GitLabRepoSelectorArgs): Promise<string[]> =>
     ipcRenderer.invoke('gitlab:listLabels', args),
 
-  listAssignableUsers: (args: GitLabRepoSelectorArgs): Promise<unknown[]> =>
+  listAssignableUsers: (args: GitLabRepoSelectorArgs) =>
     ipcRenderer.invoke('gitlab:listAssignableUsers', args),
 
-  todos: (args: GitLabRepoSelectorArgs): Promise<unknown[]> =>
-    ipcRenderer.invoke('gitlab:todos', args),
+  todos: (args: GitLabRepoSelectorArgs) => ipcRenderer.invoke('gitlab:todos', args),
 
   workItemDetails: (
     args: GitLabRepoSelectorArgs & {
       iid: number
       type: 'issue' | 'mr'
     }
-  ): Promise<unknown> => ipcRenderer.invoke('gitlab:workItemDetails', args),
+  ) => ipcRenderer.invoke('gitlab:workItemDetails', args),
 
   closeMR: (
     args: GitLabRepoSelectorArgs & {
@@ -133,9 +128,9 @@ export const glApi = {
       reviewerIds: number[]
       projectRef?: unknown
     }
-  ): Promise<unknown> => ipcRenderer.invoke('gitlab:updateMRReviewers', args),
+  ) => ipcRenderer.invoke('gitlab:updateMRReviewers', args),
 
-  addMRComment: (args: GitLabRepoSelectorArgs & { iid: number; body: string }): Promise<unknown> =>
+  addMRComment: (args: GitLabRepoSelectorArgs & { iid: number; body: string }) =>
     ipcRenderer.invoke('gitlab:addMRComment', args),
 
   addMRInlineComment: (
@@ -144,7 +139,7 @@ export const glApi = {
       input: unknown
       projectRef?: unknown
     }
-  ): Promise<unknown> => ipcRenderer.invoke('gitlab:addMRInlineComment', args),
+  ) => ipcRenderer.invoke('gitlab:addMRInlineComment', args),
 
   resolveMRDiscussion: (
     args: GitLabRepoSelectorArgs & {
@@ -152,15 +147,14 @@ export const glApi = {
       discussionId: string
       resolved: boolean
     }
-  ): Promise<unknown> => ipcRenderer.invoke('gitlab:resolveMRDiscussion', args),
+  ) => ipcRenderer.invoke('gitlab:resolveMRDiscussion', args),
 
   jobTrace: (
     args: GitLabRepoSelectorArgs & { jobId: number; projectRef?: unknown; logExcerpt?: boolean }
-  ): Promise<unknown> => ipcRenderer.invoke('gitlab:jobTrace', args),
+  ) => ipcRenderer.invoke('gitlab:jobTrace', args),
 
-  retryJob: (
-    args: GitLabRepoSelectorArgs & { jobId: number; projectRef?: unknown }
-  ): Promise<unknown> => ipcRenderer.invoke('gitlab:retryJob', args),
+  retryJob: (args: GitLabRepoSelectorArgs & { jobId: number; projectRef?: unknown }) =>
+    ipcRenderer.invoke('gitlab:retryJob', args),
 
   workItemByPath: (
     args: GitLabRepoSelectorArgs & {
@@ -169,5 +163,5 @@ export const glApi = {
       iid: number
       type: 'issue' | 'mr'
     }
-  ): Promise<unknown> => ipcRenderer.invoke('gitlab:workItemByPath', args)
+  ) => ipcRenderer.invoke('gitlab:workItemByPath', args)
 }
diff --git a/src/preload/index.ts b/src/preload/index.ts
index ad97a911fe5..27d3ca8e062 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -182,7 +182,7 @@ const api = {
   mobile: mobileApi,
   agentStatus: agentStatusApi,
   speech: speechApi
-}
+} satisfies PreloadApi
 
 if (process.contextIsolated) {
   try {
@@ -193,6 +193,5 @@ if (process.contextIsolated) {
   }
 } else {
   window.electron = electronAPI
-  // @ts-expect-error (define in dts)
   window.api = api
 }

From fd33f9b0f93ff03055a05c977496e93a1e2f6573 Mon Sep 17 00:00:00 2001
From: Jinwoo Hong <73622457+Jinwoo-H@users.noreply.github.com>
Date: Tue, 1 Sep 2026 21:52:36 -0400
Subject: [PATCH 19/32] fix(review-notes): classify send failures and mirrored
 tabs (#18023)

* fix(review-notes): classify send failures

* fix(review-notes): honor structured runtime error codes

* test(review-notes): use full runtime error envelope

* chore: remove unrelated merge formatting

* refactor(review-notes): share runtime failure codes

* fix(review-notes): classify structured runtime timeouts
---
 .../editor/ReviewNotesSendMenuContent.tsx     |  15 +-
 .../lib/active-agent-note-send-delivery.ts    | 152 +++++++++++
 .../lib/active-agent-note-send-diagnostics.ts |  82 ++++++
 ...ve-agent-note-send-explicit-target.test.ts | 147 ++++++++++-
 ...ve-agent-note-send-focused-session.test.ts |  14 +-
 .../src/lib/active-agent-note-send-result.ts  |  57 +++-
 ...gent-note-send-runtime-error-codes.test.ts |  56 ++++
 .../src/lib/active-agent-note-send.ts         | 245 ++++++------------
 .../src/lib/active-agent-note-target.ts       |   5 +-
 .../active-agent-terminal-send-readiness.ts   |  49 ++--
 .../store/slices/ui/ui-slice-agent-actions.ts |  13 +-
 11 files changed, 617 insertions(+), 218 deletions(-)
 create mode 100644 src/renderer/src/lib/active-agent-note-send-delivery.ts
 create mode 100644 src/renderer/src/lib/active-agent-note-send-diagnostics.ts
 create mode 100644 src/renderer/src/lib/active-agent-note-send-runtime-error-codes.test.ts

diff --git a/src/renderer/src/components/editor/ReviewNotesSendMenuContent.tsx b/src/renderer/src/components/editor/ReviewNotesSendMenuContent.tsx
index 5fbb92c7636..e0b1d70d5a2 100644
--- a/src/renderer/src/components/editor/ReviewNotesSendMenuContent.tsx
+++ b/src/renderer/src/components/editor/ReviewNotesSendMenuContent.tsx
@@ -124,17 +124,18 @@ export function ReviewNotesSendMenuContent({
 
           toast.message(
             activeAgentNotesSendFailureMessage(result.status, {
-              explicitTarget: options.explicitTarget
+              explicitTarget: options.explicitTarget,
+              code: result.code
             })
           )
         })
-        .catch((error) => {
-          console.error('Failed to send notes:', error)
+        .catch(() => {
+          console.error('Failed to send notes:', { code: 'runtime-unverifiable' })
           toast.error(
-            translate(
-              'auto.components.editor.ReviewNotesSendMenuContent.f5096c6e4e',
-              'Could not send notes.'
-            )
+            activeAgentNotesSendFailureMessage('status-unavailable', {
+              explicitTarget: options.explicitTarget,
+              code: 'runtime-unverifiable'
+            })
           )
         })
         .finally(() => {
diff --git a/src/renderer/src/lib/active-agent-note-send-delivery.ts b/src/renderer/src/lib/active-agent-note-send-delivery.ts
new file mode 100644
index 00000000000..2d9e88ae507
--- /dev/null
+++ b/src/renderer/src/lib/active-agent-note-send-delivery.ts
@@ -0,0 +1,152 @@
+import type { RuntimeTerminalSend } from '../../../shared/runtime-types'
+import { sanitizeTerminalPasteText } from '@/components/terminal-pane/terminal-bracketed-paste'
+import { callRuntimeRpc } from '@/runtime/runtime-rpc-client'
+import {
+  BRACKETED_PASTE_BEGIN,
+  BRACKETED_PASTE_END,
+  POST_PASTE_SUBMIT_DELAY_MS
+} from './agent-paste-draft'
+import type { ActiveAgentNotesSendResult } from './active-agent-note-send-result'
+import {
+  ACTIVE_AGENT_SEND_RPC_TIMEOUT_MS,
+  getTerminalAgentSendReadiness,
+  isRuntimeTerminalNotWritable,
+  isRuntimeTerminalUnavailable
+} from './active-agent-terminal-send-readiness'
+import { codeForReadinessStatus, runtimeFailureCode } from './active-agent-note-send-diagnostics'
+
+const ORCA_DESKTOP_TERMINAL_CLIENT = { id: 'orca-desktop', type: 'desktop' as const }
+
+export async function sendPromptWithLegacyCombinedSend(
+  runtimeTarget: Parameters<typeof callRuntimeRpc>[0],
+  terminalHandle: string,
+  prompt: string
+): Promise<ActiveAgentNotesSendResult> {
+  try {
+    const { send } = await callRuntimeRpc<{ send: RuntimeTerminalSend }>(
+      runtimeTarget,
+      'terminal.send',
+      { terminal: terminalHandle, text: prompt, enter: true, client: ORCA_DESKTOP_TERMINAL_CLIENT },
+      { timeoutMs: ACTIVE_AGENT_SEND_RPC_TIMEOUT_MS }
+    )
+    return send.accepted
+      ? { status: 'sent' }
+      : { status: 'not-writable', code: 'terminal-send-refused' }
+  } catch (error) {
+    if (isRuntimeTerminalUnavailable(error)) {
+      return {
+        status: 'no-active-terminal',
+        code: runtimeFailureCode(error) ?? 'runtime-unverifiable'
+      }
+    }
+    if (isRuntimeTerminalNotWritable(error)) {
+      return { status: 'not-writable', code: 'terminal_not_writable' }
+    }
+    throw error
+  }
+}
+
+export async function sendPromptWithGuardedPasteAndEnter(
+  runtimeTarget: Parameters<typeof callRuntimeRpc>[0],
+  terminalHandle: string,
+  prompt: string,
+  options: { allowLegacyFallback: boolean }
+): Promise<ActiveAgentNotesSendResult> {
+  const initialAgentStatus = await getTerminalAgentSendReadiness(
+    runtimeTarget,
+    terminalHandle,
+    options
+  )
+  if (
+    initialAgentStatus.status !== 'sendable' &&
+    !(initialAgentStatus.status === 'no-agent' && initialAgentStatus.supportsGuardedSend)
+  ) {
+    return {
+      status: initialAgentStatus.status,
+      code: initialAgentStatus.code ?? codeForReadinessStatus(initialAgentStatus.status)
+    }
+  }
+
+  const pastePayload = `${BRACKETED_PASTE_BEGIN}${sanitizeTerminalPasteText(prompt)}${BRACKETED_PASTE_END}`
+  try {
+    const { send } = await callRuntimeRpc<{ send: RuntimeTerminalSend }>(
+      runtimeTarget,
+      'terminal.send',
+      {
+        terminal: terminalHandle,
+        text: pastePayload,
+        requireAgentStatus: 'sendable',
+        client: ORCA_DESKTOP_TERMINAL_CLIENT
+      },
+      { timeoutMs: ACTIVE_AGENT_SEND_RPC_TIMEOUT_MS }
+    )
+    if (!send.accepted) {
+      if (send.refusedReason === 'permission') {
+        return { status: 'permission', code: 'terminal-send-permission' }
+      }
+      if (send.refusedReason === 'no-agent') {
+        return { status: 'no-agent', code: 'no-agent' }
+      }
+      return { status: 'not-writable', code: 'terminal-send-refused' }
+    }
+  } catch (error) {
+    if (isRuntimeTerminalUnavailable(error)) {
+      return {
+        status: 'no-active-terminal',
+        code: runtimeFailureCode(error) ?? 'runtime-unverifiable'
+      }
+    }
+    if (isRuntimeTerminalNotWritable(error)) {
+      return { status: 'not-writable', code: 'terminal_not_writable' }
+    }
+    throw error
+  }
+
+  await new Promise<void>((resolve) => setTimeout(resolve, POST_PASTE_SUBMIT_DELAY_MS))
+  try {
+    const submitAgentStatus = await getTerminalAgentSendReadiness(
+      runtimeTarget,
+      terminalHandle,
+      options
+    )
+    if (
+      submitAgentStatus.status !== 'sendable' &&
+      !(submitAgentStatus.status === 'no-agent' && submitAgentStatus.supportsGuardedSend)
+    ) {
+      return {
+        status: 'partial-submit-failed',
+        code: submitAgentStatus.code ?? 'submit-readiness-lost'
+      }
+    }
+  } catch (error) {
+    if (isRuntimeTerminalUnavailable(error)) {
+      return {
+        status: 'partial-submit-failed',
+        code: runtimeFailureCode(error) ?? 'submit-terminal-unavailable'
+      }
+    }
+    throw error
+  }
+
+  try {
+    const { send } = await callRuntimeRpc<{ send: RuntimeTerminalSend }>(
+      runtimeTarget,
+      'terminal.send',
+      {
+        terminal: terminalHandle,
+        enter: true,
+        requireAgentStatus: 'sendable',
+        client: ORCA_DESKTOP_TERMINAL_CLIENT
+      },
+      { timeoutMs: ACTIVE_AGENT_SEND_RPC_TIMEOUT_MS }
+    )
+    return send.accepted
+      ? { status: 'sent' }
+      : { status: 'partial-submit-failed', code: 'submit-send-refused' }
+  } catch (error) {
+    if (isRuntimeTerminalUnavailable(error) || isRuntimeTerminalNotWritable(error)) {
+      return { status: 'partial-submit-failed', code: 'submit-send-error' }
+    }
+    throw error
+  }
+}
diff --git a/src/renderer/src/lib/active-agent-note-send-diagnostics.ts b/src/renderer/src/lib/active-agent-note-send-diagnostics.ts
new file mode 100644
index 00000000000..155dec17e06
--- /dev/null
+++ b/src/renderer/src/lib/active-agent-note-send-diagnostics.ts
@@ -0,0 +1,82 @@
+import type { ActiveTerminalNoteTarget } from './active-agent-note-target'
+import type {
+  ActiveAgentNotesSendFailureCode,
+  ActiveAgentNotesSendResult
+} from './active-agent-note-send-result'
+import { hasRuntimeRpcErrorCode } from '../../../shared/runtime-rpc-error-code'
+
+export const TERMINAL_RUNTIME_FAILURE_CODES = [
+  'terminal_handle_stale',
+  'terminal_exited',
+  'terminal_gone',
+  'no_active_terminal'
+] as const
+
+export function reportNoteSendFailure(
+  result: ActiveAgentNotesSendResult,
+  noteTarget: ActiveTerminalNoteTarget | null
+): ActiveAgentNotesSendResult {
+  if (result.status === 'sent' || result.status === 'empty') {
+    return result
+  }
+  const code = result.code ?? codeForStatus(result.status)
+  console.warn('[review-notes] send failed', {
+    code,
+    status: result.status,
+    tabId: noteTarget?.tabId,
+    leafId: noteTarget?.leafId
+  })
+  return { ...result, code }
+}
+
+export function codeForReadinessStatus(
+  status: 'no-active-terminal' | 'no-agent' | 'permission' | 'status-unavailable'
+): ActiveAgentNotesSendFailureCode {
+  switch (status) {
+    case 'no-active-terminal':
+      return 'no-inventory-match'
+    case 'no-agent':
+      return 'no-agent'
+    case 'permission':
+      return 'agent-permission'
+    case 'status-unavailable':
+      return 'status-unavailable'
+  }
+}
+
+export function runtimeFailureCode(error: unknown): ActiveAgentNotesSendFailureCode | null {
+  return TERMINAL_RUNTIME_FAILURE_CODES.find((code) => hasRuntimeRpcErrorCode(error, code)) ?? null
+}
+
+export function runtimeFailureFallbackCode(error: unknown): ActiveAgentNotesSendFailureCode {
+  return isTimeoutError(error) ? 'runtime-timeout' : 'runtime-unverifiable'
+}
+
+function isTimeoutError(error: unknown): boolean {
+  if (hasRuntimeRpcErrorCode(error, 'runtime_timeout')) {
+    return true
+  }
+  const message = error instanceof Error ? error.message : String(error)
+  return message.includes('timeout')
+}
+
+function codeForStatus(
+  status: Exclude<ActiveAgentNotesSendResult['status'], 'sent' | 'empty'>
+): ActiveAgentNotesSendFailureCode {
+  switch (status) {
+    case 'no-active-terminal':
+      return 'no-inventory-match'
+    case 'no-agent':
+      return 'no-agent'
+    case 'permission':
+      return 'agent-permission'
+    case 'status-unavailable':
+      return 'status-unavailable'
+    case 'not-ready':
+      return 'terminal_wait_timeout'
+    case 'not-writable':
+      return 'terminal-send-refused'
+    case 'partial-submit-failed':
+      return 'submit-send-error'
+  }
+}
diff --git a/src/renderer/src/lib/active-agent-note-send-explicit-target.test.ts b/src/renderer/src/lib/active-agent-note-send-explicit-target.test.ts
index 96eb0306a40..098dd649f29 100644
--- a/src/renderer/src/lib/active-agent-note-send-explicit-target.test.ts
+++ b/src/renderer/src/lib/active-agent-note-send-explicit-target.test.ts
@@ -172,7 +172,7 @@ describe('active agent note send', () => {
         prompt: 'notes',
         noteTarget: { tabId: 'tab-9', leafId: OTHER_LEAF_ID }
       })
-    ).resolves.toEqual({ status: 'status-unavailable' })
+    ).resolves.toEqual({ status: 'status-unavailable', code: 'status-unavailable' })
 
     expect(methods).toEqual(['terminal.list', 'terminal.agentStatus'])
     expect(testState.callRuntimeRpc).not.toHaveBeenCalledWith(
@@ -275,7 +275,7 @@ describe('active agent note send', () => {
         prompt: 'notes',
         noteTarget: { tabId: 'tab-9', leafId: OTHER_LEAF_ID }
       })
-    ).resolves.toEqual({ status: 'permission' })
+    ).resolves.toEqual({ status: 'permission', code: 'agent-permission' })
 
     expect(testState.callRuntimeRpc).not.toHaveBeenCalledWith(
       expect.anything(),
@@ -359,7 +359,7 @@ describe('active agent note send', () => {
         prompt: 'notes',
         noteTarget: { tabId: 'tab-9', leafId: OTHER_LEAF_ID }
       })
-    ).resolves.toEqual({ status: 'no-agent' })
+    ).resolves.toEqual({ status: 'no-agent', code: 'no-agent' })
     expect(methods).toEqual(['terminal.list', 'terminal.agentStatus', 'terminal.send'])
   })
 
@@ -401,7 +401,7 @@ describe('active agent note send', () => {
         prompt: 'notes',
         noteTarget: { tabId: 'tab-9', leafId: OTHER_LEAF_ID }
       })
-    ).resolves.toEqual({ status: 'not-writable' })
+    ).resolves.toEqual({ status: 'not-writable', code: 'terminal-send-refused' })
 
     const sendCalls = testState.callRuntimeRpc.mock.calls.filter(
       (call) => call[1] === 'terminal.send'
@@ -454,7 +454,7 @@ describe('active agent note send', () => {
         prompt: 'notes',
         noteTarget: { tabId: 'tab-9', leafId: OTHER_LEAF_ID }
       })
-    ).resolves.toEqual({ status: 'permission' })
+    ).resolves.toEqual({ status: 'permission', code: 'terminal-send-permission' })
 
     const sendCalls = testState.callRuntimeRpc.mock.calls.filter(
       (call) => call[1] === 'terminal.send'
@@ -508,7 +508,7 @@ describe('active agent note send', () => {
         prompt: 'notes',
         noteTarget: { tabId: 'tab-9', leafId: OTHER_LEAF_ID }
       })
-    ).resolves.toEqual({ status: 'partial-submit-failed' })
+    ).resolves.toEqual({ status: 'partial-submit-failed', code: 'submit-readiness-lost' })
 
     const sendCalls = testState.callRuntimeRpc.mock.calls.filter(
       (call) => call[1] === 'terminal.send'
@@ -562,7 +562,7 @@ describe('active agent note send', () => {
         prompt: 'notes',
         noteTarget: { tabId: 'tab-9', leafId: OTHER_LEAF_ID }
       })
-    ).resolves.toEqual({ status: 'partial-submit-failed' })
+    ).resolves.toEqual({ status: 'partial-submit-failed', code: 'submit-send-refused' })
   })
 
   it('maps explicit target guarded Enter permission refusal to partial-submit-failed', async () => {
@@ -620,7 +620,7 @@ describe('active agent note send', () => {
         prompt: 'notes',
         noteTarget: { tabId: 'tab-9', leafId: OTHER_LEAF_ID }
       })
-    ).resolves.toEqual({ status: 'partial-submit-failed' })
+    ).resolves.toEqual({ status: 'partial-submit-failed', code: 'submit-send-refused' })
   })
 
   it('uses selected-target failure wording for explicit note targets', () => {
@@ -647,8 +647,90 @@ describe('active agent note send', () => {
     expect(activeAgentNotesSendFailureMessage('partial-submit-failed')).toBe(
       'The notes may already be pasted in the active terminal, but Orca could not submit them.'
     )
+    expect(
+      activeAgentNotesSendFailureMessage('no-active-terminal', {
+        explicitTarget: true,
+        code: 'no-inventory-match'
+      })
+    ).toBe('The selected terminal is no longer available. (no-inventory-match)')
   })
 
+  it.each(['terminal_handle_stale', 'terminal_exited', 'terminal_gone'] as const)(
+    'returns and logs the runtime terminal failure code %s without note contents',
+    async (runtimeCode) => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+      testState.callRuntimeRpc.mockImplementation(async (_target, method) => {
+        if (method === 'terminal.list') {
+          return {
+            terminals: [
+              {
+                handle: 'term-runtime-failure',
+                worktreeId: 'wt-1',
+                worktreePath: '/repo',
+                branch: 'main',
+                tabId: 'tab-9',
+                leafId: OTHER_LEAF_ID,
+                title: 'Codex',
+                connected: true,
+                writable: true,
+                lastOutputAt: 1,
+                preview: ''
+              }
+            ],
+            totalCount: 1,
+            truncated: false
+          }
+        }
+        if (method === 'terminal.agentStatus') {
+          throw new Error(runtimeCode)
+        }
+        throw new Error(`unexpected method ${method}`)
+      })
+
+      await expect(
+        sendNotesToActiveAgentSession({
+          worktreeId: 'wt-1',
+          prompt: 'private note contents',
+          noteTarget: { tabId: 'tab-9', leafId: OTHER_LEAF_ID }
+        })
+      ).resolves.toEqual({ status: 'no-active-terminal', code: runtimeCode })
+
+      expect(warn).toHaveBeenCalledWith('[review-notes] send failed', {
+        code: runtimeCode,
+        status: 'no-active-terminal',
+        tabId: 'tab-9',
+        leafId: OTHER_LEAF_ID
+      })
+      expect(JSON.stringify(warn.mock.calls)).not.toContain('private note contents')
+      warn.mockRestore()
+    }
+  )
+
+  it.each([
+    ['remote connection closed at /private/workspace', 'runtime-unverifiable'],
+    ['runtime request timeout', 'runtime-timeout']
+  ] as const)(
+    'classifies terminal inventory failure without logging raw error details: %s',
+    async (message, code) => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+      testState.callRuntimeRpc.mockRejectedValue(new Error(message))
+
+      await expect(
+        sendNotesToActiveAgentSession({
+          worktreeId: 'wt-1',
+          prompt: 'private note contents',
+          noteTarget: { tabId: 'tab-9', leafId: OTHER_LEAF_ID }
+        })
+      ).resolves.toEqual({ status: 'status-unavailable', code })
+
+      const logged = JSON.stringify(warn.mock.calls)
+      expect(logged).toContain(code)
+      expect(logged).not.toContain(message)
+      expect(logged).not.toContain('private note contents')
+      warn.mockRestore()
+    }
+  )
+
   it('returns no-active-terminal when the explicit note target is absent from the runtime list', async () => {
     testState.callRuntimeRpc.mockImplementation(async (_target, method) => {
       if (method === 'terminal.list') {
@@ -681,7 +763,7 @@ describe('active agent note send', () => {
         prompt: 'notes',
         noteTarget: { tabId: 'tab-1', leafId: OTHER_LEAF_ID }
       })
-    ).resolves.toEqual({ status: 'no-active-terminal' })
+    ).resolves.toEqual({ status: 'no-active-terminal', code: 'no-inventory-match' })
 
     expect(testState.callRuntimeRpc).not.toHaveBeenCalledWith(
       expect.anything(),
@@ -690,4 +772,51 @@ describe('active agent note send', () => {
       expect.anything()
     )
   })
+
+  it('matches mirrored renderer tab IDs to host runtime tab IDs', async () => {
+    testState.callRuntimeRpc.mockImplementation(async (_target, method, params) => {
+      if (method === 'terminal.list') {
+        return {
+          terminals: [
+            {
+              handle: 'term-mirrored',
+              worktreeId: 'wt-1',
+              worktreePath: '/repo',
+              branch: 'main',
+              tabId: 'tab-9',
+              leafId: OTHER_LEAF_ID,
+              title: 'Codex',
+              connected: true,
+              writable: true,
+              lastOutputAt: 1,
+              preview: ''
+            }
+          ],
+          totalCount: 1,
+          truncated: false
+        }
+      }
+      if (method === 'terminal.agentStatus') {
+        return { agentStatus: { handle: 'term-mirrored', isRunningAgent: true, status: 'working' } }
+      }
+      if (method === 'terminal.send') {
+        return {
+          send: {
+            handle: 'term-mirrored',
+            accepted: true,
+            bytesWritten: typeof params.text === 'string' ? params.text.length : 1
+          }
+        }
+      }
+      throw new Error(`unexpected method ${method}`)
+    })
+
+    await expect(
+      sendNotesToActiveAgentSession({
+        worktreeId: 'wt-1',
+        prompt: 'notes',
+        noteTarget: { tabId: 'web-terminal-tab-9', leafId: OTHER_LEAF_ID }
+      })
+    ).resolves.toEqual({ status: 'sent' })
+  })
 })
diff --git a/src/renderer/src/lib/active-agent-note-send-focused-session.test.ts b/src/renderer/src/lib/active-agent-note-send-focused-session.test.ts
index 76fcf49c4e6..118bd134df5 100644
--- a/src/renderer/src/lib/active-agent-note-send-focused-session.test.ts
+++ b/src/renderer/src/lib/active-agent-note-send-focused-session.test.ts
@@ -187,7 +187,7 @@ describe('active agent note send', () => {
 
     await expect(
       sendNotesToActiveAgentSession({ worktreeId: 'wt-1', prompt: 'notes' })
-    ).resolves.toEqual({ status: 'permission' })
+    ).resolves.toEqual({ status: 'permission', code: 'terminal-send-permission' })
   })
 
   it('keeps active-focused sends compatible when an older runtime lacks agentStatus', async () => {
@@ -286,7 +286,7 @@ describe('active agent note send', () => {
 
     await expect(
       sendNotesToActiveAgentSession({ worktreeId: 'wt-1', prompt: 'notes' })
-    ).resolves.toEqual({ status: 'no-agent' })
+    ).resolves.toEqual({ status: 'no-agent', code: 'no-agent' })
 
     expect(testState.callRuntimeRpc).not.toHaveBeenCalledWith(
       expect.anything(),
@@ -330,7 +330,7 @@ describe('active agent note send', () => {
 
     await expect(
       sendNotesToActiveAgentSession({ worktreeId: 'wt-1', prompt: 'notes' })
-    ).resolves.toEqual({ status: 'not-ready' })
+    ).resolves.toEqual({ status: 'not-ready', code: 'terminal_wait_timeout' })
 
     expect(testState.callRuntimeRpc).not.toHaveBeenCalledWith(
       expect.anything(),
@@ -382,7 +382,7 @@ describe('active agent note send', () => {
 
     await expect(
       sendNotesToActiveAgentSession({ worktreeId: 'wt-1', prompt: 'notes' })
-    ).resolves.toEqual({ status: 'no-active-terminal' })
+    ).resolves.toEqual({ status: 'no-active-terminal', code: 'terminal_wait_not_running' })
 
     expect(testState.callRuntimeRpc).not.toHaveBeenCalledWith(
       expect.anything(),
@@ -435,7 +435,7 @@ describe('active agent note send', () => {
 
     await expect(
       sendNotesToActiveAgentSession({ worktreeId: 'wt-1', prompt: 'notes' })
-    ).resolves.toEqual({ status: 'permission' })
+    ).resolves.toEqual({ status: 'permission', code: 'terminal_wait_blocked' })
 
     expect(testState.callRuntimeRpc).not.toHaveBeenCalledWith(
       expect.anything(),
@@ -495,7 +495,7 @@ describe('active agent note send', () => {
 
     await expect(
       sendNotesToActiveAgentSession({ worktreeId: 'wt-1', prompt: 'notes' })
-    ).resolves.toEqual({ status: 'permission' })
+    ).resolves.toEqual({ status: 'permission', code: 'agent-permission' })
 
     expect(statusChecks).toBe(2)
     expect(testState.callRuntimeRpc).not.toHaveBeenCalledWith(
@@ -512,7 +512,7 @@ describe('active agent note send', () => {
 
     await expect(
       sendNotesToActiveAgentSession({ worktreeId: 'wt-1', prompt: 'notes' })
-    ).resolves.toEqual({ status: 'no-active-terminal' })
+    ).resolves.toEqual({ status: 'no-active-terminal', code: 'no-note-target' })
 
     expect(testState.callRuntimeRpc).not.toHaveBeenCalled()
   })
diff --git a/src/renderer/src/lib/active-agent-note-send-result.ts b/src/renderer/src/lib/active-agent-note-send-result.ts
index 3c292d497e4..388037d7226 100644
--- a/src/renderer/src/lib/active-agent-note-send-result.ts
+++ b/src/renderer/src/lib/active-agent-note-send-result.ts
@@ -9,39 +9,76 @@ export type ActiveAgentNotesSendStatus =
   | 'not-writable'
   | 'partial-submit-failed'
 
+export type ActiveAgentNotesSendFailureCode =
+  | 'empty'
+  | 'no-note-target'
+  | 'no-inventory-match'
+  | 'terminal_handle_stale'
+  | 'terminal_exited'
+  | 'terminal_gone'
+  | 'no_active_terminal'
+  | 'terminal_wait_not_running'
+  | 'terminal_wait_blocked'
+  | 'terminal_wait_unsatisfied'
+  | 'terminal_wait_timeout'
+  | 'no-agent'
+  | 'agent-permission'
+  | 'status-unavailable'
+  | 'terminal-send-permission'
+  | 'terminal-send-refused'
+  | 'terminal_not_writable'
+  | 'submit-readiness-lost'
+  | 'submit-terminal-unavailable'
+  | 'submit-send-refused'
+  | 'submit-send-error'
+  | 'runtime-unverifiable'
+  | 'runtime-timeout'
+
 export type ActiveAgentNotesSendResult = {
   status: ActiveAgentNotesSendStatus
+  code?: ActiveAgentNotesSendFailureCode
 }
 
 export function activeAgentNotesSendFailureMessage(
   status: ActiveAgentNotesSendStatus,
-  options: { explicitTarget?: boolean } = {}
+  options: { explicitTarget?: boolean; code?: ActiveAgentNotesSendFailureCode } = {}
 ): string {
   const target = options.explicitTarget ? 'selected' : 'active'
+  let message: string
   switch (status) {
     case 'empty':
-      return 'No notes to send.'
+      message = 'No notes to send.'
+      break
     case 'no-active-terminal':
-      return options.explicitTarget
+      message = options.explicitTarget
         ? 'The selected terminal is no longer available.'
         : 'Open the agent terminal in this worktree, then send the notes again.'
+      break
     case 'no-agent':
-      return `The ${target} terminal is not a recognized agent session.`
+      message = `The ${target} terminal is not a recognized agent session.`
+      break
     case 'permission':
-      return options.explicitTarget
+      message = options.explicitTarget
         ? 'The selected agent needs permission.'
         : 'The active agent needs permission.'
+      break
     case 'status-unavailable':
-      return `The ${target} agent status could not be verified.`
+      message = `The ${target} agent status could not be verified.`
+      break
     case 'not-ready':
-      return `The ${target} agent was not ready for input yet.`
+      message = `The ${target} agent was not ready for input yet.`
+      break
     case 'not-writable':
-      return `The ${target} terminal did not accept the notes.`
+      message = `The ${target} terminal did not accept the notes.`
+      break
     case 'partial-submit-failed':
-      return options.explicitTarget
+      message = options.explicitTarget
         ? 'The notes may already be pasted in the selected terminal, but Orca could not submit them.'
         : 'The notes may already be pasted in the active terminal, but Orca could not submit them.'
+      break
     case 'sent':
-      return ''
+      message = ''
+      break
   }
+  return options.code ? `${message} (${options.code})` : message
 }
diff --git a/src/renderer/src/lib/active-agent-note-send-runtime-error-codes.test.ts b/src/renderer/src/lib/active-agent-note-send-runtime-error-codes.test.ts
new file mode 100644
index 00000000000..baa41a7d139
--- /dev/null
+++ b/src/renderer/src/lib/active-agent-note-send-runtime-error-codes.test.ts
@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest'
+import { hasRuntimeRpcErrorCode, RuntimeRpcCallError } from '@/runtime/runtime-rpc-client'
+import {
+  isRuntimeTerminalNotWritable,
+  isRuntimeTerminalUnavailable,
+  isRuntimeTimeout
+} from './active-agent-terminal-send-readiness'
+import {
+  runtimeFailureCode,
+  runtimeFailureFallbackCode
+} from './active-agent-note-send-diagnostics'
+
+function runtimeError(code: string): RuntimeRpcCallError {
+  return new RuntimeRpcCallError({
+    id: 'test-runtime-error',
+    ok: false,
+    error: { code, message: 'The terminal is no longer available' }
+  })
+}
+
+describe('active agent note runtime error codes', () => {
+  it.each(['terminal_handle_stale', 'terminal_exited', 'terminal_gone', 'no_active_terminal'])(
+    'uses structured %s codes even with human-readable messages',
+    (code) => {
+      const error = runtimeError(code)
+
+      expect(isRuntimeTerminalUnavailable(error)).toBe(true)
+      expect(runtimeFailureCode(error)).toBe(code)
+    }
+  )
+
+  it('uses structured terminal_not_writable with a human-readable message', () => {
+    const error = runtimeError('terminal_not_writable')
+
+    expect(isRuntimeTerminalNotWritable(error)).toBe(true)
+    expect(hasRuntimeRpcErrorCode(error, 'terminal_not_writable')).toBe(true)
+  })
+
+  it('uses structured runtime_timeout with a human-readable message', () => {
+    const error = new RuntimeRpcCallError({
+      id: 'test-runtime-timeout',
+      ok: false,
+      error: { code: 'runtime_timeout', message: 'Timed out waiting for the remote runtime.' }
+    })
+
+    expect(isRuntimeTimeout(error)).toBe(true)
+    expect(runtimeFailureFallbackCode(error)).toBe('runtime-timeout')
+  })
+
+  it('retains support for transport-rewrapped error tokens', () => {
+    const error = new Error("Error invoking remote method 'terminal.send': terminal_gone")
+
+    expect(isRuntimeTerminalUnavailable(error)).toBe(true)
+    expect(runtimeFailureCode(error)).toBe('terminal_gone')
+  })
+})
diff --git a/src/renderer/src/lib/active-agent-note-send.ts b/src/renderer/src/lib/active-agent-note-send.ts
index 97bb2418132..48cced68feb 100644
--- a/src/renderer/src/lib/active-agent-note-send.ts
+++ b/src/renderer/src/lib/active-agent-note-send.ts
@@ -1,26 +1,26 @@
-import type { RuntimeTerminalSend, RuntimeTerminalWait } from '../../../shared/runtime-types'
-import { sanitizeTerminalPasteText } from '@/components/terminal-pane/terminal-bracketed-paste'
+import type { RuntimeTerminalWait } from '../../../shared/runtime-types'
 import { useAppStore } from '@/store'
 import { callRuntimeRpc, getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
 import { getSettingsForWorktreeRuntimeOwner } from '@/lib/worktree-runtime-owner'
-import {
-  findActiveRuntimeTerminal,
-  getActiveTerminalNoteTarget,
-  type ActiveTerminalNoteTarget
-} from './active-agent-note-target'
-import {
-  BRACKETED_PASTE_BEGIN,
-  BRACKETED_PASTE_END,
-  POST_PASTE_SUBMIT_DELAY_MS
-} from './agent-paste-draft'
+import { findActiveRuntimeTerminal, getActiveTerminalNoteTarget } from './active-agent-note-target'
+import type { ActiveTerminalNoteTarget } from './active-agent-note-target'
 import type { ActiveAgentNotesSendResult } from './active-agent-note-send-result'
 import {
   ACTIVE_AGENT_SEND_RPC_TIMEOUT_MS,
   getTerminalAgentSendReadiness,
-  isRuntimeTerminalNotWritable,
   isRuntimeTerminalUnavailable,
   isRuntimeTimeout
 } from './active-agent-terminal-send-readiness'
+import {
+  codeForReadinessStatus,
+  reportNoteSendFailure,
+  runtimeFailureCode,
+  runtimeFailureFallbackCode
+} from './active-agent-note-send-diagnostics'
+import {
+  sendPromptWithGuardedPasteAndEnter,
+  sendPromptWithLegacyCombinedSend
+} from './active-agent-note-send-delivery'
 
 export {
   getActiveAgentNoteTarget,
@@ -34,11 +34,24 @@ export {
   type ActiveAgentNotesSendResult,
   type ActiveAgentNotesSendStatus
 } from './active-agent-note-send-result'
-
 const ACTIVE_AGENT_SEND_TIMEOUT_MS = 8000
-const ORCA_DESKTOP_TERMINAL_CLIENT = { id: 'orca-desktop', type: 'desktop' as const }
 
-export async function sendNotesToActiveAgentSession({
+export async function sendNotesToActiveAgentSession(args: {
+  worktreeId: string
+  prompt: string
+  noteTarget?: ActiveTerminalNoteTarget
+  timeoutMs?: number
+}): Promise<ActiveAgentNotesSendResult> {
+  try {
+    return await sendNotesToActiveAgentSessionInternal(args)
+  } catch (error) {
+    return reportNoteSendFailure(
+      { status: 'status-unavailable', code: runtimeFailureFallbackCode(error) },
+      args.noteTarget ?? null
+    )
+  }
+}
+async function sendNotesToActiveAgentSessionInternal({
   worktreeId,
   prompt,
   noteTarget: explicitNoteTarget,
@@ -51,20 +64,13 @@ export async function sendNotesToActiveAgentSession({
 }): Promise<ActiveAgentNotesSendResult> {
   const trimmedPrompt = prompt.trim()
   if (!trimmedPrompt) {
-    return { status: 'empty' }
+    return { status: 'empty', code: 'empty' }
   }
-
   const state = useAppStore.getState()
-  // Why: an explicit target lets the notes dropdown address ANY running agent of
-  // the worktree, not just the focused pane; omitted, fall back to the focused
-  // active terminal so existing callers keep their behavior. Routing below still
-  // resolves the worktree's owner host, so explicit targets stay SSH/remote-correct.
   const noteTarget = explicitNoteTarget ?? getActiveTerminalNoteTarget(state, worktreeId)
   if (!noteTarget) {
-    return { status: 'no-active-terminal' }
+    return reportNoteSendFailure({ status: 'no-active-terminal', code: 'no-note-target' }, null)
   }
-  // Route by the worktree's owner host so the agent terminal is found and driven
-  // on the host that actually runs it, not on the focused runtime.
   const runtimeTarget = getActiveRuntimeTarget(
     getSettingsForWorktreeRuntimeOwner(state, worktreeId)
   )
@@ -75,21 +81,30 @@ export async function sendNotesToActiveAgentSession({
     ACTIVE_AGENT_SEND_RPC_TIMEOUT_MS
   )
   if (!terminal) {
-    return { status: 'no-active-terminal' }
+    return reportNoteSendFailure(
+      { status: 'no-active-terminal', code: 'no-inventory-match' },
+      noteTarget
+    )
   }
-
   if (explicitNoteTarget) {
-    return await sendPromptToExplicitAgentTarget(runtimeTarget, terminal.handle, trimmedPrompt)
+    return reportNoteSendFailure(
+      await sendPromptToExplicitAgentTarget(runtimeTarget, terminal.handle, trimmedPrompt),
+      noteTarget
+    )
   }
-
   const effectiveTimeoutMs = timeoutMs ?? ACTIVE_AGENT_SEND_TIMEOUT_MS
   const initialAgentStatus = await getTerminalAgentSendReadiness(runtimeTarget, terminal.handle, {
     allowLegacyFallback: true
   })
   if (initialAgentStatus.status !== 'sendable') {
-    return { status: initialAgentStatus.status }
+    return reportNoteSendFailure(
+      {
+        status: initialAgentStatus.status,
+        code: initialAgentStatus.code ?? codeForReadinessStatus(initialAgentStatus.status)
+      },
+      noteTarget
+    )
   }
-
   try {
     const { wait } = await callRuntimeRpc<{ wait: RuntimeTerminalWait }>(
       runtimeTarget,
@@ -98,160 +113,64 @@ export async function sendNotesToActiveAgentSession({
       { timeoutMs: effectiveTimeoutMs + 5000 }
     )
     if (wait.status !== 'running') {
-      return { status: 'no-active-terminal' }
+      return reportNoteSendFailure(
+        { status: 'no-active-terminal', code: 'terminal_wait_not_running' },
+        noteTarget
+      )
     }
     if (wait.blockedReason) {
-      return { status: 'permission' }
+      return reportNoteSendFailure(
+        { status: 'permission', code: 'terminal_wait_blocked' },
+        noteTarget
+      )
     }
     if (!wait.satisfied) {
-      return { status: 'not-ready' }
+      return reportNoteSendFailure(
+        { status: 'not-ready', code: 'terminal_wait_unsatisfied' },
+        noteTarget
+      )
     }
   } catch (error) {
     if (isRuntimeTerminalUnavailable(error)) {
-      return { status: 'no-active-terminal' }
+      return reportNoteSendFailure(
+        { status: 'no-active-terminal', code: runtimeFailureCode(error) ?? 'runtime-unverifiable' },
+        noteTarget
+      )
     }
     if (isRuntimeTimeout(error)) {
-      return { status: 'not-ready' }
+      return reportNoteSendFailure(
+        { status: 'not-ready', code: 'terminal_wait_timeout' },
+        noteTarget
+      )
     }
     throw error
   }
-
   const finalAgentStatus = await getTerminalAgentSendReadiness(runtimeTarget, terminal.handle, {
     allowLegacyFallback: true
   })
   if (finalAgentStatus.status !== 'sendable') {
-    return { status: finalAgentStatus.status }
+    return reportNoteSendFailure(
+      {
+        status: finalAgentStatus.status,
+        code: finalAgentStatus.code ?? codeForReadinessStatus(finalAgentStatus.status)
+      },
+      noteTarget
+    )
   }
 
   if (finalAgentStatus.supportsGuardedSend) {
-    return await sendPromptWithGuardedPasteAndEnter(runtimeTarget, terminal.handle, trimmedPrompt, {
-      allowLegacyFallback: false
-    })
-  }
-
-  // Why: protocol-compatible older SSH runtimes do not know the guarded send
-  // option. They already passed terminal.wait + legacy isRunningAgent checks,
-  // so preserve the old active-focused send path for remote compatibility.
-  return await sendPromptWithLegacyCombinedSend(runtimeTarget, terminal.handle, trimmedPrompt)
-}
-
-async function sendPromptWithLegacyCombinedSend(
-  runtimeTarget: ReturnType<typeof getActiveRuntimeTarget>,
-  terminalHandle: string,
-  prompt: string
-): Promise<ActiveAgentNotesSendResult> {
-  try {
-    const { send } = await callRuntimeRpc<{ send: RuntimeTerminalSend }>(
-      runtimeTarget,
-      'terminal.send',
-      {
-        terminal: terminalHandle,
-        text: prompt,
-        enter: true,
-        client: ORCA_DESKTOP_TERMINAL_CLIENT
-      },
-      { timeoutMs: ACTIVE_AGENT_SEND_RPC_TIMEOUT_MS }
+    return reportNoteSendFailure(
+      await sendPromptWithGuardedPasteAndEnter(runtimeTarget, terminal.handle, trimmedPrompt, {
+        allowLegacyFallback: false
+      }),
+      noteTarget
     )
-    return send.accepted ? { status: 'sent' } : { status: 'not-writable' }
-  } catch (error) {
-    if (isRuntimeTerminalUnavailable(error)) {
-      return { status: 'no-active-terminal' }
-    }
-    if (isRuntimeTerminalNotWritable(error)) {
-      return { status: 'not-writable' }
-    }
-    throw error
-  }
-}
-
-async function sendPromptWithGuardedPasteAndEnter(
-  runtimeTarget: ReturnType<typeof getActiveRuntimeTarget>,
-  terminalHandle: string,
-  prompt: string,
-  options: { allowLegacyFallback: boolean }
-): Promise<ActiveAgentNotesSendResult> {
-  const initialAgentStatus = await getTerminalAgentSendReadiness(runtimeTarget, terminalHandle, {
-    allowLegacyFallback: options.allowLegacyFallback
-  })
-  // Why: the readiness probe and write guard can observe different transient
-  // title/process snapshots; the guard owns the bounded no-agent recheck.
-  if (
-    initialAgentStatus.status !== 'sendable' &&
-    !(initialAgentStatus.status === 'no-agent' && initialAgentStatus.supportsGuardedSend)
-  ) {
-    return { status: initialAgentStatus.status }
   }
 
-  const pastePayload = `${BRACKETED_PASTE_BEGIN}${sanitizeTerminalPasteText(prompt)}${BRACKETED_PASTE_END}`
-  try {
-    const { send } = await callRuntimeRpc<{ send: RuntimeTerminalSend }>(
-      runtimeTarget,
-      'terminal.send',
-      {
-        terminal: terminalHandle,
-        text: pastePayload,
-        requireAgentStatus: 'sendable',
-        client: ORCA_DESKTOP_TERMINAL_CLIENT
-      },
-      { timeoutMs: ACTIVE_AGENT_SEND_RPC_TIMEOUT_MS }
-    )
-    if (!send.accepted) {
-      if (send.refusedReason === 'permission') {
-        return { status: 'permission' }
-      }
-      if (send.refusedReason === 'no-agent') {
-        return { status: 'no-agent' }
-      }
-      return { status: 'not-writable' }
-    }
-  } catch (error) {
-    if (isRuntimeTerminalUnavailable(error)) {
-      return { status: 'no-active-terminal' }
-    }
-    if (isRuntimeTerminalNotWritable(error)) {
-      return { status: 'not-writable' }
-    }
-    throw error
-  }
-
-  await new Promise<void>((resolve) => setTimeout(resolve, POST_PASTE_SUBMIT_DELAY_MS))
-
-  try {
-    const submitAgentStatus = await getTerminalAgentSendReadiness(runtimeTarget, terminalHandle, {
-      allowLegacyFallback: options.allowLegacyFallback
-    })
-    if (
-      submitAgentStatus.status !== 'sendable' &&
-      !(submitAgentStatus.status === 'no-agent' && submitAgentStatus.supportsGuardedSend)
-    ) {
-      return { status: 'partial-submit-failed' }
-    }
-  } catch (error) {
-    if (isRuntimeTerminalUnavailable(error)) {
-      return { status: 'partial-submit-failed' }
-    }
-    throw error
-  }
-
-  try {
-    const { send } = await callRuntimeRpc<{ send: RuntimeTerminalSend }>(
-      runtimeTarget,
-      'terminal.send',
-      {
-        terminal: terminalHandle,
-        enter: true,
-        requireAgentStatus: 'sendable',
-        client: ORCA_DESKTOP_TERMINAL_CLIENT
-      },
-      { timeoutMs: ACTIVE_AGENT_SEND_RPC_TIMEOUT_MS }
-    )
-    return send.accepted ? { status: 'sent' } : { status: 'partial-submit-failed' }
-  } catch (error) {
-    if (isRuntimeTerminalUnavailable(error) || isRuntimeTerminalNotWritable(error)) {
-      return { status: 'partial-submit-failed' }
-    }
-    throw error
-  }
+  return reportNoteSendFailure(
+    await sendPromptWithLegacyCombinedSend(runtimeTarget, terminal.handle, trimmedPrompt),
+    noteTarget
+  )
 }
 
 async function sendPromptToExplicitAgentTarget(
diff --git a/src/renderer/src/lib/active-agent-note-target.ts b/src/renderer/src/lib/active-agent-note-target.ts
index dbacc97e4c1..2b114166d1f 100644
--- a/src/renderer/src/lib/active-agent-note-target.ts
+++ b/src/renderer/src/lib/active-agent-note-target.ts
@@ -1,4 +1,5 @@
 import type { RuntimeTerminalListResult } from '../../../shared/runtime-types'
+import { toHostSessionTabId } from '../../../shared/terminal-surface-id'
 import {
   AGENT_STATUS_STALE_AFTER_MS,
   type AgentStatusEntry
@@ -174,9 +175,11 @@ export async function findActiveRuntimeTerminal(
     },
     { timeoutMs }
   )
+  // Why: paired renderer tabs wrap the host id with `web-terminal-*`.
+  const runtimeTabId = toHostSessionTabId(noteTarget.tabId)
   return (
     terminals.find(
-      (terminal) => terminal.tabId === noteTarget.tabId && terminal.leafId === noteTarget.leafId
+      (terminal) => terminal.tabId === runtimeTabId && terminal.leafId === noteTarget.leafId
     ) ?? null
   )
 }
diff --git a/src/renderer/src/lib/active-agent-terminal-send-readiness.ts b/src/renderer/src/lib/active-agent-terminal-send-readiness.ts
index fa049398e8b..b432366527f 100644
--- a/src/renderer/src/lib/active-agent-terminal-send-readiness.ts
+++ b/src/renderer/src/lib/active-agent-terminal-send-readiness.ts
@@ -1,6 +1,12 @@
 import type { RuntimeTerminalAgentStatus } from '../../../shared/runtime-types'
+import { hasRuntimeRpcErrorCode } from '../../../shared/runtime-rpc-error-code'
+import type { ActiveAgentNotesSendFailureCode } from './active-agent-note-send-result'
 import { callRuntimeRpc, RuntimeRpcCallError } from '@/runtime/runtime-rpc-client'
 import type { getActiveRuntimeTarget } from '@/runtime/runtime-rpc-client'
+import {
+  runtimeFailureCode,
+  TERMINAL_RUNTIME_FAILURE_CODES
+} from './active-agent-note-send-diagnostics'
 
 export const ACTIVE_AGENT_SEND_RPC_TIMEOUT_MS = 15000
 
@@ -14,6 +20,7 @@ export type TerminalAgentSendReadiness =
 export type TerminalAgentSendReadinessResult = {
   status: TerminalAgentSendReadiness
   supportsGuardedSend: boolean
+  code?: ActiveAgentNotesSendFailureCode
 }
 
 export async function getTerminalAgentSendReadiness(
@@ -44,13 +51,14 @@ export async function getTerminalAgentSendReadiness(
       }
       // Why: active-focused sends still wait for tui-idle, preserving old
       // runtime compatibility without immediate selected-target risk.
-      return {
-        status: await getLegacyTerminalAgentSendStatus(runtimeTarget, terminalHandle),
-        supportsGuardedSend: false
-      }
+      return await getLegacyTerminalAgentSendStatus(runtimeTarget, terminalHandle)
     }
     if (isRuntimeTerminalUnavailable(error)) {
-      return { status: 'no-active-terminal', supportsGuardedSend: false }
+      return {
+        status: 'no-active-terminal',
+        supportsGuardedSend: false,
+        code: runtimeTerminalUnavailableCode(error)
+      }
     }
     throw error
   }
@@ -59,7 +67,7 @@ export async function getTerminalAgentSendReadiness(
 async function getLegacyTerminalAgentSendStatus(
   runtimeTarget: ReturnType<typeof getActiveRuntimeTarget>,
   terminalHandle: string
-): Promise<TerminalAgentSendReadiness> {
+): Promise<TerminalAgentSendReadinessResult> {
   try {
     const { isRunningAgent } = await callRuntimeRpc<{ isRunningAgent: boolean }>(
       runtimeTarget,
@@ -67,31 +75,38 @@ async function getLegacyTerminalAgentSendStatus(
       { terminal: terminalHandle },
       { timeoutMs: ACTIVE_AGENT_SEND_RPC_TIMEOUT_MS }
     )
-    return isRunningAgent ? 'sendable' : 'no-agent'
+    return {
+      status: isRunningAgent ? 'sendable' : 'no-agent',
+      supportsGuardedSend: false
+    }
   } catch (error) {
     if (isRuntimeTerminalUnavailable(error)) {
-      return 'no-active-terminal'
+      return {
+        status: 'no-active-terminal',
+        supportsGuardedSend: false,
+        code: runtimeTerminalUnavailableCode(error)
+      }
     }
     throw error
   }
 }
 
+function runtimeTerminalUnavailableCode(error: unknown): ActiveAgentNotesSendFailureCode {
+  return runtimeFailureCode(error) ?? 'runtime-unverifiable'
+}
+
 export function isRuntimeTimeout(error: unknown): boolean {
+  if (hasRuntimeRpcErrorCode(error, 'runtime_timeout')) {
+    return true
+  }
   const message = error instanceof Error ? error.message : String(error)
   return message.includes('timeout')
 }
 
 export function isRuntimeTerminalUnavailable(error: unknown): boolean {
-  const message = error instanceof Error ? error.message : String(error)
-  return (
-    message.includes('terminal_handle_stale') ||
-    message.includes('terminal_exited') ||
-    message.includes('terminal_gone') ||
-    message.includes('no_active_terminal')
-  )
+  return TERMINAL_RUNTIME_FAILURE_CODES.some((code) => hasRuntimeRpcErrorCode(error, code))
 }
 
 export function isRuntimeTerminalNotWritable(error: unknown): boolean {
-  const message = error instanceof Error ? error.message : String(error)
-  return message.includes('terminal_not_writable')
+  return hasRuntimeRpcErrorCode(error, 'terminal_not_writable')
 }
diff --git a/src/renderer/src/store/slices/ui/ui-slice-agent-actions.ts b/src/renderer/src/store/slices/ui/ui-slice-agent-actions.ts
index 9fa15ffb81e..ebd0f016b3f 100644
--- a/src/renderer/src/store/slices/ui/ui-slice-agent-actions.ts
+++ b/src/renderer/src/store/slices/ui/ui-slice-agent-actions.ts
@@ -149,9 +149,11 @@ export function createUiAgentActions(
         worktreeId: mode.worktreeId,
         prompt: mode.prompt,
         noteTarget: { tabId: target.tabId, leafId: target.leafId }
-      }).catch((error) => {
-        console.error('Failed to send notes to sidebar agent target:', error)
-        return { status: 'no-active-terminal' as const }
+      }).catch(() => {
+        console.error('Failed to send notes to sidebar agent target:', {
+          code: 'runtime-unverifiable'
+        })
+        return { status: 'status-unavailable' as const, code: 'runtime-unverifiable' as const }
       })
 
       const stillCurrent = (): boolean => {
@@ -160,7 +162,10 @@ export function createUiAgentActions(
       }
 
       if (result.status !== 'sent') {
-        const message = activeAgentNotesSendFailureMessage(result.status, { explicitTarget: true })
+        const message = activeAgentNotesSendFailureMessage(result.status, {
+          explicitTarget: true,
+          code: result.code
+        })
         set((s) =>
           s.agentSendPopoverTargetMode?.id === mode.id &&
           s.agentSendPopoverTargetMode.instanceId === mode.instanceId

From 3f5c54332d8832ca2ed54a93d323e7f5a019f909 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Tue, 1 Sep 2026 03:00:52 -0700
Subject: [PATCH 20/32] fix(github-project): sort and group empty field values
 last in both directions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

compareSort early-returned 1 for a missing value — before the trailing
DESC flip — but expressed the same idea as `cmp = 1` for an empty
users/labels list, which that line then negated. Descending order
therefore scattered empty cells across both ends of the table.
getFieldValueForGrouping had the matching defect: an empty list fell
through to deriveStringValue and produced a blank-label group that the
header renders as the literal "All".

Both paths now share one predicate, which also covers `text: ''` and
`date: ''` — reachable because the view normalizer maps a null GitHub
text/date to the empty string.

Co-authored-by: kaluli123123 <295758798+kaluli123123@users.noreply.github.com>
---
 .../github-project/group-sort.test.ts         | 106 ++++++++++++++++++
 src/shared/github/project-group-sort.ts       |  62 +++++-----
 2 files changed, 137 insertions(+), 31 deletions(-)

diff --git a/src/renderer/src/components/github-project/group-sort.test.ts b/src/renderer/src/components/github-project/group-sort.test.ts
index cd5e77738bc..57b96267bae 100644
--- a/src/renderer/src/components/github-project/group-sort.test.ts
+++ b/src/renderer/src/components/github-project/group-sort.test.ts
@@ -33,6 +33,27 @@ const iterationField: GitHubProjectField = {
   ]
 }
 
+const assigneesField: GitHubProjectField = {
+  kind: 'field',
+  id: 'F_assignees',
+  name: 'Assignees',
+  dataType: 'ASSIGNEES'
+}
+
+const labelsField: GitHubProjectField = {
+  kind: 'field',
+  id: 'F_labels',
+  name: 'Labels',
+  dataType: 'LABELS'
+}
+
+const textField: GitHubProjectField = {
+  kind: 'field',
+  id: 'F_text',
+  name: 'Notes',
+  dataType: 'TEXT'
+}
+
 function makeRow(
   id: string,
   position: number,
@@ -206,6 +227,66 @@ describe('sortRows', () => {
     expect(sorted.map((r) => r.id)).toEqual(['rHas', 'rEmpty'])
   })
 
+  it('sorts an empty user list last in both directions, like a missing value', () => {
+    // Why: the DESC flip negated the empty branch, sending unassigned rows to the top.
+    const rows = [
+      makeRow('empty-list', 0, {
+        F_assignees: { kind: 'users', fieldId: 'F_assignees', users: [] }
+      }),
+      makeRow('alice', 1, {
+        F_assignees: {
+          kind: 'users',
+          fieldId: 'F_assignees',
+          users: [{ login: 'alice', name: null, avatarUrl: null }]
+        }
+      }),
+      makeRow('no-value', 2, {})
+    ]
+
+    for (const direction of ['ASC', 'DESC'] as const) {
+      const view = makeView(assigneesField, { direction, field: assigneesField })
+      const sorted = sortRows(makeTable(view, rows), rows)
+      expect(sorted.map((r) => r.id)).toEqual(['alice', 'empty-list', 'no-value'])
+    }
+  })
+
+  it('sorts an empty label list last in both directions, like a missing value', () => {
+    const rows = [
+      makeRow('empty-list', 0, {
+        F_labels: { kind: 'labels', fieldId: 'F_labels', labels: [] }
+      }),
+      makeRow('bug', 1, {
+        F_labels: {
+          kind: 'labels',
+          fieldId: 'F_labels',
+          labels: [{ name: 'bug', color: 'ff0000' }]
+        }
+      }),
+      makeRow('no-value', 2, {})
+    ]
+
+    for (const direction of ['ASC', 'DESC'] as const) {
+      const view = makeView(labelsField, { direction, field: labelsField })
+      const sorted = sortRows(makeTable(view, rows), rows)
+      expect(sorted.map((r) => r.id)).toEqual(['bug', 'empty-list', 'no-value'])
+    }
+  })
+
+  it('sorts a blank text value last in both directions, like a missing value', () => {
+    // Why reachable: the normalizer turns a null GitHub text/date into ''.
+    const rows = [
+      makeRow('blank', 0, { F_text: { kind: 'text', fieldId: 'F_text', text: '' } }),
+      makeRow('alpha', 1, { F_text: { kind: 'text', fieldId: 'F_text', text: 'alpha' } }),
+      makeRow('no-value', 2, {})
+    ]
+
+    for (const direction of ['ASC', 'DESC'] as const) {
+      const view = makeView(textField, { direction, field: textField })
+      const sorted = sortRows(makeTable(view, rows), rows)
+      expect(sorted.map((r) => r.id)).toEqual(['alpha', 'blank', 'no-value'])
+    }
+  })
+
   it('keeps sort fallback finite when row positions are absent', () => {
     const view = makeView(singleSelectField)
     const rows = [
@@ -220,6 +301,31 @@ describe('sortRows', () => {
 })
 
 describe('groupRows', () => {
+  it('groups a present-but-empty user list with the missing-value rows', () => {
+    // Why: an empty list fell through to a blank-label group, which renders as "All".
+    const view = { ...makeView(assigneesField), groupByFields: [assigneesField] }
+    const rows = [
+      makeRow('empty-list', 0, {
+        F_assignees: { kind: 'users', fieldId: 'F_assignees', users: [] }
+      }),
+      makeRow('alice', 1, {
+        F_assignees: {
+          kind: 'users',
+          fieldId: 'F_assignees',
+          users: [{ login: 'alice', name: null, avatarUrl: null }]
+        }
+      }),
+      makeRow('no-value', 2, {})
+    ]
+
+    const groups = groupRows(makeTable(view, rows), rows)
+
+    expect(groups.map((group) => [group.label, group.rows.map((r) => r.id)])).toEqual([
+      ['alice', ['alice']],
+      ['No Assignees', ['empty-list', 'no-value']]
+    ])
+  })
+
   it('places the empty group last', () => {
     const view = {
       ...makeView(singleSelectField),
diff --git a/src/shared/github/project-group-sort.ts b/src/shared/github/project-group-sort.ts
index 707fbfb35e4..0b91d92b267 100644
--- a/src/shared/github/project-group-sort.ts
+++ b/src/shared/github/project-group-sort.ts
@@ -24,6 +24,29 @@ export type ProjectGroup = {
 
 const EMPTY_GROUP_KEY = '__empty__'
 
+type ProjectFieldValue = GitHubProjectRow['fieldValuesByFieldId'][string]
+
+/** False for anything that renders as an empty cell — absent, or present with a blank payload. */
+function hasNonEmptyFieldValue(value: ProjectFieldValue | undefined): boolean {
+  if (!value) {
+    return false
+  }
+  switch (value.kind) {
+    case 'users':
+      return Boolean(value.users[0]?.login)
+    case 'labels':
+      return Boolean(value.labels[0]?.name)
+    case 'text':
+      return value.text.trim().length > 0
+    case 'date':
+      return value.date.trim().length > 0
+    case 'iteration':
+    case 'number':
+    case 'single-select':
+      return true
+  }
+}
+
 // Why: use a finite sentinel instead of Infinity so subtractions in the sort
 // comparator stay finite. `Infinity - Infinity` is NaN, which makes
 // Array.sort's behavior implementation-defined and skips later tie-breaks.
@@ -35,7 +58,7 @@ function getFieldValueForGrouping(
   field: GitHubProjectField
 ): { key: string; label: string; orderHint: number; iteration: ProjectGroup['iteration'] } {
   const value = row.fieldValuesByFieldId[field.id]
-  if (!value) {
+  if (!hasNonEmptyFieldValue(value)) {
     return {
       key: EMPTY_GROUP_KEY,
       label: labelForEmpty(field),
@@ -144,14 +167,11 @@ function compareSort(a: GitHubProjectRow, b: GitHubProjectRow, sort: GitHubProje
   const field = sort.field
   const aValue = a.fieldValuesByFieldId[field.id]
   const bValue = b.fieldValuesByFieldId[field.id]
-  if (!aValue && !bValue) {
-    return 0
-  }
-  if (!aValue) {
-    return 1
-  }
-  if (!bValue) {
-    return -1
+  // Why: return before the trailing DESC flip so empty sorts last in both directions.
+  const aFilled = hasNonEmptyFieldValue(aValue)
+  const bFilled = hasNonEmptyFieldValue(bValue)
+  if (!aFilled || !bFilled) {
+    return aFilled === bFilled ? 0 : aFilled ? -1 : 1
   }
 
   let cmp = 0
@@ -182,29 +202,9 @@ function compareSort(a: GitHubProjectRow, b: GitHubProjectRow, sort: GitHubProje
   } else if (aValue.kind === 'text' && bValue.kind === 'text') {
     cmp = aValue.text.localeCompare(bValue.text)
   } else if (aValue.kind === 'users' && bValue.kind === 'users') {
-    const aLogin = aValue.users[0]?.login ?? ''
-    const bLogin = bValue.users[0]?.login ?? ''
-    if (!aLogin && !bLogin) {
-      cmp = 0
-    } else if (!aLogin) {
-      cmp = 1
-    } else if (!bLogin) {
-      cmp = -1
-    } else {
-      cmp = aLogin.localeCompare(bLogin)
-    }
+    cmp = (aValue.users[0]?.login ?? '').localeCompare(bValue.users[0]?.login ?? '')
   } else if (aValue.kind === 'labels' && bValue.kind === 'labels') {
-    const aName = aValue.labels[0]?.name ?? ''
-    const bName = bValue.labels[0]?.name ?? ''
-    if (!aName && !bName) {
-      cmp = 0
-    } else if (!aName) {
-      cmp = 1
-    } else if (!bName) {
-      cmp = -1
-    } else {
-      cmp = aName.localeCompare(bName)
-    }
+    cmp = (aValue.labels[0]?.name ?? '').localeCompare(bValue.labels[0]?.name ?? '')
   } else {
     // Why: unknown sort-field kind — ignore this sort field and fall through
     // to tie-breaks (and eventually row.position).

From e89321192aebbd1ad842d2c5bb5a94a46b6d332b Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Tue, 1 Sep 2026 19:01:59 -0700
Subject: [PATCH 21/32] perf(worktree): batch remote conflict probes, re-arm
 the prepared checkout (#17829)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* perf(worktree): batch remote conflict probes, re-arm the prepared checkout

A repo with many remotes paid one `git show-ref --verify` subprocess per
remote on every branch-conflict check during create. Ask one
`git cat-file --batch-check` over stdin instead; it reports a missing ref
as data rather than a failed exit, so a batch stays as decidable as the
per-ref probe. Hosts that cannot feed stdin, and undecided batches, still
fall back to the per-ref path.

The prepared checkout was single-use, so the second create in a row paid
the full cold `git worktree add`. Re-arm it in the background after one is
consumed; the existing TTL and preparation limit still bound it.

The create timing recorder existed but its phases were never emitted and
did not cover preflight, leaving a multi-second gap in the trace with no
attribution. Add `resolve_name`/`prepare_push_target` phases and record the
breakdown, plus the unattributed remainder, on the create span.

* fix(worktree): format the conflicting review number eagerly for the create error

* perf(worktree): re-arm a prepared checkout only for a burst of creates

Re-arming after every consumed preparation spends a full checkout and
~200MB of disk on a user who created one worktree and stopped, then pays
an unexplained delete when the TTL expires five minutes later. Track when
each preparation key was last consumed and only replace it when a second
create lands inside the burst window, so the warm second create is still
free and an isolated create costs nothing.

* fix(worktree): address review findings on the create-path batching

Three findings from PR review:

The `batched.found` fallback in the remote-conflict probe was unreachable
— a present ref is decisive, so `found` never survives with `unknown`
set, and the guard above already returns that case.

`rearmPreparation` checked for an existing preparation before recording
the consume, so a prefetch that re-armed the key while create finalized
swallowed the timestamp and made the next create look isolated when it
was really mid-burst.

Create runs some phases concurrently, so summing phase durations
double-counted overlap and understated `unattributed_ms` — the one
number that matters when a create is slow for no visible reason. Measure
the union of the phase intervals instead.

* refactor(worktree): move stale-preparation cleanup into its own module

The preparation module crossed the 300-line budget. Crash recovery is a
separate concern from the pool itself — it discards preparations another
process left registered, single-flighted per repo and runtime so a burst
of arming calls shares one worktree listing.

* test(worktree): make the re-arm test able to fail

The burst test armed a preparation manually after the second consume, so
the third checkout appeared whether or not the re-arm produced it — the
assertion passed with re-arming disabled. Drop that arming call so the
third checkout can only come from the re-arm, and assert the consume
results rather than discarding them.
---
 src/main/git/exact-ref-probe.ts               |  49 ++++
 .../git/repo-branch-conflict-real-git.test.ts |  49 ++++
 src/main/git/repo-branch-conflict.test.ts     | 120 +++++++++
 src/main/git/repo-branch-conflict.ts          |  53 +++-
 src/main/ipc/worktree-remote.ts               | 250 +++++++++---------
 .../register-worktree-create-handlers.ts      |  10 +-
 .../observability/instrumentation.test.ts     |  48 ++++
 src/main/observability/instrumentation.ts     |  59 ++++-
 src/main/worktree-create-preparation-burst.ts |  21 ++
 ...rktree-create-preparation-stale-cleanup.ts |  79 ++++++
 src/main/worktree-create-preparation.test.ts  |  47 ++++
 src/main/worktree-create-preparation.ts       | 125 ++++-----
 12 files changed, 702 insertions(+), 208 deletions(-)
 create mode 100644 src/main/git/repo-branch-conflict-real-git.test.ts
 create mode 100644 src/main/worktree-create-preparation-burst.ts
 create mode 100644 src/main/worktree-create-preparation-stale-cleanup.ts

diff --git a/src/main/git/exact-ref-probe.ts b/src/main/git/exact-ref-probe.ts
index 6b13cc718c5..96bb421b8e8 100644
--- a/src/main/git/exact-ref-probe.ts
+++ b/src/main/git/exact-ref-probe.ts
@@ -19,6 +19,8 @@ export type ExactRefProbeSetResult = {
 type ExactRefPresence = 'present' | 'absent' | 'unknown'
 
 const EXACT_REF_PROBE_CONCURRENCY = 8
+// SHA-1 and SHA-256 repositories both report a full object id here.
+const OBJECT_ID_PATTERN = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/
 
 export function isShowRefNoMatchError(error: unknown): boolean {
   const record = error && typeof error === 'object' ? (error as Record<string, unknown>) : undefined
@@ -126,3 +128,50 @@ export async function probeAnyExactRef(
   await Promise.all(Array.from({ length: workerCount }, () => probeNext()))
   return { found, unknown }
 }
+
+/** Runs Git with a stdin payload. Only hosts that can feed a child's stdin supply one. */
+export type ExactRefProbeStdinExec = (
+  argv: string[],
+  options: ExactRefProbeExecOptions & { stdin: string }
+) => Promise<{ stdout: string }>
+
+/** `cat-file --batch-check` reports every ref from one child, and reports a missing ref as data
+ *  rather than a failed exit — so a batch stays as decidable as a per-ref `show-ref --verify`.
+ *  A repo with many remotes otherwise pays one subprocess per remote on every conflict check. */
+export async function probeAnyExactRefBatched(
+  runGit: ExactRefProbeStdinExec,
+  refs: readonly string[],
+  options: ExactRefProbeExecOptions = {}
+): Promise<{ found: boolean; unknown: boolean }> {
+  const uniqueRefs = [...new Set(refs)]
+  const safeRefs = uniqueRefs.filter((ref) => isSafeGitRefName(ref))
+  if (safeRefs.length === 0) {
+    return { found: false, unknown: uniqueRefs.length > 0 }
+  }
+  let stdout: string
+  try {
+    ;({ stdout } = await runGit(['cat-file', '--batch-check'], {
+      ...options,
+      stdin: `${safeRefs.join('\n')}\n`
+    }))
+  } catch {
+    return { found: false, unknown: true }
+  }
+  const lines = stdout.split('\n').filter((line) => line.trim().length > 0)
+  // One line per input, in order; a short read means the batch never answered for the rest.
+  if (lines.length !== safeRefs.length) {
+    return { found: false, unknown: true }
+  }
+  let unknown = safeRefs.length !== uniqueRefs.length
+  for (const line of lines) {
+    const [head, type] = line.split(' ')
+    if (OBJECT_ID_PATTERN.test(head) && type !== undefined && type !== 'missing') {
+      return { found: true, unknown: false }
+    }
+    if (type !== 'missing') {
+      // `ambiguous`, or a spelling this Git reports differently; neither proves absence.
+      unknown = true
+    }
+  }
+  return { found: false, unknown }
+}
diff --git a/src/main/git/repo-branch-conflict-real-git.test.ts b/src/main/git/repo-branch-conflict-real-git.test.ts
new file mode 100644
index 00000000000..34092273eda
--- /dev/null
+++ b/src/main/git/repo-branch-conflict-real-git.test.ts
@@ -0,0 +1,49 @@
+import { execFileSync } from 'node:child_process'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { getBranchConflictKind } from './repo-branch-conflict'
+
+describe('branch conflict real Git contract', () => {
+  const tempPaths: string[] = []
+
+  afterEach(() => {
+    for (const path of tempPaths.splice(0)) {
+      rmSync(path, { recursive: true, force: true })
+    }
+  })
+
+  it('decides remote conflicts from one batched probe across many remotes', async () => {
+    const repoPath = mkdtempSync(join(tmpdir(), 'orca-branch-conflict-'))
+    tempPaths.push(repoPath)
+    const git = (...args: string[]): string =>
+      execFileSync('git', args, { cwd: repoPath, encoding: 'utf8' })
+
+    git('init', '--quiet')
+    git('config', 'user.name', 'Orca Test')
+    git('config', 'user.email', 'orca@example.test')
+    git('config', 'commit.gpgSign', 'false')
+    git('config', 'core.hooksPath', '.git/no-hooks')
+    writeFileSync(join(repoPath, 'fixture.txt'), 'base\n')
+    git('add', 'fixture.txt')
+    git('commit', '--quiet', '-m', 'base')
+    const head = git('rev-parse', 'HEAD').trim()
+
+    // Many remotes is the shape that used to cost one subprocess each.
+    for (let index = 0; index < 12; index += 1) {
+      git('remote', 'add', `remote${index}`, 'https://example.test/repo.git')
+    }
+    git('update-ref', 'refs/remotes/remote7/taken', head)
+
+    await expect(getBranchConflictKind(repoPath, 'taken')).resolves.toBe('remote')
+    await expect(getBranchConflictKind(repoPath, 'free')).resolves.toBeNull()
+    // The allowed base ref is the one remote spelling that is not a conflict.
+    await expect(
+      getBranchConflictKind(repoPath, 'taken', 'refs/remotes/remote7/taken')
+    ).resolves.toBeNull()
+
+    git('branch', 'local-only', head)
+    await expect(getBranchConflictKind(repoPath, 'local-only')).resolves.toBe('local')
+  })
+})
diff --git a/src/main/git/repo-branch-conflict.test.ts b/src/main/git/repo-branch-conflict.test.ts
index dab8dd396d6..873c8bd3340 100644
--- a/src/main/git/repo-branch-conflict.test.ts
+++ b/src/main/git/repo-branch-conflict.test.ts
@@ -134,3 +134,123 @@ describe('getBranchConflictKindViaExec', () => {
     expect(exec).not.toHaveBeenCalled()
   })
 })
+
+describe('getBranchConflictKindViaExec batched remote probe', () => {
+  function remoteNames(count: number): string {
+    return `${Array.from({ length: count }, (_, index) => `remote${index}`).join('\n')}\n`
+  }
+
+  function baseExec(calls: string[][]): (argv: string[]) => Promise<{ stdout: string }> {
+    return async (argv) => {
+      calls.push(argv)
+      if (argv[0] === 'rev-parse') {
+        throw new Error('local branch is absent')
+      }
+      if (argv[0] === 'remote') {
+        return { stdout: remoteNames(3) }
+      }
+      throw new Error(`unexpected git command: ${argv.join(' ')}`)
+    }
+  }
+
+  it('asks one batched child instead of one probe per remote', async () => {
+    const calls: string[][] = []
+    const stdinPayloads: (string | undefined)[] = []
+    const exec = baseExec(calls)
+    const batched = async (
+      argv: string[],
+      options: { stdin: string }
+    ): Promise<{ stdout: string }> => {
+      calls.push(argv)
+      stdinPayloads.push(options.stdin)
+      return {
+        stdout: [
+          'refs/remotes/remote0/feature missing',
+          'refs/remotes/remote1/feature missing',
+          'refs/remotes/remote2/feature missing'
+        ].join('\n')
+      }
+    }
+
+    await expect(
+      getBranchConflictKindViaExec(exec, 'feature', undefined, {}, batched)
+    ).resolves.toBeNull()
+    expect(calls).toEqual([
+      ['rev-parse', '--verify', 'refs/heads/feature'],
+      ['remote'],
+      ['cat-file', '--batch-check']
+    ])
+    expect(stdinPayloads).toEqual([
+      'refs/remotes/remote0/feature\nrefs/remotes/remote1/feature\nrefs/remotes/remote2/feature\n'
+    ])
+  })
+
+  it('reports a remote conflict from the batched answer', async () => {
+    const calls: string[][] = []
+    const exec = baseExec(calls)
+    const batched = async (): Promise<{ stdout: string }> => ({
+      stdout: [
+        'refs/remotes/remote0/feature missing',
+        `${'a'.repeat(40)} commit 214`,
+        'refs/remotes/remote2/feature missing'
+      ].join('\n')
+    })
+
+    await expect(
+      getBranchConflictKindViaExec(exec, 'feature', undefined, {}, batched)
+    ).resolves.toBe('remote')
+  })
+
+  it('falls back to per-ref probes when the batch cannot answer', async () => {
+    const calls: string[][] = []
+    const exec = async (argv: string[]): Promise<{ stdout: string }> => {
+      calls.push(argv)
+      if (argv[0] === 'rev-parse') {
+        throw new Error('local branch is absent')
+      }
+      if (argv[0] === 'remote') {
+        return { stdout: remoteNames(3) }
+      }
+      if (argv[0] === 'show-ref') {
+        if (argv[4] === 'refs/remotes/remote1/feature') {
+          return { stdout: 'abc refs/remotes/remote1/feature\n' }
+        }
+        throw Object.assign(new Error('missing'), { code: 1, stderr: '' })
+      }
+      throw new Error(`unexpected git command: ${argv.join(' ')}`)
+    }
+    const batched = async (): Promise<{ stdout: string }> => {
+      throw new Error('cat-file is unavailable')
+    }
+
+    await expect(
+      getBranchConflictKindViaExec(exec, 'feature', undefined, {}, batched)
+    ).resolves.toBe('remote')
+    expect(calls.filter((argv) => argv[0] === 'show-ref')).toHaveLength(3)
+  })
+
+  it('treats a short batch read as undecided rather than as absence', async () => {
+    const calls: string[][] = []
+    const exec = async (argv: string[]): Promise<{ stdout: string }> => {
+      calls.push(argv)
+      if (argv[0] === 'rev-parse') {
+        throw new Error('local branch is absent')
+      }
+      if (argv[0] === 'remote') {
+        return { stdout: remoteNames(3) }
+      }
+      if (argv[0] === 'show-ref') {
+        throw Object.assign(new Error('missing'), { code: 1, stderr: '' })
+      }
+      throw new Error(`unexpected git command: ${argv.join(' ')}`)
+    }
+    const batched = async (): Promise<{ stdout: string }> => ({
+      stdout: 'refs/remotes/remote0/feature missing'
+    })
+
+    await expect(
+      getBranchConflictKindViaExec(exec, 'feature', undefined, {}, batched)
+    ).resolves.toBeNull()
+    expect(calls.filter((argv) => argv[0] === 'show-ref')).toHaveLength(3)
+  })
+})
diff --git a/src/main/git/repo-branch-conflict.ts b/src/main/git/repo-branch-conflict.ts
index 162d5ef53b3..c799d3770be 100644
--- a/src/main/git/repo-branch-conflict.ts
+++ b/src/main/git/repo-branch-conflict.ts
@@ -4,8 +4,10 @@ import { gitExecFileAsync } from './runner'
 import { isSafeGitRefName } from '../../shared/git-status-upstream-ref'
 import {
   probeAnyExactRef,
+  probeAnyExactRefBatched,
   type ExactRefProbeExec,
-  type ExactRefProbeExecOptions
+  type ExactRefProbeExecOptions,
+  type ExactRefProbeStdinExec
 } from './exact-ref-probe'
 
 export type BranchConflictKind = 'local' | 'remote'
@@ -79,12 +81,31 @@ function buildRemoteBranchConflictRefs(
   return [...refs]
 }
 
+/** One batched child answers for every remote; the per-ref probes only run when the host cannot
+ *  feed stdin, or when the batch came back undecided. */
+async function probeAnyRemoteConflictRef(
+  exec: ExactRefProbeExec,
+  batchedExec: ExactRefProbeStdinExec | undefined,
+  candidateRefs: readonly string[],
+  probeOptions: ExactRefProbeExecOptions
+): Promise<{ found: boolean }> {
+  if (batchedExec) {
+    // A present ref is always decisive, so `found` never survives with `unknown` set.
+    const batched = await probeAnyExactRefBatched(batchedExec, candidateRefs, probeOptions)
+    if (!batched.unknown) {
+      return { found: batched.found }
+    }
+  }
+  return probeAnyExactRef(exec, candidateRefs, probeOptions)
+}
+
 /** Run branch-conflict policy through the host that owns Git execution. */
 export async function getBranchConflictKindViaExec(
   exec: ExactRefProbeExec,
   branchName: string,
   allowedBaseRef?: string,
-  options: ExactRefProbeExecOptions = {}
+  options: ExactRefProbeExecOptions = {},
+  batchedExec?: ExactRefProbeStdinExec
 ): Promise<BranchConflictKind | null> {
   if (!canQueryRemoteBranchName(branchName)) {
     return null
@@ -104,7 +125,12 @@ export async function getBranchConflictKindViaExec(
       return null
     }
 
-    const { found: hasRemoteConflict } = await probeAnyExactRef(exec, candidateRefs, probeOptions)
+    const { found: hasRemoteConflict } = await probeAnyRemoteConflictRef(
+      exec,
+      batchedExec,
+      candidateRefs,
+      probeOptions
+    )
 
     return hasRemoteConflict ? 'remote' : null
   } catch {
@@ -119,15 +145,22 @@ export function getBranchConflictKind(
   options: LocalGitExecOptions = {}
 ): Promise<BranchConflictKind | null> {
   const execOptions = gitExecOptions(path, options)
+  const runLocalGit = (
+    argv: string[],
+    commandOptions?: ExactRefProbeExecOptions & { stdin?: string }
+  ): Promise<{ stdout: string }> =>
+    gitExecFileAsync(argv, {
+      ...execOptions,
+      ...(commandOptions?.maxBuffer === undefined ? {} : { maxBuffer: commandOptions.maxBuffer }),
+      ...(commandOptions?.timeoutMs === undefined ? {} : { timeout: commandOptions.timeoutMs }),
+      ...(commandOptions?.stdin === undefined ? {} : { stdin: commandOptions.stdin })
+    })
   return getBranchConflictKindViaExec(
-    (argv, commandOptions) =>
-      gitExecFileAsync(argv, {
-        ...execOptions,
-        ...(commandOptions?.maxBuffer === undefined ? {} : { maxBuffer: commandOptions.maxBuffer }),
-        ...(commandOptions?.timeoutMs === undefined ? {} : { timeout: commandOptions.timeoutMs })
-      }),
+    runLocalGit,
     branchName,
-    allowedBaseRef
+    allowedBaseRef,
+    {},
+    (argv, commandOptions) => runLocalGit(argv, commandOptions)
   )
 }
 
diff --git a/src/main/ipc/worktree-remote.ts b/src/main/ipc/worktree-remote.ts
index e53ae264129..7d28f38f2db 100644
--- a/src/main/ipc/worktree-remote.ts
+++ b/src/main/ipc/worktree-remote.ts
@@ -2189,130 +2189,139 @@ export async function createLocalWorktree(
   let lastExistingReviewNumber: number | null = null
   const shouldRetireGeneratedName =
     args.nameWasGenerated === true && isGeneratedWorktreeCreateName(sanitizedName)
-  const retiredNameRegistry = shouldRetireGeneratedName
-    ? await getRetiredNameRegistryForRepo(store, repo, store.getRepos(), settings)
-    : null
-  const isRetiredName = retiredNameRegistry ? createRetiredNameLookup(retiredNameRegistry) : null
-  // Why: a create-from-review branch override may already exist locally; suffix both branch and path instead of blocking the user.
-  for (let suffix = 1, attempts = 0; attempts < WORKTREE_CREATE_MAX_SUFFIX_ATTEMPTS; suffix += 1) {
-    effectiveSanitizedName = shouldRetireGeneratedName
-      ? getGeneratedWorktreeCreateCandidate(
-          sanitizedName,
-          suffix,
-          retiredNameRegistry?.exhaustedTiers
-        )
-      : getWorktreeCreateCandidate(sanitizedName, suffix)
-    effectiveRequestedName = shouldRetireGeneratedName
-      ? effectiveSanitizedName
-      : requestedName.trim()
-        ? getWorktreeCreateCandidate(requestedName, suffix)
-        : effectiveSanitizedName
-    if (isRetiredName?.(effectiveSanitizedName)) {
-      continue
-    }
-    attempts += 1
-    lastExistingReviewNumber = null
+  await timing.time('resolve_name', async () => {
+    const retiredNameRegistry = shouldRetireGeneratedName
+      ? await getRetiredNameRegistryForRepo(store, repo, store.getRepos(), settings)
+      : null
+    const isRetiredName = retiredNameRegistry ? createRetiredNameLookup(retiredNameRegistry) : null
+    // Why: a create-from-review branch override may already exist locally; suffix both branch and path instead of blocking the user.
+    for (
+      let suffix = 1, attempts = 0;
+      attempts < WORKTREE_CREATE_MAX_SUFFIX_ATTEMPTS;
+      suffix += 1
+    ) {
+      effectiveSanitizedName = shouldRetireGeneratedName
+        ? getGeneratedWorktreeCreateCandidate(
+            sanitizedName,
+            suffix,
+            retiredNameRegistry?.exhaustedTiers
+          )
+        : getWorktreeCreateCandidate(sanitizedName, suffix)
+      effectiveRequestedName = shouldRetireGeneratedName
+        ? effectiveSanitizedName
+        : requestedName.trim()
+          ? getWorktreeCreateCandidate(requestedName, suffix)
+          : effectiveSanitizedName
+      if (isRetiredName?.(effectiveSanitizedName)) {
+        continue
+      }
+      attempts += 1
+      lastExistingReviewNumber = null
 
-    branchName = await resolveCreateBranchName(
-      repo.path,
-      selectedExistingLocalBranchName
-        ? selectedExistingLocalBranchName
-        : getBranchNameOverrideCandidate(args.branchNameOverride, suffix),
-      effectiveSanitizedName,
-      settings,
-      username,
-      localWorktreeGitOptions
-    )
-    checkoutExistingBranch = await canCheckoutExistingLocalBranch(
-      repo.path,
-      branchName,
-      baseBranch,
-      localWorktreeGitOptions
-    )
-    if (checkoutExistingBranch && !selectedExistingLocalBranchName) {
-      // Why: suffix retries may need a new path, but an existing-branch checkout must keep the user-selected branch, not a sibling.
-      selectedExistingLocalBranchName = branchName
-    }
-    lastBranchConflictKind = checkoutExistingBranch
-      ? null
-      : await getBranchConflictKind(repo.path, branchName, baseBranch, localWorktreeGitOptions)
-    const allowedPushTargetRemoteConflict =
-      lastBranchConflictKind &&
-      isAllowedPushTargetRemoteConflict(lastBranchConflictKind, branchName, args)
-    if (lastBranchConflictKind) {
-      if (allowedPushTargetRemoteConflict) {
-        lastExistingPR = null
-        let lookupFailed = false
-        const selectedReview = getSelectedReviewBranch(args)
-        if (selectedReview?.provider === 'github') {
-          try {
-            lastExistingPR = await getLocalGitHubPrForBranch(
-              repo.path,
-              branchName,
-              localWorktreeGitOptions
-            )
-          } catch {
-            lookupFailed = true
-          }
-          if (!lookupFailed && isMatchingSelectedGitHubPr(lastExistingPR, args, branchName)) {
-            lastBranchConflictKind = null
-          } else if (lastExistingPR) {
-            lastExistingReviewNumber = lastExistingPR.number
-          }
-        } else if (selectedReview) {
-          let hostedReview: Awaited<ReturnType<typeof getSelectedHostedReviewForBranch>> = null
-          try {
-            hostedReview = await getSelectedHostedReviewForBranch(repo, branchName, args)
-          } catch {
-            lookupFailed = true
-          }
-          if (!lookupFailed && hostedReview?.matchesSelected) {
-            lastBranchConflictKind = null
-          } else if (hostedReview) {
-            lastExistingReviewNumber = hostedReview.number
+      branchName = await resolveCreateBranchName(
+        repo.path,
+        selectedExistingLocalBranchName
+          ? selectedExistingLocalBranchName
+          : getBranchNameOverrideCandidate(args.branchNameOverride, suffix),
+        effectiveSanitizedName,
+        settings,
+        username,
+        localWorktreeGitOptions
+      )
+      checkoutExistingBranch = await canCheckoutExistingLocalBranch(
+        repo.path,
+        branchName,
+        baseBranch,
+        localWorktreeGitOptions
+      )
+      if (checkoutExistingBranch && !selectedExistingLocalBranchName) {
+        // Why: suffix retries may need a new path, but an existing-branch checkout must keep the user-selected branch, not a sibling.
+        selectedExistingLocalBranchName = branchName
+      }
+      lastBranchConflictKind = checkoutExistingBranch
+        ? null
+        : await getBranchConflictKind(repo.path, branchName, baseBranch, localWorktreeGitOptions)
+      const allowedPushTargetRemoteConflict =
+        lastBranchConflictKind &&
+        isAllowedPushTargetRemoteConflict(lastBranchConflictKind, branchName, args)
+      if (lastBranchConflictKind) {
+        if (allowedPushTargetRemoteConflict) {
+          lastExistingPR = null
+          let lookupFailed = false
+          const selectedReview = getSelectedReviewBranch(args)
+          if (selectedReview?.provider === 'github') {
+            try {
+              lastExistingPR = await getLocalGitHubPrForBranch(
+                repo.path,
+                branchName,
+                localWorktreeGitOptions
+              )
+            } catch {
+              lookupFailed = true
+            }
+            if (!lookupFailed && isMatchingSelectedGitHubPr(lastExistingPR, args, branchName)) {
+              lastBranchConflictKind = null
+            } else if (lastExistingPR) {
+              lastExistingReviewNumber = lastExistingPR.number
+            }
+          } else if (selectedReview) {
+            let hostedReview: Awaited<ReturnType<typeof getSelectedHostedReviewForBranch>> = null
+            try {
+              hostedReview = await getSelectedHostedReviewForBranch(repo, branchName, args)
+            } catch {
+              lookupFailed = true
+            }
+            if (!lookupFailed && hostedReview?.matchesSelected) {
+              lastBranchConflictKind = null
+            } else if (hostedReview) {
+              lastExistingReviewNumber = hostedReview.number
+            }
           }
         }
       }
-    }
-    if (lastBranchConflictKind) {
-      continue
-    }
-
-    // Why: gh pr list is a ~1–3s network call; only probe PR conflicts after a branch collision (suffix > 1) so the common no-collision path skips it.
-    if (suffix > 1 && !checkoutExistingBranch) {
-      lastExistingPR = null
-      try {
-        lastExistingPR = await getLocalGitHubPrForBranch(
-          repo.path,
-          branchName,
-          localWorktreeGitOptions
-        )
-      } catch {
-        // GitHub API may be unreachable, rate-limited, or token missing
-      }
-      if (lastExistingPR && !isMatchingSelectedGitHubPr(lastExistingPR, args, branchName)) {
-        lastExistingReviewNumber = lastExistingPR.number
+      if (lastBranchConflictKind) {
         continue
       }
-    }
 
-    worktreePath = ensurePathWithinWorkspace(
-      computeWorktreePath(effectiveSanitizedName, repo.path, worktreePathSettings),
-      workspaceRoot
-    )
-    if (existsSync(worktreePath)) {
-      continue
-    }
+      // Why: gh pr list is a ~1–3s network call; only probe PR conflicts after a branch collision (suffix > 1) so the common no-collision path skips it.
+      if (suffix > 1 && !checkoutExistingBranch) {
+        lastExistingPR = null
+        try {
+          lastExistingPR = await getLocalGitHubPrForBranch(
+            repo.path,
+            branchName,
+            localWorktreeGitOptions
+          )
+        } catch {
+          // GitHub API may be unreachable, rate-limited, or token missing
+        }
+        if (lastExistingPR && !isMatchingSelectedGitHubPr(lastExistingPR, args, branchName)) {
+          lastExistingReviewNumber = lastExistingPR.number
+          continue
+        }
+      }
 
-    resolved = true
-    break
-  }
+      worktreePath = ensurePathWithinWorkspace(
+        computeWorktreePath(effectiveSanitizedName, repo.path, worktreePathSettings),
+        workspaceRoot
+      )
+      if (existsSync(worktreePath)) {
+        continue
+      }
+
+      resolved = true
+      break
+    }
+  })
 
   if (!resolved) {
     // Why: every suffix collided; reject with a specific reason so the user sees why create failed instead of a generic error or hung spinner.
-    if (lastExistingReviewNumber !== null) {
+    // Read once and format eagerly: the suffix loop assigns this from a callback, so the `let`'s
+    // narrowing does not reach the message.
+    const existingReviewNumber = lastExistingReviewNumber
+    if (existingReviewNumber !== null) {
       throw new Error(
-        `Branch "${branchName}" already has PR #${lastExistingReviewNumber}. Pick a different ${branchConflictSubject}.`
+        `Branch "${branchName}" already has PR #${String(existingReviewNumber)}. Pick a different ${branchConflictSubject}.`
       )
     }
     if (lastBranchConflictKind) {
@@ -2361,14 +2370,17 @@ export async function createLocalWorktree(
   emitCreateWorktreeProgress(mainWindow, 'creating', args.creationId)
 
   let preparedPushTarget: GitPushTarget | undefined
-  if (args.pushTarget) {
+  const requestedPushTarget = args.pushTarget
+  if (requestedPushTarget) {
     // Why: validate/fetch the contributor remote before create so a failure doesn't leave a half-created worktree with conflicts on retry.
-    preparedPushTarget = await prepareWorktreePushTarget(
-      repo.path,
-      args.pushTarget,
-      store,
-      repo.id,
-      localWorktreeGitOptions
+    preparedPushTarget = await timing.time('prepare_push_target', () =>
+      prepareWorktreePushTarget(
+        repo.path,
+        requestedPushTarget,
+        store,
+        repo.id,
+        localWorktreeGitOptions
+      )
     )
   }
 
diff --git a/src/main/ipc/worktrees/create/register-worktree-create-handlers.ts b/src/main/ipc/worktrees/create/register-worktree-create-handlers.ts
index 775a0859790..f371529963c 100644
--- a/src/main/ipc/worktrees/create/register-worktree-create-handlers.ts
+++ b/src/main/ipc/worktrees/create/register-worktree-create-handlers.ts
@@ -4,7 +4,10 @@ import type {
   CreateWorktreeResult,
   AdoptProvisionedRootArgs
 } from '../../../../shared/worktree/create-types'
-import { withWorktreeSpan } from '../../../observability/instrumentation'
+import {
+  addWorktreeCreatePhaseAttributes,
+  withWorktreeSpan
+} from '../../../observability/instrumentation'
 import { workspaceSourceSchema } from '../../../../shared/telemetry-events'
 import type { WorkspaceSource } from '../../../../shared/telemetry-events'
 import {
@@ -36,7 +39,7 @@ export function registerWorktreeCreateHandlers(context: WorktreeIpcContext): voi
     async (_event, rawArgs: CreateWorktreeArgs): Promise<CreateWorktreeResult> => {
       const args = normalizeLinkedWorkItemFields(rawArgs)
       // Why span here: parent the child git spans for the trace tree; don't attach branch name/remote URL (user content) — repo ID is the safer correlator.
-      return withWorktreeSpan({ stage: 'create' }, async () => {
+      return withWorktreeSpan({ stage: 'create' }, async (span) => {
         const repo = store.getRepo(args.repoId)
         if (!repo) {
           throw new Error(`Repo not found: ${args.repoId}`)
@@ -74,6 +77,9 @@ export function registerWorktreeCreateHandlers(context: WorktreeIpcContext): voi
           throw error
         }
         finishAutomationWorkspaceProvenanceRequest(args.automationProvenanceRequest)
+        if (result.timing) {
+          addWorktreeCreatePhaseAttributes(span, result.timing)
+        }
 
         // Why: reaching here means create succeeded (helpers throw); skip a separate workspace_initialized (telemetry-plan.md§Deferred); never send the branch name.
         track('workspace_created', {
diff --git a/src/main/observability/instrumentation.test.ts b/src/main/observability/instrumentation.test.ts
index 2f7d1da05dd..978854897e4 100644
--- a/src/main/observability/instrumentation.test.ts
+++ b/src/main/observability/instrumentation.test.ts
@@ -3,6 +3,7 @@ import { _resetTracerForTests, setActiveSink, type TracerSink } from './tracer'
 import {
   _gitSpanSamplingBucketCountForTests,
   _resetGitSpanSamplingForTests,
+  addWorktreeCreatePhaseAttributes,
   withGitSpan
 } from './instrumentation'
 
@@ -167,3 +168,50 @@ describe('withGitSpan sampling', () => {
     expect(_gitSpanSamplingBucketCountForTests()).toBe(1)
   })
 })
+
+describe('addWorktreeCreatePhaseAttributes', () => {
+  function capture(): {
+    attributes: Record<string, unknown>
+    span: Parameters<typeof addWorktreeCreatePhaseAttributes>[0]
+  } {
+    const attributes: Record<string, unknown> = {}
+    const span = {
+      setAttribute: (key: string, value: unknown) => {
+        attributes[key] = value
+      }
+    } as unknown as Parameters<typeof addWorktreeCreatePhaseAttributes>[0]
+    return { attributes, span }
+  }
+
+  it('counts concurrent phases once when measuring unattributed time', () => {
+    const { attributes, span } = capture()
+    // Create resolves shared directories and .worktreeinclude concurrently; summing their
+    // durations would claim 400ms of coverage for a 200ms window.
+    addWorktreeCreatePhaseAttributes(span, {
+      totalDurationMs: 1000,
+      phases: [
+        { phase: 'resolve_shared_directories', startedAtMs: 100, durationMs: 200 },
+        { phase: 'resolve_worktreeinclude', startedAtMs: 150, durationMs: 150 }
+      ]
+    })
+
+    expect(attributes['worktree.create.phase.resolve_shared_directories_ms']).toBe(200)
+    expect(attributes['worktree.create.phase.resolve_worktreeinclude_ms']).toBe(150)
+    // Covered wall clock is 100..300, so 800ms is genuinely unaccounted for.
+    expect(attributes['worktree.create.unattributed_ms']).toBe(800)
+  })
+
+  it('sums disjoint phases and never reports negative unattributed time', () => {
+    const { attributes, span } = capture()
+    addWorktreeCreatePhaseAttributes(span, {
+      totalDurationMs: 500,
+      phases: [
+        { phase: 'resolve_name', startedAtMs: 0, durationMs: 100 },
+        { phase: 'git_worktree_add', startedAtMs: 300, durationMs: 200 }
+      ]
+    })
+
+    expect(attributes['worktree.create.total_ms']).toBe(500)
+    expect(attributes['worktree.create.unattributed_ms']).toBe(200)
+  })
+})
diff --git a/src/main/observability/instrumentation.ts b/src/main/observability/instrumentation.ts
index bab57b74f64..fb57aa5a870 100644
--- a/src/main/observability/instrumentation.ts
+++ b/src/main/observability/instrumentation.ts
@@ -202,10 +202,11 @@ export type WorktreeSpanArgs = {
   readonly path?: string
 }
 
-/** Wrap a worktree-setup phase in a `worktree.<stage>` span. */
+/** Wrap a worktree-setup phase in a `worktree.<stage>` span. The callback receives the span so a
+ *  create can attach its own phase breakdown; the git children alone leave the waits invisible. */
 export async function withWorktreeSpan<T>(
   meta: WorktreeSpanArgs,
-  fn: () => Promise<T>
+  fn: (span: ActiveSpan) => Promise<T>
 ): Promise<T> {
   return withSpan(
     `worktree.${meta.stage}`,
@@ -214,12 +215,64 @@ export async function withWorktreeSpan<T>(
       if (meta.path) {
         span.setAttribute('worktree.path', meta.path)
       }
-      return await fn()
+      return await fn(span)
     },
     { attributes: { kind: 'worktree' } }
   )
 }
 
+type WorktreeCreatePhaseTiming = {
+  readonly phase: string
+  readonly startedAtMs: number
+  readonly durationMs: number
+}
+
+/** Wall-clock span covered by at least one phase. Create runs some phases concurrently, so summing
+ *  durations double-counts and would report overlap as coverage the phases never had. */
+function measuredWallClockMs(phases: readonly WorktreePhaseInterval[]): number {
+  const intervals = [...phases]
+    .map((phase) => [phase.startedAtMs, phase.startedAtMs + phase.durationMs] as const)
+    .sort((left, right) => left[0] - right[0])
+  let covered = 0
+  let openedAt: number | null = null
+  let closesAt = 0
+  for (const [start, end] of intervals) {
+    if (openedAt === null) {
+      openedAt = start
+      closesAt = end
+      continue
+    }
+    if (start <= closesAt) {
+      closesAt = Math.max(closesAt, end)
+      continue
+    }
+    covered += closesAt - openedAt
+    openedAt = start
+    closesAt = end
+  }
+  return openedAt === null ? 0 : covered + (closesAt - openedAt)
+}
+
+type WorktreePhaseInterval = Pick<WorktreeCreatePhaseTiming, 'startedAtMs' | 'durationMs'>
+
+/** Records a create's phase breakdown on its span. Phase names are already a closed vocabulary in
+ *  the recorder, so they are safe to key on; nothing here carries a branch name or a path. */
+export function addWorktreeCreatePhaseAttributes(
+  span: ActiveSpan,
+  timing: { totalDurationMs: number; phases: readonly WorktreeCreatePhaseTiming[] }
+): void {
+  span.setAttribute('worktree.create.total_ms', Math.round(timing.totalDurationMs))
+  for (const phase of timing.phases) {
+    span.setAttribute(`worktree.create.phase.${phase.phase}_ms`, Math.round(phase.durationMs))
+  }
+  // What the phases do not cover is the number that matters when create feels slow for no visible
+  // reason, so name it rather than leaving it to subtraction.
+  span.setAttribute(
+    'worktree.create.unattributed_ms',
+    Math.max(0, Math.round(timing.totalDurationMs - measuredWallClockMs(timing.phases)))
+  )
+}
+
 /** Closed set so a typo can't silently mint an orphan span name. */
 export type WorktreeRemoveStage =
   | 'archive_hook'
diff --git a/src/main/worktree-create-preparation-burst.ts b/src/main/worktree-create-preparation-burst.ts
new file mode 100644
index 00000000000..d289927ffaa
--- /dev/null
+++ b/src/main/worktree-create-preparation-burst.ts
@@ -0,0 +1,21 @@
+import { setBoundedMapEntry } from './runtime/runtime-async-boundaries'
+
+/** Two creates this close together mean more are likely; an isolated create earns no replacement. */
+export const WORKTREE_CREATE_BURST_MS = 5 * 60_000
+const WORKTREE_CREATE_PREPARATION_CONSUME_MAX = 64
+
+/** When each preparation key was last consumed, so a burst can be told from an isolated create. */
+const lastConsumedAt = new Map<string, number>()
+
+/** Records this consume and reports whether it continues a burst. A replacement checkout costs a
+ *  full tree and holds disk until its TTL, so only a user who is already creating repeatedly earns
+ *  one; the first create of a session pays nothing for a spare nobody claims. */
+export function recordPreparationConsume(key: string, now = Date.now()): boolean {
+  const previous = lastConsumedAt.get(key)
+  setBoundedMapEntry(lastConsumedAt, key, now, WORKTREE_CREATE_PREPARATION_CONSUME_MAX)
+  return previous !== undefined && now - previous <= WORKTREE_CREATE_BURST_MS
+}
+
+export function resetPreparationConsumeHistoryForTests(): void {
+  lastConsumedAt.clear()
+}
diff --git a/src/main/worktree-create-preparation-stale-cleanup.ts b/src/main/worktree-create-preparation-stale-cleanup.ts
new file mode 100644
index 00000000000..4a422f672ed
--- /dev/null
+++ b/src/main/worktree-create-preparation-stale-cleanup.ts
@@ -0,0 +1,79 @@
+import {
+  isWorktreeCreatePreparation,
+  parseWorktreePreparationOwnerPid,
+  parseWorktreePreparationPathOwnerPid
+} from '../shared/worktree/create-preparation'
+import type { AddWorktreeOptions } from './git/worktree'
+import { listWorktreeGraph } from './git/worktree'
+import { discardPreparedWorktree, unlockPreparedWorktree } from './git/worktree-create-preparation'
+import { retryPendingPreparationDiscards } from './worktree-preparation-discard-retry'
+
+const STALE_PREPARATION_CLEANUP_CONCURRENCY = 4
+
+const staleCleanupInFlight = new Map<string, Promise<void>>()
+
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code !== 'ESRCH'
+  }
+}
+
+/** Reclaims preparations a crashed process left registered. Single-flighted per host key so a burst
+ *  of arming calls shares one worktree listing. */
+export async function cleanupStalePreparations(
+  cleanupKey: string,
+  repoPath: string,
+  options: AddWorktreeOptions
+): Promise<void> {
+  const existing = staleCleanupInFlight.get(cleanupKey)
+  if (existing) {
+    await existing.catch(() => {})
+    return
+  }
+  const cleanup = (async () => {
+    // Not awaited: the create path awaits this cleanup, and one stranded discard costs an unlock plus
+    // a `worktree remove --force` bounded at 30s each. Reclaiming leaked scratch must not delay create.
+    void retryPendingPreparationDiscards(cleanupKey)
+    const worktrees = await listWorktreeGraph(repoPath, {
+      ...options,
+      includeCreatePreparations: true
+    })
+    const staleWorktrees = worktrees.filter(isWorktreeCreatePreparation)
+    let nextIndex = 0
+    async function discardNextStalePreparation(): Promise<void> {
+      while (nextIndex < staleWorktrees.length) {
+        const worktree = staleWorktrees[nextIndex]
+        nextIndex += 1
+        const lockOwnerPid = parseWorktreePreparationOwnerPid(worktree.lockReason)
+        const pathOwnerPid = parseWorktreePreparationPathOwnerPid(worktree.path)
+        if (!lockOwnerPid || isProcessAlive(lockOwnerPid)) {
+          continue
+        }
+        // Preserve a branch-attached final path after a crash; only detached or
+        // still-hidden preparations are safe to discard automatically.
+        if (worktree.branch && pathOwnerPid === null) {
+          await unlockPreparedWorktree(repoPath, worktree.path, options).catch(() => {})
+        } else if (pathOwnerPid === lockOwnerPid) {
+          await discardPreparedWorktree(repoPath, worktree.path, options).catch(() => {})
+        }
+      }
+    }
+    const workerCount = Math.min(STALE_PREPARATION_CLEANUP_CONCURRENCY, staleWorktrees.length)
+    await Promise.all(Array.from({ length: workerCount }, () => discardNextStalePreparation()))
+  })()
+  staleCleanupInFlight.set(cleanupKey, cleanup)
+  try {
+    await cleanup.catch(() => {})
+  } finally {
+    if (staleCleanupInFlight.get(cleanupKey) === cleanup) {
+      staleCleanupInFlight.delete(cleanupKey)
+    }
+  }
+}
+
+export function resetStalePreparationCleanupForTests(): void {
+  staleCleanupInFlight.clear()
+}
diff --git a/src/main/worktree-create-preparation.test.ts b/src/main/worktree-create-preparation.test.ts
index 3e03643d6a8..dababbef88d 100644
--- a/src/main/worktree-create-preparation.test.ts
+++ b/src/main/worktree-create-preparation.test.ts
@@ -466,4 +466,51 @@ describe('worktree create preparation registry', () => {
     expect(mocks.mkdir).toHaveBeenCalledWith('/workspace', { recursive: true })
     expect(mocks.discard).toHaveBeenCalledTimes(1)
   })
+
+  function consumeOnce(name: string): ReturnType<typeof consumePreparedWorktreeCreate> {
+    return consumePreparedWorktreeCreate({
+      repoPath: repo.path,
+      workspaceRoot: '/workspace',
+      worktreePath: `/workspace/${name}`,
+      branch: `feature/${name}`,
+      baseBranch: 'origin/main'
+    })
+  }
+
+  it('does not re-arm after an isolated create', async () => {
+    await prepareWorktreeCreateForRepo(store, repo, 'origin/main')
+    await expect(consumeOnce('only')).resolves.toEqual({})
+
+    // Why: a lone create would otherwise leave a full spare checkout on disk for the whole TTL.
+    expect(mocks.prepareCheckout).toHaveBeenCalledTimes(1)
+  })
+
+  it('re-arms a preparation once creates arrive in a burst', async () => {
+    await prepareWorktreeCreateForRepo(store, repo, 'origin/main')
+    await expect(consumeOnce('first')).resolves.toEqual({})
+    expect(mocks.prepareCheckout).toHaveBeenCalledTimes(1)
+
+    await prepareWorktreeCreateForRepo(store, repo, 'origin/main')
+    expect(mocks.prepareCheckout).toHaveBeenCalledTimes(2)
+
+    // No arming call follows this consume: the third checkout can only come from the re-arm.
+    await expect(consumeOnce('second')).resolves.toEqual({})
+    expect(mocks.prepareCheckout).toHaveBeenCalledTimes(3)
+
+    // The replacement is claimable, so a third create still skips the cold add.
+    await expect(consumeOnce('third')).resolves.toEqual({})
+    expect(mocks.finalize).toHaveBeenCalledTimes(3)
+  })
+
+  it('does not re-arm when finalization failed', async () => {
+    await prepareWorktreeCreateForRepo(store, repo, 'origin/main')
+    await expect(consumeOnce('first')).resolves.toEqual({})
+    await prepareWorktreeCreateForRepo(store, repo, 'origin/main')
+    mocks.prepareCheckout.mockClear()
+    mocks.finalize.mockRejectedValueOnce(new Error('submodules prevent worktree move'))
+
+    await expect(consumeOnce('second')).resolves.toBeNull()
+
+    expect(mocks.prepareCheckout).not.toHaveBeenCalled()
+  })
 })
diff --git a/src/main/worktree-create-preparation.ts b/src/main/worktree-create-preparation.ts
index ff7478cb46e..22bcf5d1e2c 100644
--- a/src/main/worktree-create-preparation.ts
+++ b/src/main/worktree-create-preparation.ts
@@ -7,17 +7,12 @@ import { isFolderRepo } from '../shared/repo-kind'
 import { isWindowsAbsolutePathLike } from '../shared/cross-platform-path'
 import {
   WORKTREE_CREATE_PREPARATION_DIRECTORY,
-  createWorktreePreparationLockReason,
-  isWorktreeCreatePreparation,
-  parseWorktreePreparationOwnerPid,
-  parseWorktreePreparationPathOwnerPid
+  createWorktreePreparationLockReason
 } from '../shared/worktree/create-preparation'
 import type { AddWorktreeOptions, AddWorktreeResult } from './git/worktree'
-import { listWorktreeGraph } from './git/worktree'
 import {
   discardPreparedWorktree,
   finalizePreparedWorktree,
-  unlockPreparedWorktree,
   prepareWorktreeCreateCheckout
 } from './git/worktree-create-preparation'
 import {
@@ -25,17 +20,23 @@ import {
   getWorktreeMirrorDistro
 } from './project-runtime-git-options'
 import { computeWorkspaceRootAsync, getWorktreePathSettings } from './ipc/worktree-logic'
+import {
+  recordPreparationConsume,
+  resetPreparationConsumeHistoryForTests
+} from './worktree-create-preparation-burst'
+import {
+  cleanupStalePreparations,
+  resetStalePreparationCleanupForTests
+} from './worktree-create-preparation-stale-cleanup'
 import { toHostFilesystemPath } from './host-tree-removal'
 import {
   discardPreparationWithRetry,
   resetPendingPreparationDiscardsForTests,
-  retryPendingPreparationDiscards,
   trackPreparationDiscard
 } from './worktree-preparation-discard-retry'
 
 export const WORKTREE_CREATE_PREPARATION_TTL_MS = 5 * 60_000
 export const WORKTREE_CREATE_PREPARATION_LIMIT = 3
-const STALE_PREPARATION_CLEANUP_CONCURRENCY = 4
 
 type PreparationEntry = {
   key: string
@@ -59,7 +60,6 @@ type ConsumePreparedWorktreeArgs = {
 }
 
 const preparations = new Map<string, PreparationEntry>()
-const staleCleanupInFlight = new Map<string, Promise<void>>()
 
 function pathOps(path: string): Pick<typeof posix, 'dirname' | 'join' | 'normalize'> {
   return isWindowsAbsolutePathLike(path) ? win32 : posix
@@ -79,15 +79,6 @@ function preparationKey(
   return `${pathKey(repoPath)}\0${pathKey(workspaceRoot)}\0${baseBranch}\0${options.wslDistro ?? ''}`
 }
 
-function isProcessAlive(pid: number): boolean {
-  try {
-    process.kill(pid, 0)
-    return true
-  } catch (error) {
-    return (error as NodeJS.ErrnoException).code !== 'ESRCH'
-  }
-}
-
 function preparationHostKey(repoPath: string, options: AddWorktreeOptions): string {
   return `${pathKey(repoPath)}\0${options.wslDistro ?? ''}`
 }
@@ -131,57 +122,6 @@ function enforcePreparationLimit(): void {
   }
 }
 
-async function cleanupStalePreparations(
-  repoPath: string,
-  options: AddWorktreeOptions
-): Promise<void> {
-  const cleanupKey = preparationHostKey(repoPath, options)
-  const existing = staleCleanupInFlight.get(cleanupKey)
-  if (existing) {
-    await existing.catch(() => {})
-    return
-  }
-  const cleanup = (async () => {
-    // Not awaited: the create path awaits this cleanup, and one stranded discard costs an unlock plus
-    // a `worktree remove --force` bounded at 30s each. Reclaiming leaked scratch must not delay create.
-    void retryPendingPreparationDiscards(cleanupKey)
-    const worktrees = await listWorktreeGraph(repoPath, {
-      ...options,
-      includeCreatePreparations: true
-    })
-    const staleWorktrees = worktrees.filter(isWorktreeCreatePreparation)
-    let nextIndex = 0
-    async function discardNextStalePreparation(): Promise<void> {
-      while (nextIndex < staleWorktrees.length) {
-        const worktree = staleWorktrees[nextIndex]
-        nextIndex += 1
-        const lockOwnerPid = parseWorktreePreparationOwnerPid(worktree.lockReason)
-        const pathOwnerPid = parseWorktreePreparationPathOwnerPid(worktree.path)
-        if (!lockOwnerPid || isProcessAlive(lockOwnerPid)) {
-          continue
-        }
-        // Preserve a branch-attached final path after a crash; only detached or
-        // still-hidden preparations are safe to discard automatically.
-        if (worktree.branch && pathOwnerPid === null) {
-          await unlockPreparedWorktree(repoPath, worktree.path, options).catch(() => {})
-        } else if (pathOwnerPid === lockOwnerPid) {
-          await discardPreparedWorktree(repoPath, worktree.path, options).catch(() => {})
-        }
-      }
-    }
-    const workerCount = Math.min(STALE_PREPARATION_CLEANUP_CONCURRENCY, staleWorktrees.length)
-    await Promise.all(Array.from({ length: workerCount }, () => discardNextStalePreparation()))
-  })()
-  staleCleanupInFlight.set(cleanupKey, cleanup)
-  try {
-    await cleanup.catch(() => {})
-  } finally {
-    if (staleCleanupInFlight.get(cleanupKey) === cleanup) {
-      staleCleanupInFlight.delete(cleanupKey)
-    }
-  }
-}
-
 export async function prepareWorktreeCreateForRepo(
   store: Store,
   repo: Repo,
@@ -205,6 +145,16 @@ export async function prepareWorktreeCreateForRepo(
     return existing.ready
   }
 
+  return startPreparation(key, repo.path, workspaceRoot, baseBranch, options)
+}
+
+function startPreparation(
+  key: string,
+  repoPath: string,
+  workspaceRoot: string,
+  baseBranch: string,
+  options: AddWorktreeOptions
+): Promise<void> {
   enforcePreparationLimit()
   const preparationId = `${process.pid}-${randomUUID()}`
   const lockReason = createWorktreePreparationLockReason(preparationId)
@@ -218,21 +168,21 @@ export async function prepareWorktreeCreateForRepo(
   expiration.unref()
   Object.assign(entry, {
     key,
-    repoPath: repo.path,
+    repoPath,
     workspaceRoot,
     preparedPath,
     options,
     createdAt: Date.now(),
     expiration,
     ready: (async () => {
-      await cleanupStalePreparations(repo.path, options)
+      await cleanupStalePreparations(preparationHostKey(repoPath, options), repoPath, options)
       await mkdir(
         toHostFilesystemPath(
           pathOps(workspaceRoot).join(workspaceRoot, WORKTREE_CREATE_PREPARATION_DIRECTORY)
         ),
         { recursive: true }
       )
-      await prepareWorktreeCreateCheckout(repo.path, preparedPath, baseBranch, lockReason, options)
+      await prepareWorktreeCreateCheckout(repoPath, preparedPath, baseBranch, lockReason, options)
     })()
   } satisfies PreparationEntry)
   preparations.set(key, entry)
@@ -266,6 +216,28 @@ async function claimPreparedWorktree(
   }
 }
 
+/** Replaces a just-consumed preparation, but only once the user has shown they are creating in a
+ *  burst. A replacement costs a full checkout and ~5 minutes of disk until its TTL, so arming one
+ *  after an isolated create spends that on nobody. Never awaited: create has already returned by
+ *  the time the replacement checkout finishes. */
+function rearmPreparation(entry: PreparationEntry, baseBranch: string): void {
+  // Record first: a prefetch that re-armed this key while we finalized would otherwise swallow the
+  // consume, and the next create would look isolated when it is really the middle of a burst.
+  const continuesBurst = recordPreparationConsume(entry.key)
+  if (preparations.has(entry.key) || !continuesBurst) {
+    return
+  }
+  void startPreparation(
+    entry.key,
+    entry.repoPath,
+    entry.workspaceRoot,
+    baseBranch,
+    entry.options
+  ).catch(() => {
+    // Why: a warm-up failure is recovered by the normal add on the next create.
+  })
+}
+
 export async function consumePreparedWorktreeCreate(
   args: ConsumePreparedWorktreeArgs
 ): Promise<AddWorktreeResult | null> {
@@ -283,7 +255,7 @@ export async function consumePreparedWorktreeCreate(
     await mkdir(toHostFilesystemPath(pathOps(args.worktreePath).dirname(args.worktreePath)), {
       recursive: true
     })
-    return await finalizePreparedWorktree(
+    const result = await finalizePreparedWorktree(
       args.repoPath,
       entry.preparedPath,
       args.worktreePath,
@@ -292,6 +264,10 @@ export async function consumePreparedWorktreeCreate(
       args.refreshLocalBaseRef,
       options
     )
+    // Consuming the only prepared checkout leaves the next create cold. Re-arm for a user who is
+    // creating in a burst; the TTL and the preparation limit still bound an unused replacement.
+    rearmPreparation(entry, args.baseBranch)
+    return result
   } catch (error) {
     await discardPreparedWorktree(args.repoPath, entry.preparedPath, options).catch(() => {})
     console.warn(
@@ -305,7 +281,8 @@ export async function consumePreparedWorktreeCreate(
 export async function _resetWorktreeCreatePreparationsForTests(): Promise<void> {
   const entries = [...preparations.values()]
   preparations.clear()
-  staleCleanupInFlight.clear()
+  resetPreparationConsumeHistoryForTests()
+  resetStalePreparationCleanupForTests()
   await Promise.all(
     entries.map(async (entry) => {
       clearTimeout(entry.expiration)

From 8b7d778a2ef5e3c0a17434b564486e8aa61138de Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Tue, 1 Sep 2026 19:04:03 -0700
Subject: [PATCH 22/32] perf(git-common): bound the fs-stat fan-out in the
 worktree pollers (#17839)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* perf(git-common): bound the fs-stat fan-out in the worktree pollers

snapshotGitCommon and snapshotBase issued one fs op per candidate via
Promise.all/a serial loop, unbounded by worktree count. At 973 live
worktrees this queued ~6,800 concurrent stat calls (measured peak 6000
in a 1000-entry synthetic benchmark) onto libuv's 4-thread default
pool, starving every other main-process fs operation for the scan's
duration (~1s). Bound both to concurrency 8 via the existing
forEachWithConcurrency helper, matching the precedent in
exact-ref-probe.ts and worktree-head-identity-reader.ts. Peak
concurrent stats dropped 6000 -> 48 in the benchmark; wall time was
essentially unchanged (495ms -> 541ms), since the real bottleneck was
never total scan time but pool starvation of unrelated work.

Also make the no-native-watch and crash-fuse polling fallbacks in
worktree-git-common-watch.ts / worktree-git-common-narrow-watch.ts
self-calibrate their cadence: on platforms/paths where this poller is
the sole change signal, a fixed 2s cadence at hundreds of worktrees
approaches a permanent scan loop. Stretch the interval so a scan stays
a bounded fraction (10%) of its own cadence, capped at 30s, floored at
the configured base interval. Left the reconciliation backstop (fixed
30s cadence, already accepted) and checkPendingMarkers (bounded by
concurrent-worktree-creation count, not total count) untouched.

Fixes #17828

* perf(git-common): split the tripwire from the per-entry sweep cadence

Review on #17839 found a real staleness trade-off: adaptiveCadence
gated ALL detection (worktree add/remove, HEAD, dirty refs, AND
per-entry commit signals) behind one stretched interval, so on the
crash-fuse polling fallback the reviewer measured cadence sitting at
5.4-10s sustained and hitting the 30s cap once a single scan reached
3s at 973 worktrees -- worse than the pre-#17828 fixed ~2s+250ms
baseline for signals users notice immediately (sidebar worktree list,
branch labels).

Split snapshotGitCommon into a cheap structural "tripwire" (readdir,
worktreesDir signature, primary-file signatures, newly-appeared
entries -- ~5-6 fs ops, O(1) in worktree count) that always runs on
the fixed pollIntervalMs, and the O(n) per-entry sweep (commit/dirty
detection) that alone is gated by the adaptive cadence via a
nextSweepDueAt deadline. Existing, unchanged entries are carried over
by reference on a tripwire-only tick (no re-stat), so diffing produces
no spurious events; genuinely new entries are still stat'd immediately
so worktree add remains real-time. This keeps everything on one
ticking-flag-guarded loop (no new concurrency/race surface) --
scheduling stays fixed at pollIntervalMs; only nextSweepDueAt stretches.

Also drop the adaptive-cadence seed heuristic entirely: nextSweepDueAt
starts at 0, so the first regular tick after bootstrap sweeps
unconditionally on its own schedule instead of guessing an initial
interval from the bootstrap snapshot's duration (which could stretch
the very first tick to 10-30s on a slow disk).

Documented that worktree-git-common-watch.ts's adaptiveCadence call
site is unreachable in production (Electron only ships
darwin/linux/win32, both covered by NARROW_WATCH_PLATFORMS) rather
than implying it protects real users. The reachable path is the
narrow-watch crash-fuse fallback in worktree-git-common-narrow-watch.ts.

Filed #17878 to track the real long-term fix: periodically retrying
the upgrade back to the narrow watch after a crash-fuse trip, so the
degraded/polling state doesn't need to be tuned at all once the
underlying failure clears.

* perf(git-common): gate per-entry structural stats on the entry-dir signature

Every real git write inside a worktree admin entry (HEAD, index,
config.worktree, locked) goes through a lock file + rename, which moves
the entry directory's own mtime/ctime/size signature. Only `gitdir`
(worktree move/repair) is rewritten in place, and that's already covered
by the periodic ungated backstop (INDEX_BACKSTOP_TICKS). The previous
comment claiming structural leaves "change in place every tick" was
wrong; verified against git 2.55 across checkout, commit, amend, reset,
ref updates, stash, worktree lock/unlock, config --worktree, and index
writes.

Gate all six per-entry stats behind the entry dir's own signature instead
of stat-ing every leaf unconditionally every tick: an unchanged entry now
costs one stat per tick instead of six, and a changed one still costs six
(bounded by change rate, not worktree count). This also fixes the actual
in-flight fan-out: forEachWithConcurrency(entries, 8) previously still
issued 6 stats per in-flight entry (48 real concurrent ops); with the
gate, warm ticks issue ~1 stat per entry, so true in-flight tracks the
concurrency limit directly.

This makes the follow-up adaptive-cadence machinery from the prior commit
unnecessary: the crash-fuse and no-narrow-watch polling fallbacks no
longer need to stretch their own cadence, since a warm sweep across
hundreds of worktrees is now cheap regardless of interval. Revert both
call sites to a fixed pollIntervalMs and delete the adaptive-cadence
option, the split tripwire/sweep cadence, and the seed heuristic — none
of it earns its complexity once the real per-entry cost is fixed at the
source. Per-entry staleness on the crash-fuse path returns to a fixed 2s
+ 250ms debounce instead of the previous 5.4-30s adaptive stretch.

Refs #17828
---
 ...ase-directory-poller-marker-fanout.test.ts |  84 +++++++
 .../ipc/worktree-base-directory-poller.ts     |  37 +--
 .../ipc/worktree-git-common-entry-snapshot.ts |  42 ++--
 .../ipc/worktree-git-common-narrow-watch.ts   |   5 +
 .../ipc/worktree-git-common-polling.test.ts   | 237 ++++++++++++++++++
 src/main/ipc/worktree-git-common-polling.ts   |  35 +--
 src/main/ipc/worktree-git-common-watch.ts     |   2 +
 7 files changed, 395 insertions(+), 47 deletions(-)
 create mode 100644 src/main/ipc/worktree-base-directory-poller-marker-fanout.test.ts
 create mode 100644 src/main/ipc/worktree-git-common-polling.test.ts

diff --git a/src/main/ipc/worktree-base-directory-poller-marker-fanout.test.ts b/src/main/ipc/worktree-base-directory-poller-marker-fanout.test.ts
new file mode 100644
index 00000000000..023a8390ccd
--- /dev/null
+++ b/src/main/ipc/worktree-base-directory-poller-marker-fanout.test.ts
@@ -0,0 +1,84 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { mkdir, mkdtemp, realpath, rm, writeFile } from 'node:fs/promises'
+import type * as NodeFsPromises from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { startWorktreeBaseDirectoryPoller } from './worktree-base-directory-poller'
+import type {
+  WorktreeBaseRepoWatchConfig,
+  WorktreeBaseWatchTarget
+} from './worktree-base-directory-event-filter'
+
+// Why: the backstop full scan stats a `.git` marker per candidate dir; an
+// unbounded fan-out at hundreds of worktrees would queue thousands of `stat`
+// calls on libuv's 4-thread pool (#17828).
+const { concurrency } = vi.hoisted(() => ({ concurrency: { current: 0, peak: 0 } }))
+
+vi.mock('node:fs/promises', async (importOriginal) => {
+  const actual = await importOriginal<typeof NodeFsPromises>()
+  return {
+    ...actual,
+    stat: async (...args: Parameters<typeof actual.stat>) => {
+      concurrency.current += 1
+      concurrency.peak = Math.max(concurrency.peak, concurrency.current)
+      try {
+        return await actual.stat(...args)
+      } finally {
+        concurrency.current -= 1
+      }
+    }
+  }
+})
+
+function makeTarget(path: string): WorktreeBaseWatchTarget {
+  const repoConfig: WorktreeBaseRepoWatchConfig = {
+    repoId: 'repo-1',
+    repoName: 'project',
+    nestWorkspaces: false
+  }
+  return {
+    key: `base:local:${path}`,
+    kind: 'base',
+    path,
+    repos: new Map([[repoConfig.repoId, repoConfig]])
+  }
+}
+
+describe('worktree base directory poller marker fan-out (#17828)', () => {
+  const cleanups: (() => Promise<void>)[] = []
+
+  beforeEach(() => {
+    concurrency.current = 0
+    concurrency.peak = 0
+  })
+
+  afterEach(async () => {
+    await Promise.all(cleanups.splice(0).map((cleanup) => cleanup()))
+  })
+
+  it('bounds concurrent `.git`-marker stats regardless of candidate count', async () => {
+    const root = await realpath(await mkdtemp(join(tmpdir(), 'orca-base-poller-fanout-')))
+    cleanups.push(() => rm(root, { recursive: true, force: true }))
+    const candidateCount = 200
+    for (let i = 0; i < candidateCount; i++) {
+      const worktree = join(root, `wt-${i}`)
+      await mkdir(worktree)
+      await writeFile(join(worktree, '.git'), 'gitdir: elsewhere')
+    }
+
+    const target = makeTarget(root)
+    const poller = await startWorktreeBaseDirectoryPoller(
+      target,
+      () => target.repos,
+      () => {},
+      { pollIntervalMs: 100_000 }
+    )
+    cleanups.push(() => poller.unsubscribe())
+
+    // 200 candidates stated unbounded would peak near 200 concurrent `stat`
+    // calls; bounding the marker probe keeps the peak independent of count —
+    // while still overlapping requests (not serialized one-at-a-time).
+    expect(concurrency.peak).toBeGreaterThan(1)
+    expect(concurrency.peak).toBeLessThan(20)
+  })
+})
diff --git a/src/main/ipc/worktree-base-directory-poller.ts b/src/main/ipc/worktree-base-directory-poller.ts
index 42ee184b811..201d9782fba 100644
--- a/src/main/ipc/worktree-base-directory-poller.ts
+++ b/src/main/ipc/worktree-base-directory-poller.ts
@@ -1,6 +1,8 @@
 import { readdir, stat } from 'node:fs/promises'
+import type { Dirent } from 'node:fs'
 import { join } from 'node:path'
 import { normalizeRuntimePathForComparison } from '../../shared/cross-platform-path'
+import { forEachWithConcurrency } from '../../shared/map-with-concurrency'
 import { isMainWindowVisible, onMainWindowBecameVisible } from '../window/main-window-visibility'
 import type {
   WorktreeBaseRepoWatchConfig,
@@ -92,6 +94,11 @@ export const WORKTREE_BASE_BACKSTOP_TICKS = 15
 // backstop scan cover the pathological case.
 const PENDING_MARKER_MAX_TICKS = 300
 
+// Why: matches the git-common poller's fan-out bound (#17828) — bounded
+// concurrency turns hundreds of serial round trips into a handful of batches
+// without dumping every candidate onto libuv's 4-thread pool at once.
+const MARKER_PROBE_CONCURRENCY = 8
+
 function statSignature(s: { mtimeMs: number; ctimeMs: number; ino: number }): string {
   return `${s.mtimeMs}:${s.ctimeMs}:${s.ino}`
 }
@@ -123,6 +130,14 @@ type BaseSnapshot = {
   gateSignatures: string[]
 }
 
+async function readdirSafe(path: string): Promise<Dirent[]> {
+  try {
+    return await readdir(path, { withFileTypes: true })
+  } catch {
+    return []
+  }
+}
+
 // Depth-1 worktree dirs (flat layout), plus depth-2 dirs under each nested
 // repo's container, mirroring what worktree-base-directory-event-filter
 // matches: `<wt>/.git` completion markers and `<wt>` deletions.
@@ -144,14 +159,9 @@ async function snapshotBase(
       .map((config) => normalizeRuntimePathForComparison(config.repoName))
   )
 
-  let rootEntries
-  try {
-    rootEntries = await readdir(rootPath, { withFileTypes: true })
-  } catch {
-    // Root vanished: an empty snapshot diffs into delete events for every
-    // previously-known worktree dir, matching the old watcher's error path.
-    return { markers, gateDirs, gateSignatures }
-  }
+  // Root vanished or unreadable: readdirSafe yields [], producing the same
+  // empty markers/candidates result as the old watcher's error path.
+  const rootEntries = await readdirSafe(rootPath)
 
   const candidates: string[] = []
   for (const entry of rootEntries) {
@@ -165,12 +175,7 @@ async function snapshotBase(
     if (nestedRepoNames.has(normalizeRuntimePathForComparison(entry.name))) {
       gateDirs.push(entryPath)
       gateSignatures.push(await dirSignature(entryPath))
-      let subEntries
-      try {
-        subEntries = await readdir(entryPath, { withFileTypes: true })
-      } catch {
-        subEntries = []
-      }
+      const subEntries = await readdirSafe(entryPath)
       for (const sub of subEntries) {
         if (sub.isDirectory() || sub.isSymbolicLink()) {
           candidates.push(join(entryPath, sub.name))
@@ -179,9 +184,9 @@ async function snapshotBase(
     }
   }
 
-  for (const dir of candidates) {
+  await forEachWithConcurrency(candidates, MARKER_PROBE_CONCURRENCY, async (dir) => {
     markers.set(dir, await hasGitMarker(dir))
-  }
+  })
   return { markers, gateDirs, gateSignatures }
 }
 
diff --git a/src/main/ipc/worktree-git-common-entry-snapshot.ts b/src/main/ipc/worktree-git-common-entry-snapshot.ts
index d14f4ec8a1d..6dad6e0a048 100644
--- a/src/main/ipc/worktree-git-common-entry-snapshot.ts
+++ b/src/main/ipc/worktree-git-common-entry-snapshot.ts
@@ -39,11 +39,33 @@ export async function snapshotGitCommonEntry(
   previous: GitCommonEntrySnapshot | undefined,
   forceFullScan: boolean
 ): Promise<GitCommonEntrySnapshot> {
-  // Structural leaves change in place every tick; only index uses the entry-dir gate.
+  // Git writes HEAD/index/config.worktree/locked via a lock file + rename inside the
+  // entry dir, so the entry dir's own signature moves on every one of those writes
+  // (verified against git 2.55: checkout, commit, amend, reset, ref updates, stash,
+  // worktree lock/unlock, config --worktree, index writes all move it). The one
+  // in-place exception is `gitdir` (worktree move/repair), which the periodic
+  // forceFullScan backstop (INDEX_BACKSTOP_TICKS) below re-stats regardless of this
+  // gate. Gating all of these leaves on the entry-dir signature turns an unchanged
+  // entry into a single stat per tick instead of stat-ing every leaf every tick.
+  const nextDirSignature = await gitCommonDirectorySignature(entryPath)
+  if (nextDirSignature === 'missing') {
+    return (
+      previous ?? {
+        dirSignature: nextDirSignature,
+        structuralSignatures: new Map(),
+        indexSignature: null,
+        headLogSignature: null
+      }
+    )
+  }
+  const shouldRescan = forceFullScan || !previous || previous.dirSignature !== nextDirSignature
+  if (!shouldRescan) {
+    return previous
+  }
   const structuralSignatures = new Map<string, string>()
-  const [nextDirSignature, headLogSignature] = await Promise.all([
-    gitCommonDirectorySignature(entryPath),
+  const [headLogSignature, indexSignature] = await Promise.all([
     gitCommonFileSignature(join(entryPath, HEAD_LOG_FILE)),
+    gitCommonFileSignature(join(entryPath, INDEX_FILE)),
     Promise.all(
       STRUCTURAL_METADATA_FILES.map(async (name) => {
         const signature = await gitCommonFileSignature(join(entryPath, name))
@@ -53,20 +75,6 @@ export async function snapshotGitCommonEntry(
       })
     )
   ])
-  if (nextDirSignature === 'missing') {
-    return (
-      previous ?? {
-        dirSignature: nextDirSignature,
-        structuralSignatures,
-        indexSignature: null,
-        headLogSignature
-      }
-    )
-  }
-  const shouldReadIndex = forceFullScan || !previous || previous.dirSignature !== nextDirSignature
-  const indexSignature = shouldReadIndex
-    ? await gitCommonFileSignature(join(entryPath, INDEX_FILE))
-    : previous.indexSignature
   return {
     dirSignature: nextDirSignature,
     structuralSignatures,
diff --git a/src/main/ipc/worktree-git-common-narrow-watch.ts b/src/main/ipc/worktree-git-common-narrow-watch.ts
index b60ac9877e8..99e245998a1 100644
--- a/src/main/ipc/worktree-git-common-narrow-watch.ts
+++ b/src/main/ipc/worktree-git-common-narrow-watch.ts
@@ -73,6 +73,11 @@ export async function startGitCommonNarrowWatch(
         .unsubscribe()
         .catch(() => {})
         .then(() =>
+          // Crash fuse tripped: this poller is now the sole change signal until a
+          // future existence-poll upgrade (follow-up: #17878). Its own per-entry
+          // dir-signature gate (worktree-git-common-entry-snapshot.ts) already keeps
+          // an unchanged entry to a single stat, so a fixed `pollIntervalMs` cadence
+          // stays cheap at high worktree counts without needing to stretch itself.
           startGitCommonPolling(
             target.path,
             onEvents,
diff --git a/src/main/ipc/worktree-git-common-polling.test.ts b/src/main/ipc/worktree-git-common-polling.test.ts
new file mode 100644
index 00000000000..179b73e2c33
--- /dev/null
+++ b/src/main/ipc/worktree-git-common-polling.test.ts
@@ -0,0 +1,237 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { mkdir, mkdtemp, rename, rm, writeFile } from 'node:fs/promises'
+import type * as NodeFsPromises from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join, sep } from 'node:path'
+import { startGitCommonPolling } from './worktree-git-common-polling'
+import type {
+  WorktreeBasePollEvent,
+  WorktreePollerWindowVisibility
+} from './worktree-base-directory-poller'
+
+// Why: measure the fan-out this poller issues per scan (peak concurrent `stat`
+// calls, `readdir` call count as a proxy for "a tick ran") without depending on
+// real disk timing (#17828). `entryZeroStatCalls` tracks every stat under a
+// specific pre-existing entry (its dir plus every leaf), used to prove the
+// entry-dir signature gate keeps an unchanged entry to one stat per tick.
+const { statDelayMs, readdirCalls, concurrency, entryZeroStatCalls } = vi.hoisted(() => ({
+  statDelayMs: { current: 0 },
+  readdirCalls: { count: 0 },
+  concurrency: { current: 0, peak: 0 },
+  entryZeroStatCalls: { count: 0 }
+}))
+
+vi.mock('node:fs/promises', async (importOriginal) => {
+  const actual = await importOriginal<typeof NodeFsPromises>()
+  return {
+    ...actual,
+    readdir: (...args: Parameters<typeof actual.readdir>) => {
+      readdirCalls.count += 1
+      return actual.readdir(...args)
+    },
+    stat: async (...args: Parameters<typeof actual.stat>) => {
+      concurrency.current += 1
+      concurrency.peak = Math.max(concurrency.peak, concurrency.current)
+      const path = args[0]
+      const entryZeroSegment = `${sep}wt-0`
+      if (
+        typeof path === 'string' &&
+        (path.endsWith(entryZeroSegment) || path.includes(`${entryZeroSegment}${sep}`))
+      ) {
+        entryZeroStatCalls.count += 1
+      }
+      try {
+        if (statDelayMs.current > 0) {
+          await new Promise((resolve) => setTimeout(resolve, statDelayMs.current))
+        }
+        return await actual.stat(...args)
+      } finally {
+        concurrency.current -= 1
+      }
+    }
+  }
+})
+
+const alwaysVisible: WorktreePollerWindowVisibility = {
+  isWindowVisible: () => true,
+  onWindowBecameVisible: () => () => {}
+}
+
+async function makeCommonDir(entryCount: number): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), 'git-common-polling-test-'))
+  for (let i = 0; i < entryCount; i++) {
+    const entryPath = join(root, 'worktrees', `wt-${i}`)
+    await mkdir(join(entryPath, 'logs'), { recursive: true })
+    await Promise.all([
+      writeFile(join(entryPath, 'HEAD'), 'ref: refs/heads/main\n'),
+      writeFile(join(entryPath, 'gitdir'), `${join(root, `checkout-${i}`, '.git')}\n`),
+      writeFile(join(entryPath, 'index'), Buffer.from([0])),
+      writeFile(join(entryPath, 'logs', 'HEAD'), '0000 aaaa\n')
+    ])
+  }
+  return root
+}
+
+describe('startGitCommonPolling fan-out bounds (#17828)', () => {
+  const cleanups: (() => Promise<void>)[] = []
+  const dirsToRemove: string[] = []
+
+  beforeEach(() => {
+    statDelayMs.current = 0
+    readdirCalls.count = 0
+    concurrency.current = 0
+    concurrency.peak = 0
+    entryZeroStatCalls.count = 0
+  })
+
+  afterEach(async () => {
+    await Promise.all(cleanups.splice(0).map((cleanup) => cleanup()))
+    await Promise.all(
+      dirsToRemove.splice(0).map((dir) => rm(dir, { recursive: true, force: true }))
+    )
+    vi.useRealTimers()
+  })
+
+  it('bounds concurrent per-entry stat fan-out regardless of entry count', async () => {
+    const commonDir = await makeCommonDir(200)
+    dirsToRemove.push(commonDir)
+    const sub = await startGitCommonPolling(commonDir, () => {}, 100_000, alwaysVisible)
+    cleanups.push(() => sub.unsubscribe())
+    // 200 entries x ~6 concurrent structural stats each would peak near 1,200
+    // unbounded; bounding to 8 in-flight entries keeps the peak independent of
+    // entry count instead of scaling with it.
+    expect(concurrency.peak).toBeLessThan(80)
+  })
+
+  it('never overlaps a scan with itself even when ticks fire faster than a scan completes', async () => {
+    const commonDir = await makeCommonDir(10)
+    dirsToRemove.push(commonDir)
+    statDelayMs.current = 20
+    const pollIntervalMs = 5
+    const sub = await startGitCommonPolling(commonDir, () => {}, pollIntervalMs, alwaysVisible)
+    cleanups.push(() => sub.unsubscribe())
+    readdirCalls.count = 0
+    // ~60 would-be 5ms ticks elapse in this window while every stat takes 20ms;
+    // the ticking guard must serialize scans, not launch overlapping ones.
+    await new Promise((resolve) => setTimeout(resolve, 300))
+    expect(readdirCalls.count).toBeLessThan(10)
+  })
+
+  it('costs exactly one stat per tick for an unchanged entry', async () => {
+    const commonDir = await makeCommonDir(1)
+    dirsToRemove.push(commonDir)
+    const pollIntervalMs = 20
+    const sub = await startGitCommonPolling(commonDir, () => {}, pollIntervalMs, alwaysVisible)
+    cleanups.push(() => sub.unsubscribe())
+
+    // Let the bootstrap snapshot (which always fully reads every entry once) settle.
+    await new Promise((resolve) => setTimeout(resolve, pollIntervalMs))
+    readdirCalls.count = 0
+    entryZeroStatCalls.count = 0
+    await vi.waitFor(
+      () => {
+        expect(readdirCalls.count).toBeGreaterThanOrEqual(5)
+      },
+      { timeout: 2_000 }
+    )
+    // Without the entry-dir signature gate, an unchanged entry still costs ~6
+    // stats every tick (HEAD/gitdir/locked/config.worktree/logs/HEAD/index).
+    // With the gate, only the entry dir itself is stat'd once nothing changed —
+    // one stat per tick, in lockstep with the readdir tripwire.
+    expect(entryZeroStatCalls.count).toBeLessThanOrEqual(readdirCalls.count + 1)
+    expect(entryZeroStatCalls.count).toBeGreaterThanOrEqual(readdirCalls.count - 1)
+  })
+
+  it('detects a HEAD rewrite via lock+rename on the next tick', async () => {
+    const commonDir = await makeCommonDir(1)
+    dirsToRemove.push(commonDir)
+    const events: WorktreeBasePollEvent[][] = []
+    const pollIntervalMs = 20
+    const sub = await startGitCommonPolling(
+      commonDir,
+      (batch) => events.push(batch),
+      pollIntervalMs,
+      alwaysVisible
+    )
+    cleanups.push(() => sub.unsubscribe())
+    // Let the bootstrap snapshot settle before mutating.
+    await new Promise((resolve) => setTimeout(resolve, pollIntervalMs))
+
+    const entryDir = join(commonDir, 'worktrees', 'wt-0')
+    const headPath = join(entryDir, 'HEAD')
+    const headLockPath = join(entryDir, 'HEAD.lock')
+    // Every real git ref write goes through a lock file + rename inside the entry
+    // dir (never an in-place overwrite), which moves the entry dir's own signature.
+    await writeFile(headLockPath, 'ref: refs/heads/feature\n')
+    await rename(headLockPath, headPath)
+
+    await vi.waitFor(
+      () => {
+        expect(events.flat()).toContainEqual({ type: 'update', path: headPath })
+      },
+      { timeout: pollIntervalMs * 10 }
+    )
+  })
+
+  it('detects an in-place gitdir rewrite only once the periodic backstop rescans it', async () => {
+    const commonDir = await makeCommonDir(1)
+    dirsToRemove.push(commonDir)
+    const events: WorktreeBasePollEvent[][] = []
+    const pollIntervalMs = 10
+    const sub = await startGitCommonPolling(
+      commonDir,
+      (batch) => events.push(batch),
+      pollIntervalMs,
+      alwaysVisible
+    )
+    cleanups.push(() => sub.unsubscribe())
+    // Let the bootstrap snapshot settle before mutating.
+    await new Promise((resolve) => setTimeout(resolve, pollIntervalMs))
+
+    const entryDir = join(commonDir, 'worktrees', 'wt-0')
+    const gitdirPath = join(entryDir, 'gitdir')
+    // `gitdir` is the one structural leaf git rewrites in place (worktree move/repair),
+    // so the entry dir's own signature never moves — the periodic ungated backstop
+    // (INDEX_BACKSTOP_TICKS = 15) is the only thing that catches it.
+    await writeFile(gitdirPath, `${join(commonDir, 'checkout-moved', '.git')}\n`)
+
+    // Not caught by the next several ticks: the gate stays closed since nothing
+    // moved the entry dir's own signature.
+    await new Promise((resolve) => setTimeout(resolve, pollIntervalMs * 5))
+    expect(events.flat()).not.toContainEqual({ type: 'update', path: gitdirPath })
+
+    // Eventually caught regardless of the gate, once tick 15 forces the periodic backstop.
+    await vi.waitFor(
+      () => {
+        expect(events.flat()).toContainEqual({ type: 'update', path: gitdirPath })
+      },
+      { timeout: pollIntervalMs * 40 }
+    )
+  })
+
+  it('still detects entry add/remove correctly with bounded concurrency', async () => {
+    const commonDir = await makeCommonDir(5)
+    dirsToRemove.push(commonDir)
+    const events: WorktreeBasePollEvent[][] = []
+    const sub = await startGitCommonPolling(
+      commonDir,
+      (batch) => events.push(batch),
+      20,
+      alwaysVisible
+    )
+    cleanups.push(() => sub.unsubscribe())
+
+    const newEntry = join(commonDir, 'worktrees', 'wt-new')
+    await mkdir(join(newEntry, 'logs'), { recursive: true })
+    await writeFile(join(newEntry, 'HEAD'), 'ref: refs/heads/main\n')
+
+    await vi.waitFor(() => {
+      expect(events.flat()).toContainEqual({ type: 'create', path: newEntry })
+    })
+
+    await rm(newEntry, { recursive: true })
+    await vi.waitFor(() => {
+      expect(events.flat()).toContainEqual({ type: 'delete', path: newEntry })
+    })
+  })
+})
diff --git a/src/main/ipc/worktree-git-common-polling.ts b/src/main/ipc/worktree-git-common-polling.ts
index 0418f4a90fd..4b43835a81f 100644
--- a/src/main/ipc/worktree-git-common-polling.ts
+++ b/src/main/ipc/worktree-git-common-polling.ts
@@ -1,5 +1,6 @@
 import { readdir } from 'node:fs/promises'
 import { join } from 'node:path'
+import { forEachWithConcurrency } from '../../shared/map-with-concurrency'
 import { PRIMARY_CHECKOUT_METADATA_FILES } from './worktree-git-common-metadata-files'
 import {
   diffGitCommon,
@@ -23,18 +24,26 @@ import {
 // same way the base poller's backstop rescan does.
 const INDEX_BACKSTOP_TICKS = 15
 
+// Why: an unbounded fan-out across every worktree admin entry queues thousands
+// of ops on libuv's 4-thread default pool, starving every other main-process
+// fs call for the scan's duration (#17828). 8 mirrors the existing
+// head-identity/exact-ref-probe pools — enough to saturate typical local
+// disks without monopolizing the pool. Since snapshotGitCommonEntry's own
+// entry-dir gate (see worktree-git-common-entry-snapshot.ts) keeps most ticks
+// down to 1 stat per unchanged entry, real in-flight is now bounded by this
+// limit rather than limit × per-entry stat count.
+const GIT_COMMON_SNAPSHOT_CONCURRENCY = 8
+
 async function snapshotStatusRefSignatures(
   paths: ReadonlySet<string>
 ): Promise<Map<string, string>> {
   const signatures = new Map<string, string>()
-  await Promise.all(
-    [...paths].map(async (path) => {
-      const signature = await gitCommonFileSignature(path)
-      if (signature !== null) {
-        signatures.set(path, signature)
-      }
-    })
-  )
+  await forEachWithConcurrency([...paths], GIT_COMMON_SNAPSHOT_CONCURRENCY, async (path) => {
+    const signature = await gitCommonFileSignature(path)
+    if (signature !== null) {
+      signatures.set(path, signature)
+    }
+  })
   return signatures
 }
 
@@ -91,12 +100,10 @@ async function snapshotGitCommon(
   }
 
   const entries = new Map<string, GitCommonEntrySnapshot>()
-  await Promise.all(
-    entryPaths.map(async (entryPath) => {
-      const previousEntry = previous?.entries.get(entryPath)
-      entries.set(entryPath, await snapshotGitCommonEntry(entryPath, previousEntry, forceFullScan))
-    })
-  )
+  await forEachWithConcurrency(entryPaths, GIT_COMMON_SNAPSHOT_CONCURRENCY, async (entryPath) => {
+    const previousEntry = previous?.entries.get(entryPath)
+    entries.set(entryPath, await snapshotGitCommonEntry(entryPath, previousEntry, forceFullScan))
+  })
   // Why: the expensive per-entry `index` read stays gated on each entry's own dir signature; onFullScan
   // now reflects an ungated index-metadata backstop fan-out (forceFullScan) — the real periodic cost —
   // rather than the always-run worktrees-dir readdir.
diff --git a/src/main/ipc/worktree-git-common-watch.ts b/src/main/ipc/worktree-git-common-watch.ts
index 9de2c8c3392..8ed696872f7 100644
--- a/src/main/ipc/worktree-git-common-watch.ts
+++ b/src/main/ipc/worktree-git-common-watch.ts
@@ -60,6 +60,8 @@ export async function startGitCommonWatch(
       }
     }
   }
+  // Why: Electron only ships darwin/linux/win32, all covered by NARROW_WATCH_PLATFORMS
+  // above, so this branch is defensive dead code in production, not a reachable fallback.
   return startGitCommonPolling(
     target.path,
     onEvents,

From fdfe354045680a01b3743600362fd37262031af4 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Tue, 1 Sep 2026 18:20:47 -0700
Subject: [PATCH 23/32] test(relay): bind test WebSocket servers to loopback

A control-handshake test that expects a timeout was instead getting
'Unexpected server response: 401' about once in fourteen runs. A slow machine
cannot turn a timeout into a 401 -- that needs a real HTTP response, so the
connection was reaching a different server.

new WebSocketServer({ port: 0 }) binds the wildcard address while the client
dials 127.0.0.1. On macOS those differ, and with SO_REUSEADDR a foreign process
can hold the more specific 127.0.0.1:P and win the connection. Caught live: a
wildcard bind took port 52584, which a running Orca app already held on
loopback, and Orca answered the probe. A listener that checks a token answers
401.

Ten constructions across seven files now pass host: '127.0.0.1', so the
reservation covers the address the client dials and a duplicate bind is refused.

Adds a ratchet, because this is not authors forgetting a convention: all 30+
.listen(0, ...) sites already pass '127.0.0.1', while 7 of 7 ws constructions
did not. ws accepts { port } alone and binds the wildcard silently, so nothing
told them. The guard pins the wildcard count, and pins separately at zero the
option shapes it cannot read -- spreads and variable option objects fail rather
than being exempted, and a recognized-construction floor catches the matcher
going blind, which otherwise reads exactly like a clean tree.

mobile/scripts/mock-server.ts stays on the wildcard deliberately: a phone
reaches it over the LAN.
---
 ...bsocket-server-wildcard-bind-allowlist.txt |  14 ++
 config/scripts/call-site-option-keys.ts       | 204 ++++++++++++++++++
 config/scripts/websocket-server-bind-scan.ts  | 172 +++++++++++++++
 .../websocket-server-loopback-bind.test.ts    | 106 +++++++++
 .../rpc-client-live-recovery.test.ts          |   3 +-
 .../mobile-relay-e2ee.integration.test.ts     |   3 +-
 .../relay/relay-control-client.test.ts        |   7 +-
 src/main/runtime/rpc/relay-transport.test.ts  |   3 +-
 .../src/web/web-runtime-client.test.ts        |   3 +-
 src/shared/remote-runtime-client.test.ts      |  13 +-
 .../remote-runtime-outbound-admission.test.ts |   3 +-
 .../remote-runtime-request-connection.test.ts |   3 +-
 ...mote-runtime-shared-control-test-server.ts |   7 +-
 ...emote-runtime-subscription-request.test.ts |   3 +-
 14 files changed, 529 insertions(+), 15 deletions(-)
 create mode 100644 config/scripts/__fixtures__/websocket-server-wildcard-bind-allowlist.txt
 create mode 100644 config/scripts/call-site-option-keys.ts
 create mode 100644 config/scripts/websocket-server-bind-scan.ts
 create mode 100644 config/scripts/websocket-server-loopback-bind.test.ts

diff --git a/config/scripts/__fixtures__/websocket-server-wildcard-bind-allowlist.txt b/config/scripts/__fixtures__/websocket-server-wildcard-bind-allowlist.txt
new file mode 100644
index 00000000000..4b76622a9f2
--- /dev/null
+++ b/config/scripts/__fixtures__/websocket-server-wildcard-bind-allowlist.txt
@@ -0,0 +1,14 @@
+# Files allowed to construct a `ws` server that binds a port without pinning `host`.
+#
+# `ws` accepts `{ port }` alone and silently binds the wildcard address. A server
+# reached over 127.0.0.1 must pin `host: '127.0.0.1'`, or a foreign loopback
+# listener can hold the same port and answer in its place -- which is how
+# relay-control-client.test.ts came to fail with a real HTTP 401 in a test that
+# was simulating silence.
+#
+# This list only shrinks. Adding a line also requires raising the pin in
+# websocket-server-loopback-bind.test.ts, which is deliberate friction.
+
+# Deliberate, not drift: this mock is dialled by a phone on the LAN, so it has to
+# be reachable on a real interface. A loopback bind would make it unreachable.
+mobile/scripts/mock-server.ts
diff --git a/config/scripts/call-site-option-keys.ts b/config/scripts/call-site-option-keys.ts
new file mode 100644
index 00000000000..dff3a971c45
--- /dev/null
+++ b/config/scripts/call-site-option-keys.ts
@@ -0,0 +1,204 @@
+/**
+ * Read the top-level option keys of a call's object-literal argument out of raw
+ * source text.
+ *
+ * Text rather than an AST because typescript@7 no longer ships the classic
+ * compiler API and every installed parser is a transitive dependency. The
+ * tradeoff is handled by refusing to guess: any shape this cannot read comes
+ * back as `unreadable` with a reason, and callers must treat that as a failure
+ * rather than as an absence of keys.
+ */
+
+export type CallOptionKeys =
+  | { readonly readable: true; readonly keys: readonly string[] }
+  | { readonly readable: false; readonly reason: string }
+
+type ScanState = 'code' | 'line' | 'block' | 'single' | 'double' | 'template'
+
+function closesString(state: ScanState, current: string): boolean {
+  return (
+    (state === 'single' && current === "'") ||
+    (state === 'double' && current === '"') ||
+    (state === 'template' && current === '`')
+  )
+}
+
+function opensNonCode(current: string, next: string | undefined): ScanState | null {
+  if (current === '/' && next === '/') {
+    return 'line'
+  }
+  if (current === '/' && next === '*') {
+    return 'block'
+  }
+  if (current === "'") {
+    return 'single'
+  }
+  if (current === '"') {
+    return 'double'
+  }
+  if (current === '`') {
+    return 'template'
+  }
+  return null
+}
+
+/**
+ * Text between an open paren and its match, tracking strings and comments so a
+ * brace inside either cannot unbalance the count. Null when it never closes.
+ */
+function balancedArguments(text: string, openIndex: number): string | null {
+  let depth = 0
+  let state: ScanState = 'code'
+  for (let index = openIndex; index < text.length; index++) {
+    const current = text[index]
+    const next = text[index + 1]
+    if (state === 'code') {
+      const opened = opensNonCode(current, next)
+      if (opened) {
+        state = opened
+        if (opened === 'line' || opened === 'block') {
+          index++
+        }
+      } else if (current === '(' || current === '{' || current === '[') {
+        depth++
+      } else if (current === ')' || current === '}' || current === ']') {
+        depth--
+        if (depth === 0) {
+          return text.slice(openIndex + 1, index)
+        }
+        if (depth < 0) {
+          return null
+        }
+      }
+      continue
+    }
+    if (state === 'line') {
+      if (current === '\n') {
+        state = 'code'
+      }
+      continue
+    }
+    if (state === 'block') {
+      if (current === '*' && next === '/') {
+        state = 'code'
+        index++
+      }
+      continue
+    }
+    if (current === '\\') {
+      index++
+      continue
+    }
+    // Brace tracking inside `${}` would need its own depth; templates never
+    // appear as options, so report one as unreadable instead of guessing.
+    if (state === 'template' && current === '$' && next === '{') {
+      return null
+    }
+    if (closesString(state, current)) {
+      state = 'code'
+    }
+  }
+  return null
+}
+
+/** Keys at depth 0 of an object literal body, with anything non-identifier kept verbatim. */
+function objectLiteralKeys(body: string): string[] {
+  const keys: string[] = []
+  let depth = 0
+  let state: ScanState = 'code'
+  let inValue = false
+  let token = ''
+  const flush = (): void => {
+    const name = token.trim()
+    token = ''
+    if (name && depth === 0) {
+      keys.push(name)
+    }
+  }
+  for (let index = 0; index < body.length; index++) {
+    const current = body[index]
+    const next = body[index + 1]
+    if (state === 'code') {
+      const opened = opensNonCode(current, next)
+      if (opened) {
+        state = opened
+        if (opened === 'line' || opened === 'block') {
+          index++
+        }
+      } else if (current === '(' || current === '{' || current === '[') {
+        depth++
+        if (!inValue) {
+          token += current
+        }
+      } else if (current === ')' || current === '}' || current === ']') {
+        depth--
+        if (!inValue) {
+          token += current
+        }
+      } else if (current === ':' && depth === 0 && !inValue) {
+        flush()
+        inValue = true
+      } else if (current === ',' && depth === 0) {
+        // A shorthand or a spread ends here having never seen a colon.
+        if (inValue) {
+          inValue = false
+          token = ''
+        } else {
+          flush()
+        }
+      } else if (!inValue) {
+        token += current
+      }
+      continue
+    }
+    if (state === 'line') {
+      if (current === '\n') {
+        state = 'code'
+      }
+      continue
+    }
+    if (state === 'block') {
+      if (current === '*' && next === '/') {
+        state = 'code'
+        index++
+      }
+      continue
+    }
+    if (current === '\\') {
+      index++
+      continue
+    }
+    if (closesString(state, current)) {
+      state = 'code'
+    }
+  }
+  if (!inValue) {
+    flush()
+  }
+  return keys
+}
+
+/**
+ * Option keys of the call whose argument list opens at `parenIndex`, or the
+ * reason the shape could not be read. Spreads and computed keys land in the
+ * latter: either can carry a key this would otherwise report as absent.
+ */
+export function readCallOptionKeys(text: string, parenIndex: number): CallOptionKeys {
+  const args = balancedArguments(text, parenIndex)
+  if (args === null) {
+    return { readable: false, reason: 'argument list never closes' }
+  }
+  if (!args.trim()) {
+    return { readable: false, reason: 'called with no options argument' }
+  }
+  const trimmed = args.trim()
+  if (!trimmed.startsWith('{') || !trimmed.endsWith('}')) {
+    return { readable: false, reason: 'options are not an object literal' }
+  }
+  const keys = objectLiteralKeys(trimmed.slice(1, -1))
+  const unreadable = keys.find((key) => !/^[A-Za-z_$][\w$]*$/.test(key))
+  if (unreadable !== undefined) {
+    return { readable: false, reason: `unreadable option key \`${unreadable}\`` }
+  }
+  return { readable: true, keys }
+}
diff --git a/config/scripts/websocket-server-bind-scan.ts b/config/scripts/websocket-server-bind-scan.ts
new file mode 100644
index 00000000000..9054f8cc38e
--- /dev/null
+++ b/config/scripts/websocket-server-bind-scan.ts
@@ -0,0 +1,172 @@
+import { readFileSync, readdirSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { readCallOptionKeys } from './call-site-option-keys'
+
+/**
+ * Locate every `new WebSocketServer(...)` in the tree and say, for each, whether
+ * it pins a bind address.
+ *
+ * `ws` accepts `{ port }` alone and silently binds the wildcard address, so a
+ * server the caller then dials on 127.0.0.1 sits at a port a foreign loopback
+ * listener can also hold -- and the more specific listener wins the connection,
+ * answering in that server's place.
+ *
+ * Anything unreadable is reported as `opaque` rather than skipped. A matcher
+ * that silently exempts the shapes it fails to parse is worse than no matcher,
+ * because it reads as coverage.
+ */
+
+export type BindSite = { path: string; line: number }
+export type OpaqueSite = BindSite & { reason: string }
+
+export type WebSocketServerBindScan = {
+  filesScanned: number
+  /** Every construction recognized, however it was then classified. */
+  constructions: number
+  /** Binds a port with no `host`: reachable at an address the dialer never named. */
+  wildcardBound: BindSite[]
+  /** Shape that could not be read; never treated as safe. */
+  opaque: OpaqueSite[]
+  /** Binds a port and pins `host`. */
+  loopbackBound: BindSite[]
+  /** No `port`: attaches to a server that owns the bind itself. */
+  attached: BindSite[]
+}
+
+const IGNORED_DIRECTORIES = new Set([
+  'node_modules',
+  'dist',
+  'out',
+  'build',
+  '.git',
+  '__fixtures__',
+  'coverage',
+  // Full snapshots of older releases; their bind sites are not this tree's to fix.
+  '.cross-version-checkouts'
+])
+const SCANNED_EXTENSIONS = /\.(?:ts|tsx|mts|cts)$/
+const SCANNED_ROOTS = ['src', 'mobile', 'config', 'tests']
+const WS_IMPORT_HINT = /from\s*['"]ws['"]/
+
+function collectSourceFiles(root: string, found: string[] = []): string[] {
+  let entries: ReturnType<typeof readdirSync<{ withFileTypes: true }>>
+  try {
+    entries = readdirSync(root, { withFileTypes: true })
+  } catch {
+    return found
+  }
+  for (const entry of entries) {
+    if (IGNORED_DIRECTORIES.has(entry.name)) {
+      continue
+    }
+    const full = join(root, entry.name)
+    if (entry.isDirectory()) {
+      collectSourceFiles(full, found)
+    } else if (SCANNED_EXTENSIONS.test(entry.name)) {
+      found.push(full)
+    }
+  }
+  return found
+}
+
+/** Local names bound to ws's server class, following `as` aliases and namespace imports. */
+function webSocketServerNames(text: string): { direct: Set<string>; namespaces: Set<string> } {
+  const direct = new Set<string>()
+  const namespaces = new Set<string>()
+  // One statement at a time: a pattern reaching for `from 'ws'` would swallow
+  // every import above it and lose the specifier names in the blob.
+  for (const match of text.matchAll(/\bimport\b([\s\S]*?)\bfrom\s*(['"])([^'"]+)\2/g)) {
+    if (match[3] !== 'ws') {
+      continue
+    }
+    const clause = match[1]
+    if (/^\s*type\b/.test(clause)) {
+      continue
+    }
+    const namespace = clause.match(/\*\s+as\s+([A-Za-z_$][\w$]*)/)
+    if (namespace) {
+      namespaces.add(namespace[1])
+    }
+    const named = clause.match(/\{([\s\S]*)\}/)
+    if (!named) {
+      continue
+    }
+    for (const specifier of named[1].split(',')) {
+      const trimmed = specifier.trim()
+      if (!trimmed || /^type\s/.test(trimmed)) {
+        continue
+      }
+      const parts = trimmed.split(/\s+as\s+/)
+      // `Server` is ws's own alias for WebSocketServer.
+      if (parts[0].trim() === 'WebSocketServer' || parts[0].trim() === 'Server') {
+        direct.add((parts[1] ?? parts[0]).trim())
+      }
+    }
+  }
+  return { direct, namespaces }
+}
+
+function classify(
+  scan: WebSocketServerBindScan,
+  site: BindSite,
+  text: string,
+  paren: number
+): void {
+  const options = readCallOptionKeys(text, paren)
+  if (!options.readable) {
+    scan.opaque.push({ ...site, reason: options.reason })
+    return
+  }
+  if (!options.keys.includes('port')) {
+    scan.attached.push(site)
+    return
+  }
+  if (!options.keys.includes('host')) {
+    scan.wildcardBound.push(site)
+    return
+  }
+  scan.loopbackBound.push(site)
+}
+
+export function scanWebSocketServerBinds(repoRoot: string): WebSocketServerBindScan {
+  const files = SCANNED_ROOTS.flatMap((directory) => collectSourceFiles(join(repoRoot, directory)))
+  const scan: WebSocketServerBindScan = {
+    filesScanned: files.length,
+    constructions: 0,
+    wildcardBound: [],
+    opaque: [],
+    loopbackBound: [],
+    attached: []
+  }
+  for (const file of files) {
+    const text = readFileSync(file, 'utf8')
+    // Filter on the import, not on the class name: `Server as Wss` never spells
+    // WebSocketServer, and keying on that name silently skipped the whole alias.
+    if (!WS_IMPORT_HINT.test(text)) {
+      continue
+    }
+    const { direct, namespaces } = webSocketServerNames(text)
+    if (!direct.size && !namespaces.size) {
+      continue
+    }
+    const path = relative(repoRoot, file).split('\\').join('/')
+    const patterns = [
+      ...[...direct].map((name) => new RegExp(`\\bnew\\s+${name}\\s*\\(`, 'g')),
+      ...[...namespaces].map(
+        (name) => new RegExp(`\\bnew\\s+${name}\\.(?:WebSocketServer|Server)\\s*\\(`, 'g')
+      )
+    ]
+    for (const pattern of patterns) {
+      for (const match of text.matchAll(pattern)) {
+        scan.constructions++
+        const line = text.slice(0, match.index).split('\n').length
+        classify(scan, { path, line }, text, match.index + match[0].length - 1)
+      }
+    }
+  }
+  return scan
+}
+
+export function formatSites(sites: readonly BindSite[]): string[] {
+  return sites.map((site) => `${site.path}:${site.line}`)
+}
diff --git a/config/scripts/websocket-server-loopback-bind.test.ts b/config/scripts/websocket-server-loopback-bind.test.ts
new file mode 100644
index 00000000000..9f32f8eda1a
--- /dev/null
+++ b/config/scripts/websocket-server-loopback-bind.test.ts
@@ -0,0 +1,106 @@
+import { readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { formatSites, scanWebSocketServerBinds } from './websocket-server-bind-scan'
+
+/**
+ * Hold the bind address at the tree level rather than per call site.
+ *
+ * Every one of the ~30 `.listen(0, ...)` calls in this repo already passes
+ * '127.0.0.1'; 7 of 7 `new WebSocketServer({ port })` calls did not. Authors know
+ * the convention -- `ws` just never asks, because `{ port }` alone binds the
+ * wildcard without a word. That silence is what this test replaces.
+ *
+ * The allowlist only shrinks. A new wildcard bind fails here even where it looks
+ * harmless today, because harmless-looking is exactly what the seven were.
+ */
+/** The ratchet, held as data so it reads as the list it is. */
+const WILDCARD_BIND_ALLOWLIST: readonly string[] = readFileSync(
+  join(__dirname, '__fixtures__', 'websocket-server-wildcard-bind-allowlist.txt'),
+  'utf8'
+)
+  .split('\n')
+  .map((line) => line.trim())
+  .filter((line) => line.length > 0 && !line.startsWith('#'))
+
+/**
+ * The true count of constructions that bind a port without pinning a host.
+ *
+ * May only ever be DECREASED, and only by pinning a host. Raising it is never
+ * the fix.
+ */
+const WILDCARD_BIND_PIN = 1
+
+/**
+ * A floor under the constructions the scanner still recognizes.
+ *
+ * This is the guard against the scanner going blind: an import pattern it stops
+ * following reports zero offenders and reads exactly like a clean tree. During
+ * development a single wrong regex dropped this from 24 to 3.
+ */
+const RECOGNIZED_CONSTRUCTION_FLOOR = 20
+
+describe('WebSocketServer loopback bind boundary', () => {
+  const repoRoot = resolve(__dirname, '..', '..')
+  const scan = scanWebSocketServerBinds(repoRoot)
+  const offenders = scan.wildcardBound.map((site) => site.path)
+
+  it('scans a plausible number of files', () => {
+    // A broken root or extension list would make the guard silently vacuous.
+    expect(scan.filesScanned).toBeGreaterThan(5_000)
+  })
+
+  it('still recognizes the known construction sites', () => {
+    expect(
+      scan.constructions,
+      `Only ${scan.constructions} WebSocketServer constructions were recognized; the floor is ` +
+        `${RECOGNIZED_CONSTRUCTION_FLOOR}. The scanner has probably stopped following an import ` +
+        'shape rather than the tree having lost that many servers.'
+    ).toBeGreaterThanOrEqual(RECOGNIZED_CONSTRUCTION_FLOOR)
+  })
+
+  it('can read the options of every construction it found', () => {
+    // An unreadable shape is never assumed safe: it could be hiding a host, or
+    // hiding the absence of one. Rewrite it as a plain object literal.
+    expect(
+      scan.opaque.map((site) => `${site.path}:${site.line} -- ${site.reason}`),
+      'WebSocketServer options that this guard cannot read.'
+    ).toEqual([])
+  })
+
+  it('has no wildcard-bound server outside the allowlist', () => {
+    const unlisted = scan.wildcardBound.filter(
+      (site) => !WILDCARD_BIND_ALLOWLIST.includes(site.path)
+    )
+    expect(
+      formatSites(unlisted),
+      "New WebSocketServer that binds a port without a host. Pass host: '127.0.0.1' so a foreign " +
+        'loopback listener cannot claim the port and answer in its place.'
+    ).toEqual([])
+  })
+
+  it('has no stale allowlist entry', () => {
+    // Why this direction matters too: an entry left behind after the file was
+    // fixed hides the next regression in that same path.
+    const stale = WILDCARD_BIND_ALLOWLIST.filter((path) => !offenders.includes(path))
+    expect(stale, 'Allowlist entry no longer binds the wildcard — delete the line.').toEqual([])
+  })
+
+  it('holds the wildcard-bind count at the pin', () => {
+    // Bounding by the allowlist's own length would prove nothing: the two move
+    // together, so appending a line to silence a failure would keep the bound
+    // satisfied. The pin is a literal so that widening takes a second edit.
+    expect(
+      scan.wildcardBound.length,
+      `${scan.wildcardBound.length} constructions bind the wildcard; the pin is ` +
+        `${WILDCARD_BIND_PIN}. Never raise the pin -- pass host: '127.0.0.1' instead.`
+    ).toBeLessThanOrEqual(WILDCARD_BIND_PIN)
+    // A pin left above reality is how a ratchet rots: it re-opens room for the
+    // next wildcard bind to land for free.
+    expect(
+      scan.wildcardBound.length,
+      `Only ${scan.wildcardBound.length} constructions bind the wildcard. Lower ` +
+        `WILDCARD_BIND_PIN to ${scan.wildcardBound.length} to keep the ground you just took.`
+    ).toBeGreaterThanOrEqual(WILDCARD_BIND_PIN)
+  })
+})
diff --git a/mobile/src/transport/rpc-client-live-recovery.test.ts b/mobile/src/transport/rpc-client-live-recovery.test.ts
index 471a53be740..bef276f918d 100644
--- a/mobile/src/transport/rpc-client-live-recovery.test.ts
+++ b/mobile/src/transport/rpc-client-live-recovery.test.ts
@@ -59,7 +59,8 @@ function e2eeDecrypt(encrypted: string, sharedKey: Uint8Array): string | null {
 // fail with EADDRINUSE; the full scenario restarts on the captured port
 // because the client keeps reconnecting to its original URL.
 function startServer(port = 0): Promise<WebSocketServer> {
-  const wss = new WebSocketServer({ port })
+  // host must match the 127.0.0.1 clients dial: a wildcard bind lets a foreign loopback listener claim the port and answer here.
+  const wss = new WebSocketServer({ host: '127.0.0.1', port })
   wss.on('connection', (ws: ServerSocket) => {
     let sharedKey: Uint8Array | null = null
     let authenticated = false
diff --git a/src/main/runtime/relay/mobile-relay-e2ee.integration.test.ts b/src/main/runtime/relay/mobile-relay-e2ee.integration.test.ts
index 1f2b50e0648..bf9ec2ce431 100644
--- a/src/main/runtime/relay/mobile-relay-e2ee.integration.test.ts
+++ b/src/main/runtime/relay/mobile-relay-e2ee.integration.test.ts
@@ -61,7 +61,8 @@ describe('desktop relay E2EE integration', () => {
   })
 
   it('splices a simulated phone through CloudRelayTransport with real NaCl E2EE v2', async () => {
-    const relay = new WebSocketServer({ port: 0, perMessageDeflate: false })
+    // host must match the 127.0.0.1 clients dial: a wildcard bind lets a foreign loopback listener claim the port and answer here.
+    const relay = new WebSocketServer({ host: '127.0.0.1', port: 0, perMessageDeflate: false })
     servers.push(relay)
     await new Promise<void>((resolve) => relay.once('listening', resolve))
     const address = relay.address()
diff --git a/src/main/runtime/relay/relay-control-client.test.ts b/src/main/runtime/relay/relay-control-client.test.ts
index a1ad5c03482..2975b67e631 100644
--- a/src/main/runtime/relay/relay-control-client.test.ts
+++ b/src/main/runtime/relay/relay-control-client.test.ts
@@ -99,7 +99,8 @@ describe('RelayControlClient', () => {
   })
 
   it('rejects a control handshake that never receives a proof response', async () => {
-    const server = new WebSocketServer({ port: 0, perMessageDeflate: false })
+    // host must match the 127.0.0.1 clients dial: a wildcard bind lets a foreign loopback listener claim the port and answer here.
+    const server = new WebSocketServer({ host: '127.0.0.1', port: 0, perMessageDeflate: false })
     servers.push(server)
     await new Promise<void>((resolve) => server.once('listening', resolve))
     const address = server.address()
@@ -129,7 +130,7 @@ describe('RelayControlClient', () => {
   })
 
   it('settles an opening control immediately when ownership closes', async () => {
-    const server = new WebSocketServer({ port: 0, perMessageDeflate: false })
+    const server = new WebSocketServer({ host: '127.0.0.1', port: 0, perMessageDeflate: false })
     servers.push(server)
     await new Promise<void>((resolve) => server.once('listening', resolve))
     const address = server.address()
@@ -165,7 +166,7 @@ describe('RelayControlClient', () => {
   })
 
   it('proves the host key and drives control/data commands without URL credentials', async () => {
-    const server = new WebSocketServer({ port: 0, perMessageDeflate: false })
+    const server = new WebSocketServer({ host: '127.0.0.1', port: 0, perMessageDeflate: false })
     servers.push(server)
     await new Promise<void>((resolve) => server.once('listening', resolve))
     const address = server.address()
diff --git a/src/main/runtime/rpc/relay-transport.test.ts b/src/main/runtime/rpc/relay-transport.test.ts
index 8b7303ed805..21b520c8c9e 100644
--- a/src/main/runtime/rpc/relay-transport.test.ts
+++ b/src/main/runtime/rpc/relay-transport.test.ts
@@ -28,7 +28,8 @@ describe('CloudRelayTransport', () => {
   })
 
   it('authenticates one query-free host-data socket and forwards messages verbatim', async () => {
-    const server = new WebSocketServer({ port: 0, perMessageDeflate: false })
+    // host must match the 127.0.0.1 clients dial: a wildcard bind lets a foreign loopback listener claim the port and answer here.
+    const server = new WebSocketServer({ host: '127.0.0.1', port: 0, perMessageDeflate: false })
     servers.push(server)
     await new Promise<void>((resolve) => server.once('listening', resolve))
     const address = server.address()
diff --git a/src/renderer/src/web/web-runtime-client.test.ts b/src/renderer/src/web/web-runtime-client.test.ts
index 1aa36f06d0f..7373ede6b8c 100644
--- a/src/renderer/src/web/web-runtime-client.test.ts
+++ b/src/renderer/src/web/web-runtime-client.test.ts
@@ -658,7 +658,8 @@ describe('WebRuntimeClient', () => {
     vi.stubGlobal('WebSocket', WebSocket)
     const serverKeys = generateKeyPair()
     const frame = new Uint8Array([9, 8, 7])
-    const wss = new WebSocketServer({ port: 0 })
+    // host must match the 127.0.0.1 clients dial: a wildcard bind lets a foreign loopback listener claim the port and answer here.
+    const wss = new WebSocketServer({ host: '127.0.0.1', port: 0 })
     const sockets = new Set<WebSocket>()
     wss.on('connection', (socket) => {
       sockets.add(socket)
diff --git a/src/shared/remote-runtime-client.test.ts b/src/shared/remote-runtime-client.test.ts
index 3e3bba921ea..d7a76417e84 100644
--- a/src/shared/remote-runtime-client.test.ts
+++ b/src/shared/remote-runtime-client.test.ts
@@ -539,7 +539,12 @@ async function createSubscriptionServer(
   const nextAuth = new Promise<unknown>((resolve) => {
     resolveAuth = resolve
   })
-  const wss = new WebSocketServer({ port: 0, autoPong: options.disableAutoPong !== true })
+  // host must match the 127.0.0.1 clients dial: a wildcard bind lets a foreign loopback listener claim the port and answer here.
+  const wss = new WebSocketServer({
+    host: '127.0.0.1',
+    port: 0,
+    autoPong: options.disableAutoPong !== true
+  })
   servers.push(wss)
 
   wss.on('connection', (ws) => {
@@ -625,7 +630,7 @@ async function createClosingServer(
   reason: string
 ): Promise<{ pairing: PairingOffer }> {
   const serverKeyPair = generateKeyPair()
-  const wss = new WebSocketServer({ port: 0 })
+  const wss = new WebSocketServer({ host: '127.0.0.1', port: 0 })
   servers.push(wss)
   wss.on('connection', (ws) => {
     ws.close(code, reason)
@@ -649,7 +654,7 @@ async function createClosingServer(
 
 async function createInvalidHandshakeServer(): Promise<{ pairing: PairingOffer }> {
   const serverKeyPair = generateKeyPair()
-  const wss = new WebSocketServer({ port: 0 })
+  const wss = new WebSocketServer({ host: '127.0.0.1', port: 0 })
   servers.push(wss)
   wss.on('connection', (ws) => {
     ws.once('message', () => ws.send(JSON.stringify({ type: 'not_orca' })))
@@ -680,7 +685,7 @@ async function createOneShotServer(
   } = {}
 ): Promise<{ pairing: PairingOffer }> {
   const serverKeyPair = generateKeyPair()
-  const wss = new WebSocketServer({ port: 0 })
+  const wss = new WebSocketServer({ host: '127.0.0.1', port: 0 })
   servers.push(wss)
 
   wss.on('connection', (ws) => {
diff --git a/src/shared/remote-runtime-outbound-admission.test.ts b/src/shared/remote-runtime-outbound-admission.test.ts
index f536549ca46..eb5f902a16a 100644
--- a/src/shared/remote-runtime-outbound-admission.test.ts
+++ b/src/shared/remote-runtime-outbound-admission.test.ts
@@ -352,7 +352,8 @@ describe('remote runtime outbound admission', () => {
 
 async function createServer(): Promise<{ pairing: PairingOffer; server: WebSocketServer }> {
   const keyPair = generateKeyPair()
-  const server = new WebSocketServer({ port: 0 })
+  // host must match the 127.0.0.1 clients dial: a wildcard bind lets a foreign loopback listener claim the port and answer here.
+  const server = new WebSocketServer({ host: '127.0.0.1', port: 0 })
   servers.push(server)
   await new Promise<void>((resolve) => server.once('listening', resolve))
   const address = server.address() as AddressInfo
diff --git a/src/shared/remote-runtime-request-connection.test.ts b/src/shared/remote-runtime-request-connection.test.ts
index 4d812322ba0..eb8f0b06e89 100644
--- a/src/shared/remote-runtime-request-connection.test.ts
+++ b/src/shared/remote-runtime-request-connection.test.ts
@@ -98,7 +98,8 @@ async function createServer(): Promise<TestServer> {
   const requests: unknown[] = []
   const auths: unknown[] = []
   let connectionCount = 0
-  const wss = new WebSocketServer({ port: 0 })
+  // host must match the 127.0.0.1 clients dial: a wildcard bind lets a foreign loopback listener claim the port and answer here.
+  const wss = new WebSocketServer({ host: '127.0.0.1', port: 0 })
   servers.push(wss)
 
   wss.on('connection', (ws) => {
diff --git a/src/shared/remote-runtime-shared-control-test-server.ts b/src/shared/remote-runtime-shared-control-test-server.ts
index 33b535c8405..0e4adb1a69c 100644
--- a/src/shared/remote-runtime-shared-control-test-server.ts
+++ b/src/shared/remote-runtime-shared-control-test-server.ts
@@ -60,7 +60,12 @@ export async function createSharedControlTestServer(
   const delayedResponses: (() => void)[] = []
   let connectionCount = 0
   let closedAfterFirstStreamingResponse = false
-  const wss = new WebSocketServer({ port: 0, autoPong: options.disableAutoPong !== true })
+  // host must match the 127.0.0.1 clients dial: a wildcard bind lets a foreign loopback listener claim the port and answer here.
+  const wss = new WebSocketServer({
+    host: '127.0.0.1',
+    port: 0,
+    autoPong: options.disableAutoPong !== true
+  })
   servers.push(wss)
 
   wss.on('connection', (ws) => {
diff --git a/src/shared/remote-runtime-subscription-request.test.ts b/src/shared/remote-runtime-subscription-request.test.ts
index dabc51e6a24..14f904308cc 100644
--- a/src/shared/remote-runtime-subscription-request.test.ts
+++ b/src/shared/remote-runtime-subscription-request.test.ts
@@ -262,7 +262,8 @@ async function createServer(options: ServerOptions = {}): Promise<{
   const nextRequest = new Promise<unknown>((resolve) => {
     resolveRequest = resolve
   })
-  const wss = new WebSocketServer({ port: 0 })
+  // host must match the 127.0.0.1 clients dial: a wildcard bind lets a foreign loopback listener claim the port and answer here.
+  const wss = new WebSocketServer({ host: '127.0.0.1', port: 0 })
   servers.push(wss)
   wss.on('connection', (ws) => {
     let sharedKey: Uint8Array | null = null

From d7123591cebd103658c6d5c8f601eebe1dc0cb3e Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Tue, 1 Sep 2026 19:06:44 -0700
Subject: [PATCH 24/32] perf(git): pack the loose refs Orca's own fetches leave
 behind (#17857)

* perf(git): pack the loose refs Orca's own fetches leave behind

Orca strips git's auto-maintenance off every fetch it issues
(GIT_FETCH_SKIP_AUTO_MAINTENANCE_CONFIG_ARGS) and never compensated, so
nothing in an Orca-driven checkout ever packs refs. One real machine
reached 36,574 loose refs, where `git show-ref -- main` costs 5.2s and
every worktree create pays for it.

Add an idle-time, per-repo `git pack-refs --all --prune`, armed by the
fetches that create the debt. It runs only after ten minutes of quiet on
that repo, only above 1000 loose refs (probed with a walk bounded by that
threshold, not by the backlog), one at a time across the whole app, at
the background admission tier, and never while an agent is working, a
create is prepared or in flight, a worktree removal is deleting refs, the
app is quitting, or the machine is on battery. A user who set
`maintenance.auto=false` or `gc.auto=0` has opted out.

Measured on a 36,001-loose-ref fixture (macOS/APFS, git 2.44):
`show-ref` 5.5-12.2s -> 30-49ms, `for-each-ref` 4.0-10.8s -> 43-48ms.

Also fixes a pre-existing bug the split exposed: `--path-format=absolute`
is ignored before git 2.31, and taking rev-parse's stdout raw collapsed
every repo on such a host onto one fetch-serialization key.

Refs #17828

* perf(git): make idle ref maintenance preemptible and cheaper to probe

The idle veto was one-directional: it stopped a pack from starting during
a create, removal, or agent work, but nothing stopped those from starting
during a pack. A user-clicked Fetch, a branch delete, or a worktree
removal that needed `packed-refs.lock` mid-rewrite could fail with
`unable to create packed-refs.lock` -- a git error with no visible cause.

Make the pack cancellable end to end. An AbortSignal now reaches the
`pack-refs` child and both pre-pack probes, and `pause()` aborts what is
running, waits for it to actually stop, and holds a suspension count so
nothing new starts until the caller releases. Every entry point that
deletes a ref takes that pause: gitFetch, gitPull, gitFastForward,
removeWorktree, forceDeleteLocalBranch, prepareWorktreeCreateCheckout,
addWorktree. Five more triggers close the rest of the window: battery
drop, window focus, quit, the attempt deadline, and any other git command
queueing for an admission slot.

Judge a pack by re-probing the backlog rather than by the child's exit
code. Measured in the field: another Orca session moved a branch
mid-pack, git reported `cannot lock ref`, skipped that ref and packed the
rest -- 36,688 loose refs down to 3. On a machine running several
sessions that is the normal case, and retrying it would be wrong.

Probe with one batched `readdir` per directory instead of streaming
`opendir`, which issues a thread-pool round trip every 32 entries: 177ms
-> 23ms on a real 36,600-ref repository, with half the event-loop lag.
The walk stays strictly sequential so it can never occupy more than one
of libuv's four filesystem threads.

`PackRefsLockOwnership` makes a lock left by SIGKILL attributable, and
only reclaims one when a marker exists, the lock is older than any
pack-refs could run for, and the recorded process is gone.

Refs #17828

* fix(git): wait out the packed-refs lock instead of killing the pack

Measured on Git 2.55/APFS with 37k loose refs: a full `pack-refs --all
--prune` takes 23-32s but holds `packed-refs.lock` for only 0.03-1.37s of
it. The other ~95% is the prune phase, during which a concurrent `fetch
--prune`, `branch -D` or `update-ref` succeeds every time -- per-ref locks
last microseconds and git retries for `core.filesRefLockTimeout`.

So the abort-on-everything design was strictly harmful. SIGTERM into the
prune loop strands an empty `refs/**/*.lock` about one time in five
(9/30, 5/40, 6/30 kills): `tempfile.c` opens the lock O_EXCL before
`activate_tempfile()` links it into the list the signal handler walks,
and a pack does ~36k lock cycles. Afterwards `update-ref -d` on that ref
fails with `cannot lock ref ... File exists`, permanently. On Windows
`taskkill /f` never runs git's handlers at all, so an abort inside the
rewrite strands `packed-refs.lock` every time.

Never signal the child. `packRefs` no longer takes an abort signal; it
polls `packed-refs.lock` and reports the window through a
`PackedRefsLockReporter`. `pause()` resolves when the lock is released --
bounded, and free during the prune -- while the suspension counter still
blocks new attempts. Battery and window-focus become do-not-start rather
than stop-what-is-running, and quit waits for the lock and lets the child
finish orphaned.

For strands that already exist, `PackRefsLockOwnership` now also reclaims
`refs/**/*.lock` under the same three conditions plus a 0-byte check, and
a lock carrying our own not-yet-reclaimable marker records `locked` with
a 30min retry instead of the 6h failure cooldown -- so a Windows strand
self-heals in half an hour rather than six.

Reverts the git admission-scheduler event bus, which existed only to
drive the abort this removes.

Refs #17828

* test(git): make the ref-maintenance waits survive a loaded runner

CI shard 4/8 failed on `restarts every armed countdown when the user does
ref work themselves`, which passes locally. The `until()` helper spun a
fixed 200 event-loop turns and then returned silently, so on a contended
runner the filesystem probe had not finished and the assertion that
followed failed with an unrelated message.

Bound the wait by wall clock instead and throw a named error, which
immediately exposed a second latent bug: the single-flight test's second
wait could never succeed, because the deferred repo's retry is on a faked
`setTimeout` that spinning the real loop never advances. It had been
passing only because the old helper gave up quietly. Add a timer-aware
variant for those, and have the countdown test await a signal the fake
pack resolves rather than polling at all.

Verified stable across five sequential runs and once under load average
32 with six concurrent suites.

Refs #17828
---
 src/main/agent-awake-service.ts               |   5 +
 src/main/cli/cli-command-installation.ts      |   8 +-
 src/main/cli/cli-installer.ts                 |   8 +-
 src/main/cli/wsl-cli-installer.ts             |   4 +-
 src/main/git/canonical-repo-key.test.ts       |  78 +++
 src/main/git/canonical-repo-key.ts            |  72 +++
 .../git/local-repo-ref-maintenance.test.ts    | 182 ++++++
 src/main/git/local-repo-ref-maintenance.ts    | 272 +++++++++
 src/main/git/pack-refs-lock-ownership.test.ts | 192 +++++++
 src/main/git/pack-refs-lock-ownership.ts      | 202 +++++++
 src/main/git/remote.ts                        |  56 +-
 .../git/repo-ref-maintenance-real-git.test.ts | 290 ++++++++++
 src/main/git/worktree-add.ts                  |  21 +-
 src/main/git/worktree-branch-removal.ts       |   7 +-
 src/main/git/worktree-create-preparation.ts   |  81 +--
 src/main/git/worktree-removal.ts              |  10 +-
 src/main/ipc/repos-create.test.ts             |   5 +-
 src/main/ipc/worktrees.ts                     |   7 +-
 .../ipc/worktrees/worktree-ipc-context.ts     |  15 +
 src/main/repo-maintenance-idle-gate.test.ts   | 134 +++++
 src/main/repo-maintenance-idle-gate.ts        |  67 +++
 src/main/runtime/fetch-remote-cache.test.ts   |   8 +-
 .../runtime-remote-fetch-controller.ts        |  56 +-
 ...ntime-remote-fetch-ref-maintenance.test.ts | 145 +++++
 src/main/startup/main-process-observers.ts    |   5 +
 src/main/startup/main-process-quit.ts         |  18 +
 src/main/startup/main-process-state.ts        |   2 +
 src/main/worktree-create-preparation.ts       |   5 +
 src/shared/git-binary-compatibility.test.ts   |  33 ++
 src/shared/loose-ref-count.test.ts            | 119 ++++
 src/shared/loose-ref-count.ts                 |  80 +++
 src/shared/packed-refs-lock-gate.ts           |  43 ++
 src/shared/repo-ref-maintenance-policy.ts     | 166 ++++++
 src/shared/repo-ref-maintenance.test.ts       | 530 ++++++++++++++++++
 src/shared/repo-ref-maintenance.ts            | 366 ++++++++++++
 35 files changed, 3197 insertions(+), 95 deletions(-)
 create mode 100644 src/main/git/canonical-repo-key.test.ts
 create mode 100644 src/main/git/canonical-repo-key.ts
 create mode 100644 src/main/git/local-repo-ref-maintenance.test.ts
 create mode 100644 src/main/git/local-repo-ref-maintenance.ts
 create mode 100644 src/main/git/pack-refs-lock-ownership.test.ts
 create mode 100644 src/main/git/pack-refs-lock-ownership.ts
 create mode 100644 src/main/git/repo-ref-maintenance-real-git.test.ts
 create mode 100644 src/main/repo-maintenance-idle-gate.test.ts
 create mode 100644 src/main/repo-maintenance-idle-gate.ts
 create mode 100644 src/main/runtime/runtime-remote-fetch-ref-maintenance.test.ts
 create mode 100644 src/shared/loose-ref-count.test.ts
 create mode 100644 src/shared/loose-ref-count.ts
 create mode 100644 src/shared/packed-refs-lock-gate.ts
 create mode 100644 src/shared/repo-ref-maintenance-policy.ts
 create mode 100644 src/shared/repo-ref-maintenance.test.ts
 create mode 100644 src/shared/repo-ref-maintenance.ts

diff --git a/src/main/agent-awake-service.ts b/src/main/agent-awake-service.ts
index 29e866d27f2..b79612e2b9c 100644
--- a/src/main/agent-awake-service.ts
+++ b/src/main/agent-awake-service.ts
@@ -117,6 +117,11 @@ export class AgentAwakeService {
     }
   }
 
+  /** Agents this runtime has seen working recently, independent of the awake setting. */
+  getWorkingAgentCount(): number {
+    return this.getEligibleRunningStatusCount()
+  }
+
   subscribe(listener: (status: ComputerAwakeStatus) => void): () => void {
     this.statusListeners.add(listener)
     return () => this.statusListeners.delete(listener)
diff --git a/src/main/cli/cli-command-installation.ts b/src/main/cli/cli-command-installation.ts
index 5b277bd8c62..fbabc3bf6dd 100644
--- a/src/main/cli/cli-command-installation.ts
+++ b/src/main/cli/cli-command-installation.ts
@@ -35,7 +35,9 @@ export class CliCommandInstallation extends CliCommandInspection {
 
     const inspected = await this.inspectStableSymlink(commandPath, launcherPath)
     if (inspected.status.state === 'conflict') {
-      throw new Error(`Refusing to replace non-Orca command at ${commandPath}. Remove it and register again if it is no longer needed.`)
+      throw new Error(
+        `Refusing to replace non-Orca command at ${commandPath}. Remove it and register again if it is no longer needed.`
+      )
     }
     if (inspected.status.state === 'installed') {
       return
@@ -54,7 +56,9 @@ export class CliCommandInstallation extends CliCommandInspection {
 
     if (!(await capturedExpectedEntry(quarantine, inspected))) {
       await this.restoreQuarantinedCommand(quarantine, commandPath)
-      throw new Error(`Refusing to replace non-Orca command at ${commandPath}. Remove it and register again if it is no longer needed.`)
+      throw new Error(
+        `Refusing to replace non-Orca command at ${commandPath}. Remove it and register again if it is no longer needed.`
+      )
     }
 
     try {
diff --git a/src/main/cli/cli-installer.ts b/src/main/cli/cli-installer.ts
index 3c832df5078..d95e1649ac0 100644
--- a/src/main/cli/cli-installer.ts
+++ b/src/main/cli/cli-installer.ts
@@ -116,7 +116,9 @@ export class CliInstaller extends CliPathRegistration {
       throw new Error(initialStatus.detail ?? 'CLI registration is unavailable on this build.')
     }
     if (initialStatus.state === 'conflict') {
-      throw new Error(`Refusing to replace non-Orca command at ${initialStatus.commandPath}. Remove it and register again if it is no longer needed.`)
+      throw new Error(
+        `Refusing to replace non-Orca command at ${initialStatus.commandPath}. Remove it and register again if it is no longer needed.`
+      )
     }
     const extractedRoot = await this.ensureLinuxAppImagePayload()
     const status = extractedRoot
@@ -126,7 +128,9 @@ export class CliInstaller extends CliPathRegistration {
       throw new Error(status.detail ?? 'CLI registration is unavailable on this build.')
     }
     if (status.state === 'conflict') {
-      throw new Error(`Refusing to replace non-Orca command at ${status.commandPath}. Remove it and register again if it is no longer needed.`)
+      throw new Error(
+        `Refusing to replace non-Orca command at ${status.commandPath}. Remove it and register again if it is no longer needed.`
+      )
     }
 
     // eslint-disable-next-line unicorn/prefer-ternary -- Why: the install path performs async side effects and is easier to audit as an explicit branch than as an awaited ternary.
diff --git a/src/main/cli/wsl-cli-installer.ts b/src/main/cli/wsl-cli-installer.ts
index f8362fddc66..484ed4f9bc3 100644
--- a/src/main/cli/wsl-cli-installer.ts
+++ b/src/main/cli/wsl-cli-installer.ts
@@ -207,7 +207,9 @@ export class WslCliInstaller {
       throw new Error(status.detail ?? 'WSL CLI registration is unavailable.')
     }
     if (status.state === 'conflict') {
-      throw new Error(`Refusing to replace non-Orca command at ${status.commandPath}. Remove it and register again if it is no longer needed.`)
+      throw new Error(
+        `Refusing to replace non-Orca command at ${status.commandPath}. Remove it and register again if it is no longer needed.`
+      )
     }
 
     await this.run(
diff --git a/src/main/git/canonical-repo-key.test.ts b/src/main/git/canonical-repo-key.test.ts
new file mode 100644
index 00000000000..87965bcaed6
--- /dev/null
+++ b/src/main/git/canonical-repo-key.test.ts
@@ -0,0 +1,78 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const gitExecFileAsyncMock = vi.hoisted(() => vi.fn())
+
+vi.mock('./runner', async (importOriginal) => ({
+  ...((await importOriginal()) as Record<string, unknown>),
+  gitExecFileAsync: gitExecFileAsyncMock
+}))
+
+import {
+  _resetCanonicalRepoKeyCacheForTests,
+  getCanonicalRepoKey,
+  readGitCommonDir
+} from './canonical-repo-key'
+
+beforeEach(() => {
+  _resetCanonicalRepoKeyCacheForTests()
+  gitExecFileAsyncMock.mockReset()
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+describe('readGitCommonDir', () => {
+  it('reads the absolute answer modern Git gives', () => {
+    expect(readGitCommonDir('/repo/.git\n', '/repo/worktrees/a')).toBe('/repo/.git')
+  })
+
+  it('drops the flag Git older than 2.31 echoes back, and resolves the relative answer', () => {
+    // Without this every repository on such a host would answer `.git` and collide.
+    expect(readGitCommonDir('--path-format=absolute\n.git\n', '/repo')).toBe('/repo/.git')
+  })
+
+  it('resolves a WSL answer in Git execution space, not against the UNC path', () => {
+    expect(readGitCommonDir('.git\n', '//wsl$/Ubuntu/home/dev/repo')).toBe('/home/dev/repo/.git')
+  })
+
+  it('tolerates CRLF and blank lines', () => {
+    expect(readGitCommonDir('\r\n/repo/.git\r\n', '/repo')).toBe('/repo/.git')
+  })
+
+  it('returns undefined when Git printed nothing usable', () => {
+    expect(readGitCommonDir('\n', '/repo')).toBeUndefined()
+  })
+})
+
+describe('getCanonicalRepoKey', () => {
+  it('gives every worktree of one repository the same key', async () => {
+    gitExecFileAsyncMock.mockResolvedValue({ stdout: '/repo/.git\n', stderr: '' })
+
+    await expect(getCanonicalRepoKey('/repo')).resolves.toBe('local::/repo/.git')
+    await expect(getCanonicalRepoKey('/repo/worktrees/a')).resolves.toBe('local::/repo/.git')
+  })
+
+  it('scopes the key to the execution host', async () => {
+    gitExecFileAsyncMock.mockResolvedValue({ stdout: '/home/dev/repo/.git\n', stderr: '' })
+
+    await expect(
+      getCanonicalRepoKey('//wsl$/Ubuntu/home/dev/repo', { wslDistro: 'Ubuntu' })
+    ).resolves.toBe('wsl:Ubuntu::/home/dev/repo/.git')
+  })
+
+  it('caches so repeated arming costs no subprocess', async () => {
+    gitExecFileAsyncMock.mockResolvedValue({ stdout: '/repo/.git\n', stderr: '' })
+
+    await getCanonicalRepoKey('/repo')
+    await getCanonicalRepoKey('/repo')
+
+    expect(gitExecFileAsyncMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('falls back to the caller path when Git cannot answer', async () => {
+    gitExecFileAsyncMock.mockRejectedValue(new Error('not a git repository'))
+
+    await expect(getCanonicalRepoKey('/not-a-repo')).resolves.toBe('local::/not-a-repo')
+  })
+})
diff --git a/src/main/git/canonical-repo-key.ts b/src/main/git/canonical-repo-key.ts
new file mode 100644
index 00000000000..1b06423bdc9
--- /dev/null
+++ b/src/main/git/canonical-repo-key.ts
@@ -0,0 +1,72 @@
+import { toWslExecutionSpace } from '../../shared/wsl-paths'
+import { gitExecFileAsync } from './runner'
+import { resolveRevParsePath } from './worktree-path-comparison'
+
+/**
+ * One repository on one execution host, named by its Git common dir.
+ *
+ * Shared by the fetch controller (which serializes fetches on it) and idle ref
+ * maintenance (which scopes all of its state to it), so both agree on what "the
+ * same repo" means across every worktree that points at it.
+ */
+
+export type CanonicalRepoKeyOptions = { wslDistro?: string }
+
+const CACHE_MAX = 512
+const cache = new Map<string, string>()
+
+/**
+ * Git < 2.31 ignores `--path-format=absolute`: it echoes the unrecognized flag,
+ * exits 0, and prints a relative `.git`. Taking the raw stdout there would give
+ * every repository on the host the same key.
+ */
+export function readGitCommonDir(stdout: string, repoPath: string): string | undefined {
+  const commonDir = stdout
+    .split('\n')
+    .map((line) => (line.endsWith('\r') ? line.slice(0, -1) : line))
+    .findLast((line) => line.length > 0 && !line.startsWith('-'))
+  return commonDir ? resolveRevParsePath(toWslExecutionSpace(repoPath), commonDir) : undefined
+}
+
+function remember(cacheKey: string, value: string): string {
+  cache.delete(cacheKey)
+  cache.set(cacheKey, value)
+  while (cache.size > CACHE_MAX) {
+    const oldest = cache.keys().next()
+    if (oldest.done) {
+      break
+    }
+    cache.delete(oldest.value)
+  }
+  return value
+}
+
+/** `${runtimeKey}::${gitCommonDir}`, falling back to the caller's path. */
+export async function getCanonicalRepoKey(
+  repoPath: string,
+  options: CanonicalRepoKeyOptions = {}
+): Promise<string> {
+  const runtimeKey = options.wslDistro ? `wsl:${options.wslDistro}` : 'local'
+  const cacheKey = `${runtimeKey}::${repoPath}`
+  const cached = cache.get(cacheKey)
+  if (cached !== undefined) {
+    return remember(cacheKey, cached)
+  }
+  try {
+    const { stdout } = await gitExecFileAsync(
+      ['rev-parse', '--path-format=absolute', '--git-common-dir'],
+      { cwd: repoPath, ...options }
+    )
+    const commonDir = readGitCommonDir(stdout, repoPath)
+    if (commonDir) {
+      return remember(cacheKey, `${runtimeKey}::${commonDir}`)
+    }
+  } catch {
+    // The caller path remains a safe serialization key when canonicalization fails.
+  }
+  return remember(cacheKey, cacheKey)
+}
+
+export function _resetCanonicalRepoKeyCacheForTests(): void {
+  cache.clear()
+}
diff --git a/src/main/git/local-repo-ref-maintenance.test.ts b/src/main/git/local-repo-ref-maintenance.test.ts
new file mode 100644
index 00000000000..f6a411733c3
--- /dev/null
+++ b/src/main/git/local-repo-ref-maintenance.test.ts
@@ -0,0 +1,182 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const gitExecFileAsyncMock = vi.hoisted(() => vi.fn())
+const readRepoCommonDirFromGitMock = vi.hoisted(() => vi.fn())
+
+vi.mock('./runner', async (importOriginal) => ({
+  ...((await importOriginal()) as Record<string, unknown>),
+  gitExecFileAsync: gitExecFileAsyncMock
+}))
+
+vi.mock('./worktree-list-reader', async (importOriginal) => ({
+  ...((await importOriginal()) as Record<string, unknown>),
+  readRepoCommonDirFromGit: readRepoCommonDirFromGitMock
+}))
+
+import { _resetCanonicalRepoKeyCacheForTests } from './canonical-repo-key'
+import {
+  _resetLocalRepoRefMaintenanceForTests,
+  armLocalRepoRefMaintenance,
+  createLocalRepoRefMaintenanceTarget,
+  getLocalRepoRefMaintenance,
+  setRepoMaintenanceActivityProbe,
+  withRepoRefMaintenancePaused
+} from './local-repo-ref-maintenance'
+
+const NO_ABORT = new AbortController().signal
+
+function target(wslDistro?: string): ReturnType<typeof createLocalRepoRefMaintenanceTarget> {
+  return createLocalRepoRefMaintenanceTarget({
+    key: 'local::/repo/.git',
+    repoPath: wslDistro ? '//wsl$/Ubuntu/home/dev/repo' : '/repo',
+    ...(wslDistro ? { wslDistro } : {})
+  })
+}
+
+beforeEach(() => {
+  gitExecFileAsyncMock.mockReset()
+  readRepoCommonDirFromGitMock.mockReset()
+  delete process.env.ORCA_DISABLE_REPO_REF_MAINTENANCE
+  _resetCanonicalRepoKeyCacheForTests()
+  _resetLocalRepoRefMaintenanceForTests()
+})
+
+afterEach(() => {
+  delete process.env.ORCA_DISABLE_REPO_REF_MAINTENANCE
+  _resetLocalRepoRefMaintenanceForTests()
+  vi.restoreAllMocks()
+})
+
+describe('local repo ref maintenance target', () => {
+  it('never hands the pack child an abort signal', async () => {
+    // Killing a `pack-refs` strands a `refs/**` lock about one time in five, and
+    // on Windows a force-kill inside the rewrite strands `packed-refs.lock`
+    // every time. The child must always be allowed to finish.
+    readRepoCommonDirFromGitMock.mockResolvedValue('/repo/.git')
+    gitExecFileAsyncMock.mockResolvedValue({ stdout: '', stderr: '' })
+
+    await target().packRefs({ setHeld: () => {} })
+
+    const packCall = gitExecFileAsyncMock.mock.calls.find(
+      ([argv]) => (argv as string[])[0] === 'pack-refs'
+    )
+    expect(packCall?.[1]).not.toHaveProperty('signal')
+  })
+
+  it('runs pack-refs at the background tier with a long deadline', async () => {
+    gitExecFileAsyncMock.mockResolvedValue({ stdout: '', stderr: '' })
+
+    await target().packRefs({ setHeld: () => {} })
+
+    expect(gitExecFileAsyncMock).toHaveBeenCalledWith(
+      ['pack-refs', '--all', '--prune'],
+      expect.objectContaining({ cwd: '/repo', admissionTier: 'background', timeout: 15 * 60_000 })
+    )
+  })
+
+  it('reads either Git auto-maintenance opt-out, and unset keys as consent', async () => {
+    for (const stdout of [
+      'maintenance.auto false\n',
+      'gc.auto 0\n',
+      'gc.auto 6700\nmaintenance.auto false\n'
+    ]) {
+      gitExecFileAsyncMock.mockResolvedValue({ stdout, stderr: '' })
+      await expect(target().isOptedOut?.(NO_ABORT)).resolves.toBe(true)
+    }
+
+    gitExecFileAsyncMock.mockResolvedValue({
+      stdout: 'maintenance.auto true\ngc.auto 6700\n',
+      stderr: ''
+    })
+    await expect(target().isOptedOut?.(NO_ABORT)).resolves.toBe(false)
+
+    // `git config --get-regexp` exits non-zero when nothing matches.
+    gitExecFileAsyncMock.mockRejectedValue(new Error('exit 1'))
+    await expect(target().isOptedOut?.(NO_ABORT)).resolves.toBe(false)
+  })
+
+  it('walks the POSIX refs directory for a native repo', async () => {
+    readRepoCommonDirFromGitMock.mockResolvedValue('/repo/.git')
+
+    await expect(target().resolveRefsDirectory(NO_ABORT)).resolves.toBe('/repo/.git/refs')
+  })
+
+  it('translates a WSL repo answer back to the UNC path the main process can open', async () => {
+    // Git answers in its own execution space, which for WSL is a Linux path.
+    readRepoCommonDirFromGitMock.mockResolvedValue('/home/dev/repo/.git')
+
+    await expect(target('Ubuntu').resolveRefsDirectory(NO_ABORT)).resolves.toBe(
+      '\\\\wsl.localhost\\Ubuntu\\home\\dev\\repo\\.git\\refs'
+    )
+  })
+
+  it('reports an unresolvable repository rather than guessing a path', async () => {
+    readRepoCommonDirFromGitMock.mockResolvedValue(undefined)
+
+    await expect(target().resolveRefsDirectory(NO_ABORT)).resolves.toBeUndefined()
+  })
+})
+
+describe('local repo ref maintenance scheduling', () => {
+  it('schedules nothing when the kill switch is set', () => {
+    process.env.ORCA_DISABLE_REPO_REF_MAINTENANCE = '1'
+    const arm = vi.spyOn(getLocalRepoRefMaintenance(), 'arm')
+
+    armLocalRepoRefMaintenance({ key: 'local::/repo/.git', repoPath: '/repo' })
+
+    expect(arm).not.toHaveBeenCalled()
+  })
+
+  it('arms through the shared single-flight instance otherwise', () => {
+    const arm = vi.spyOn(getLocalRepoRefMaintenance(), 'arm')
+
+    armLocalRepoRefMaintenance({ key: 'local::/repo/.git', repoPath: '/repo' })
+
+    expect(arm).toHaveBeenCalledTimes(1)
+  })
+
+  it('is free when nothing has ever been armed', async () => {
+    // The common case by far: no timers, no instance, no reason to pay anything.
+    await expect(withRepoRefMaintenancePaused('git-fetch', async () => 'done')).resolves.toBe(
+      'done'
+    )
+  })
+
+  it('holds the window shut for the duration of ref-touching work', async () => {
+    readRepoCommonDirFromGitMock.mockResolvedValue('/repo/.git')
+    _resetLocalRepoRefMaintenanceForTests({ quietPeriodMs: 1, looseRefThreshold: 0 })
+    setRepoMaintenanceActivityProbe(() => false)
+    const maintenance = getLocalRepoRefMaintenance()
+    const packRefs = vi.fn(async () => {})
+    maintenance.arm({
+      key: 'local::/repo/.git',
+      resolveRefsDirectory: async () => '/repo/.git/refs',
+      packRefs
+    })
+
+    await withRepoRefMaintenancePaused('branch-delete', async () => {
+      await new Promise((resolve) => setTimeout(resolve, 25))
+      expect(packRefs).not.toHaveBeenCalled()
+    })
+
+    await vi.waitFor(() => expect(packRefs).toHaveBeenCalledTimes(1))
+  })
+
+  it('routes the app activity probe into the shared instance', async () => {
+    readRepoCommonDirFromGitMock.mockResolvedValue('/repo/.git')
+    let busy = true
+    setRepoMaintenanceActivityProbe(() => busy)
+    const maintenance = getLocalRepoRefMaintenance()
+    const packRefs = vi.fn(async () => {})
+
+    maintenance.arm({
+      key: 'local::/repo/.git',
+      resolveRefsDirectory: async () => '/repo/.git/refs',
+      packRefs
+    })
+    await maintenance.whenAttemptSettled()
+
+    expect(packRefs).not.toHaveBeenCalled()
+    busy = false
+  })
+})
diff --git a/src/main/git/local-repo-ref-maintenance.ts b/src/main/git/local-repo-ref-maintenance.ts
new file mode 100644
index 00000000000..e84f7d1ae30
--- /dev/null
+++ b/src/main/git/local-repo-ref-maintenance.ts
@@ -0,0 +1,272 @@
+import { posix, win32 } from 'node:path'
+import { isWindowsAbsolutePathLike } from '../../shared/cross-platform-path'
+import { RepoRefMaintenance } from '../../shared/repo-ref-maintenance'
+import {
+  PACK_REFS_ARGS,
+  PACK_REFS_TIMEOUT_MS,
+  RefMaintenanceRepoLocked,
+  type PackedRefsLockReporter,
+  type RepoRefMaintenanceOptions,
+  type RepoRefMaintenanceTarget
+} from '../../shared/repo-ref-maintenance-policy'
+import { isWslUncPath, toWindowsWslPath } from '../../shared/wsl-paths'
+import { withSpan } from '../observability/tracer'
+import { PackRefsLockOwnership } from './pack-refs-lock-ownership'
+import { gitExecFileAsync } from './runner'
+import { readRepoCommonDirFromGit } from './worktree-list-reader'
+
+/**
+ * Main-process wiring for idle loose-ref packing on the local execution host
+ * (native and WSL).
+ *
+ * SSH-hosted repos are deliberately out of scope: the execution host owns
+ * anything that touches execution, so maintaining them means running host-side
+ * on the relay, which today has neither admission control nor spans. Keying all
+ * state by execution host is what keeps this path from reaching across.
+ */
+
+export type RepoMaintenanceActivityProbe = () => boolean
+
+const REPO_BUSY_PROBE_MAX = 64
+
+let activityProbe: RepoMaintenanceActivityProbe | null = null
+let shared: RepoRefMaintenance | null = null
+// Why keyed here rather than captured in the target: a repo can be armed from
+// the fetch controller or from a user-initiated fetch, and every arming must see
+// the same "this repo has work in flight" answer, not whichever closure was last.
+const repoBusyProbes = new Map<string, () => boolean>()
+
+/** Register the owner of "this repo has a fetch in flight" for `key`. */
+export function setRepoRefMaintenanceBusyProbe(key: string, probe: () => boolean): void {
+  repoBusyProbes.delete(key)
+  repoBusyProbes.set(key, probe)
+  while (repoBusyProbes.size > REPO_BUSY_PROBE_MAX) {
+    const oldest = repoBusyProbes.keys().next()
+    if (oldest.done) {
+      break
+    }
+    repoBusyProbes.delete(oldest.value)
+  }
+}
+
+/**
+ * Register the app-wide "do not start maintenance now" signal. Owned by the
+ * main entry point because the inputs (live agents, battery, quit) are not
+ * visible from the git layer.
+ */
+export function setRepoMaintenanceActivityProbe(probe: RepoMaintenanceActivityProbe | null): void {
+  activityProbe = probe
+}
+
+/** Support escape hatch: kills the sweep without touching the user's git config. */
+function isDisabled(): boolean {
+  return process.env.ORCA_DISABLE_REPO_REF_MAINTENANCE === '1'
+}
+
+function localMaintenanceOptions(): RepoRefMaintenanceOptions {
+  return {
+    // Fail closed: without the app-level gate installed we cannot see agents,
+    // creates, or battery, and running blind is worse than not running.
+    isBusy: () => activityProbe?.() ?? true,
+    observe: (attempt) =>
+      withSpan('repo.ref_maintenance', (span) => attempt(span), {
+        attributes: { kind: 'git', 'repo.maintenance_host': 'local' }
+      }),
+    onError: (error) => {
+      console.warn('[repo-ref-maintenance] attempt failed:', error)
+    }
+  }
+}
+
+export function getLocalRepoRefMaintenance(): RepoRefMaintenance {
+  shared ??= new RepoRefMaintenance(localMaintenanceOptions())
+  return shared
+}
+
+/**
+ * Cancels every armed timer and waits out any `packed-refs` rewrite in progress.
+ *
+ * Deliberately does not kill the child. A pack orphaned by the app quitting
+ * finishes on its own; a pack signalled mid-prune strands a ref lock about one
+ * time in five, and on Windows a force-kill inside the rewrite strands
+ * `packed-refs.lock` every time -- which blocks every later ref deletion.
+ */
+export function disposeLocalRepoRefMaintenance(): Promise<void> {
+  const settling = shared?.awaitPackedRefsLockRelease() ?? Promise.resolve()
+  shared?.dispose()
+  shared = null
+  repoBusyProbes.clear()
+  return settling
+}
+
+/**
+ * Hold every repository open while `run` touches refs.
+ *
+ * A ref deletion needs `packed-refs.lock`, which a running pack holds only while
+ * it rewrites the file -- 0.03-1.37s of a 23-32s run. Waiting that out turns the
+ * collision into a short pause. Cancelling the pack instead would strand a
+ * `refs/**` lock about one time in five, which Git never clears, so the ref
+ * stays undeletable indefinitely.
+ */
+export async function withRepoRefMaintenancePaused<T>(
+  reason: string,
+  run: () => Promise<T>
+): Promise<T> {
+  // Taken unconditionally rather than only when something is already armed: a
+  // fetch inside `run` can arm the sweep, and one counter bump against an idle
+  // instance costs a microtask. This can rebuild the instance after the
+  // quit-time dispose; harmless, because a fresh one has no armed timers and its
+  // activity probe is gone, so it fails closed.
+  const release = await getLocalRepoRefMaintenance().pause(reason)
+  try {
+    return await run()
+  } finally {
+    release()
+  }
+}
+
+/** Wait out a `packed-refs` rewrite without holding the window open. For shutdown. */
+export function awaitPackedRefsLockRelease(): Promise<void> {
+  return shared ? shared.awaitPackedRefsLockRelease() : Promise.resolve()
+}
+
+/**
+ * Count user-initiated ref work as activity and restart every armed countdown.
+ *
+ * Deliberately not keyed to a repo: resolving one would cost a `rev-parse` on a
+ * path the user is waiting on, and a manual fetch or pull says the user is at
+ * the keyboard, which is a reason to defer every repository.
+ */
+export function postponeRepoRefMaintenance(): void {
+  shared?.postponeAll()
+}
+
+/** `overrides` preseeds the shared instance so a test can shorten the quiet period. */
+export function _resetLocalRepoRefMaintenanceForTests(
+  overrides?: Partial<RepoRefMaintenanceOptions>
+): void {
+  shared?.dispose()
+  shared = overrides ? new RepoRefMaintenance({ ...localMaintenanceOptions(), ...overrides }) : null
+  activityProbe = null
+  repoBusyProbes.clear()
+}
+
+/**
+ * Git reports the common dir in its own execution space, so a WSL repo answers
+ * with a Linux path the Windows main process cannot open. Translate it back to
+ * the UNC spelling for the dirent walk; the walk reads directories, not files,
+ * so the handful of round trips stays cheap even over the share.
+ */
+function refsDirectoryForMainProcess(commonDir: string, wslDistro: string | undefined): string {
+  if (wslDistro && !isWslUncPath(commonDir) && !isWindowsAbsolutePathLike(commonDir)) {
+    return win32.join(toWindowsWslPath(commonDir, wslDistro), 'refs')
+  }
+  // Decided by path syntax, not by platform: `win32.isAbsolute` accepts POSIX paths too.
+  return (isWindowsAbsolutePathLike(commonDir) ? win32 : posix).join(commonDir, 'refs')
+}
+
+/**
+ * `maintenance.auto=false` and `gc.auto=0` are the two knobs a user reaches for
+ * to tell Git to stop maintaining a repository on its own. Orca sets both on its
+ * own fetches, but only as per-invocation `-c` flags, so this probe sees the
+ * user's persisted config and never Orca's own suppression.
+ */
+export function isGitAutoMaintenanceDisabled(configOutput: string): boolean {
+  return configOutput
+    .split('\n')
+    .map((line) => line.trim())
+    .some((line) => line === 'maintenance.auto false' || line === 'gc.auto 0')
+}
+
+/**
+ * The common dir in the spelling the main process can open.
+ *
+ * Derived from the converted refs path, not the raw one: a WSL answer arrives as
+ * a Linux path but converts to a UNC path with no `/` in it, so choosing the
+ * path flavour before conversion collapses the whole thing to `.`.
+ */
+function gitCommonDirForMainProcess(commonDir: string, wslDistro: string | undefined): string {
+  const refs = refsDirectoryForMainProcess(commonDir, wslDistro)
+  return (isWindowsAbsolutePathLike(refs) ? win32 : posix).dirname(refs)
+}
+
+export type LocalRepoRefMaintenanceTargetArgs = {
+  /** `${runtimeKey}::${gitCommonDir}` -- already scoped to the execution host. */
+  readonly key: string
+  readonly repoPath: string
+  readonly wslDistro?: string
+}
+
+/**
+ * Record a write to this repo and restart its quiet-period countdown. The only
+ * entry point callers need: the kill switch is honoured before anything is
+ * scheduled, so a disabled build arms no timers at all.
+ */
+export function armLocalRepoRefMaintenance(args: LocalRepoRefMaintenanceTargetArgs): void {
+  if (isDisabled()) {
+    return
+  }
+  getLocalRepoRefMaintenance().arm(createLocalRepoRefMaintenanceTarget(args))
+}
+
+export function createLocalRepoRefMaintenanceTarget(
+  args: LocalRepoRefMaintenanceTargetArgs
+): RepoRefMaintenanceTarget {
+  const gitOptions = args.wslDistro ? { wslDistro: args.wslDistro } : {}
+  // The engine always probes before it packs, so the pack reuses this answer
+  // rather than spending a second rev-parse on the same repository.
+  let commonDir: string | undefined
+  const resolveCommonDir = async (signal?: AbortSignal): Promise<string | undefined> => {
+    commonDir ??= await readRepoCommonDirFromGit(args.repoPath, {
+      ...gitOptions,
+      ...(signal ? { signal } : {})
+    })
+    return commonDir
+  }
+  return {
+    key: args.key,
+    isBusy: () => repoBusyProbes.get(args.key)?.() ?? false,
+    async resolveRefsDirectory(signal: AbortSignal) {
+      const resolved = await resolveCommonDir(signal)
+      return resolved ? refsDirectoryForMainProcess(resolved, args.wslDistro) : undefined
+    },
+    async isOptedOut(signal: AbortSignal) {
+      try {
+        const { stdout } = await gitExecFileAsync(
+          ['config', '--get-regexp', '^(maintenance\\.auto|gc\\.auto)$'],
+          { cwd: args.repoPath, ...gitOptions, admissionTier: 'background', signal }
+        )
+        return isGitAutoMaintenanceDisabled(stdout)
+      } catch {
+        // Neither key set is the common case and exits non-zero; that is consent.
+        return false
+      }
+    },
+    async packRefs(lock: PackedRefsLockReporter) {
+      const resolved = await resolveCommonDir()
+      const owner = resolved
+        ? new PackRefsLockOwnership(gitCommonDirForMainProcess(resolved, args.wslDistro))
+        : null
+      const claim = owner ? await owner.claim() : { ok: true as const }
+      if (!claim.ok) {
+        throw new RefMaintenanceRepoLocked(claim.reason)
+      }
+      // Report the rewrite window rather than accepting a signal. A pack that is
+      // killed mid-prune strands a `refs/**` lock about one time in five, and
+      // Git never clears those; waiting out the window costs at most ~1.4s.
+      const watch = owner?.watchLock((held) => lock.setHeld(held))
+      try {
+        await gitExecFileAsync([...PACK_REFS_ARGS], {
+          cwd: args.repoPath,
+          ...gitOptions,
+          admissionTier: 'background',
+          timeout: PACK_REFS_TIMEOUT_MS
+        })
+      } finally {
+        watch?.stop()
+        lock.setHeld(false)
+        await owner?.release()
+      }
+    }
+  }
+}
diff --git a/src/main/git/pack-refs-lock-ownership.test.ts b/src/main/git/pack-refs-lock-ownership.test.ts
new file mode 100644
index 00000000000..e181feb9976
--- /dev/null
+++ b/src/main/git/pack-refs-lock-ownership.test.ts
@@ -0,0 +1,192 @@
+import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { PackRefsLockOwnership } from './pack-refs-lock-ownership'
+
+const roots: string[] = []
+
+async function gitCommonDir(): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), 'orca-pack-refs-lock-'))
+  roots.push(root)
+  return root
+}
+
+function paths(commonDir: string): { lock: string; marker: string } {
+  return {
+    lock: join(commonDir, 'packed-refs.lock'),
+    marker: join(commonDir, 'packed-refs.orca-owner')
+  }
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await stat(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** A pid that cannot be running: the kernel rejects it outright. */
+const DEAD_PID = 0x7fffffff
+const ABANDONED_LOCK_AGE_MS = 15 * 60_000
+const PID_REUSE_HORIZON_MS = 24 * 60 * 60_000
+
+/** `claim` takes `now`, so age cases need no sleeping and no mtime forgery. */
+function laterBy(ms: number): number {
+  return Date.now() + ms
+}
+
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })))
+})
+
+describe('packed-refs lock ownership', () => {
+  it('claims a repository with no lock and records the owner', async () => {
+    const commonDir = await gitCommonDir()
+    const { marker } = paths(commonDir)
+
+    await expect(new PackRefsLockOwnership(commonDir).claim()).resolves.toEqual({ ok: true })
+
+    await expect(readFile(marker, 'utf-8')).resolves.toContain(String(process.pid))
+  })
+
+  it('drops the owner marker on release', async () => {
+    const commonDir = await gitCommonDir()
+    const ownership = new PackRefsLockOwnership(commonDir)
+    await ownership.claim()
+
+    await ownership.release()
+
+    await expect(exists(paths(commonDir).marker)).resolves.toBe(false)
+  })
+
+  it('refuses a lock it cannot prove is its own', async () => {
+    const commonDir = await gitCommonDir()
+    // A lock with no marker belongs to the user's own git, or to another tool.
+    await writeFile(paths(commonDir).lock, 'someone else')
+
+    await expect(new PackRefsLockOwnership(commonDir).claim()).resolves.toMatchObject({ ok: false })
+    await expect(exists(paths(commonDir).lock)).resolves.toBe(true)
+  })
+
+  it('refuses a lock whose recorded owner is still running', async () => {
+    const commonDir = await gitCommonDir()
+    const { lock, marker } = paths(commonDir)
+    await writeFile(lock, 'in progress')
+    await writeFile(marker, JSON.stringify({ pid: process.pid }))
+
+    await expect(
+      new PackRefsLockOwnership(commonDir).claim(laterBy(ABANDONED_LOCK_AGE_MS + 1))
+    ).resolves.toMatchObject({ ok: false })
+    await expect(exists(lock)).resolves.toBe(true)
+  })
+
+  it('reclaims the lock its own dead process left behind', async () => {
+    // SIGKILL and power loss bypass git's cleanup, and git never clears this itself.
+    const commonDir = await gitCommonDir()
+    const { lock, marker } = paths(commonDir)
+    await writeFile(lock, 'abandoned mid-rewrite')
+    await writeFile(marker, JSON.stringify({ pid: DEAD_PID }))
+
+    const claimed = await new PackRefsLockOwnership(commonDir).claim(
+      laterBy(ABANDONED_LOCK_AGE_MS + 1)
+    )
+
+    expect(claimed).toEqual({ ok: true })
+    await expect(exists(lock)).resolves.toBe(false)
+    await expect(readFile(marker, 'utf-8')).resolves.toContain(String(process.pid))
+  })
+
+  it('leaves a young lock alone even when the marker names a dead process', async () => {
+    // A marker outlives its lock, so a foreign lock can appear after our death.
+    // Age is the only thing separating our wreckage from somebody's live lock.
+    const commonDir = await gitCommonDir()
+    const { lock, marker } = paths(commonDir)
+    await writeFile(marker, JSON.stringify({ pid: DEAD_PID }))
+    await writeFile(lock, 'a different git process, started just now')
+
+    await expect(new PackRefsLockOwnership(commonDir).claim()).resolves.toMatchObject({ ok: false })
+    await expect(exists(lock)).resolves.toBe(true)
+  })
+
+  it('does not wedge a repository forever when the recorded pid was recycled', async () => {
+    const commonDir = await gitCommonDir()
+    const { lock, marker } = paths(commonDir)
+    await writeFile(lock, 'abandoned mid-rewrite')
+    // Our own pid stands in for a recycled one: alive, but not the process that wrote this.
+    await writeFile(marker, JSON.stringify({ pid: process.pid }))
+
+    await expect(
+      new PackRefsLockOwnership(commonDir).claim(laterBy(ABANDONED_LOCK_AGE_MS + 1))
+    ).resolves.toMatchObject({ ok: false })
+
+    await expect(
+      new PackRefsLockOwnership(commonDir).claim(laterBy(PID_REUSE_HORIZON_MS + 1))
+    ).resolves.toEqual({ ok: true })
+    await expect(exists(lock)).resolves.toBe(false)
+  })
+
+  it('refuses a lock whose marker is unreadable rather than guessing', async () => {
+    const commonDir = await gitCommonDir()
+    const { lock, marker } = paths(commonDir)
+    await writeFile(lock, 'in progress')
+    await writeFile(marker, 'not json')
+
+    await expect(
+      new PackRefsLockOwnership(commonDir).claim(laterBy(PID_REUSE_HORIZON_MS + 1))
+    ).resolves.toMatchObject({ ok: false })
+    await expect(exists(lock)).resolves.toBe(true)
+  })
+
+  it('claims cleanly when a marker outlived its lock', async () => {
+    const commonDir = await gitCommonDir()
+    await writeFile(paths(commonDir).marker, JSON.stringify({ pid: DEAD_PID }))
+
+    await expect(new PackRefsLockOwnership(commonDir).claim()).resolves.toEqual({ ok: true })
+  })
+})
+
+describe('stranded per-ref locks', () => {
+  it('clears the empty refs/**/*.lock files its own dead process left behind', async () => {
+    // `tempfile.c` opens the lock O_EXCL before linking it into the list the
+    // signal handler walks, so a kill in that window leaves a 0-byte file that
+    // Git never clears -- and `update-ref -d` on that ref then fails forever.
+    const commonDir = await gitCommonDir()
+    const namespace = join(commonDir, 'refs', 'remotes', 'origin')
+    await mkdir(namespace, { recursive: true })
+    await writeFile(join(namespace, 'main.lock'), '')
+    await writeFile(join(namespace, 'main'), 'a'.repeat(40))
+    await writeFile(paths(commonDir).marker, JSON.stringify({ pid: DEAD_PID }))
+
+    await new PackRefsLockOwnership(commonDir).claim(laterBy(ABANDONED_LOCK_AGE_MS + 1))
+
+    await expect(exists(join(namespace, 'main.lock'))).resolves.toBe(false)
+    // The ref itself is untouched.
+    await expect(exists(join(namespace, 'main'))).resolves.toBe(true)
+  })
+
+  it('leaves a non-empty ref lock alone, because a live writer is mid-write', async () => {
+    const commonDir = await gitCommonDir()
+    const namespace = join(commonDir, 'refs', 'heads')
+    await mkdir(namespace, { recursive: true })
+    await writeFile(join(namespace, 'busy.lock'), 'b'.repeat(40))
+    await writeFile(paths(commonDir).marker, JSON.stringify({ pid: DEAD_PID }))
+
+    await new PackRefsLockOwnership(commonDir).claim(laterBy(ABANDONED_LOCK_AGE_MS + 1))
+
+    await expect(exists(join(namespace, 'busy.lock'))).resolves.toBe(true)
+  })
+
+  it('leaves ref locks alone when there is no marker naming a dead process', async () => {
+    const commonDir = await gitCommonDir()
+    const namespace = join(commonDir, 'refs', 'heads')
+    await mkdir(namespace, { recursive: true })
+    await writeFile(join(namespace, 'other.lock'), '')
+
+    await new PackRefsLockOwnership(commonDir).claim(laterBy(ABANDONED_LOCK_AGE_MS + 1))
+
+    await expect(exists(join(namespace, 'other.lock'))).resolves.toBe(true)
+  })
+})
diff --git a/src/main/git/pack-refs-lock-ownership.ts b/src/main/git/pack-refs-lock-ownership.ts
new file mode 100644
index 00000000000..9e7273b143b
--- /dev/null
+++ b/src/main/git/pack-refs-lock-ownership.ts
@@ -0,0 +1,202 @@
+import { readFile, readdir, rm, stat, writeFile } from 'node:fs/promises'
+import { posix, win32 } from 'node:path'
+import { isWindowsAbsolutePathLike } from '../../shared/cross-platform-path'
+import {
+  PACK_REFS_TIMEOUT_MS,
+  PACKED_REFS_LOCK_POLL_MS
+} from '../../shared/repo-ref-maintenance-policy'
+
+/** No legitimate `pack-refs` outlives its own deadline, so an older lock is abandoned. */
+const ABANDONED_LOCK_AGE_MS = PACK_REFS_TIMEOUT_MS
+
+/** Beyond this a recorded pid may have been recycled, so it stops being evidence of life. */
+const PID_REUSE_HORIZON_MS = 24 * 60 * 60_000
+
+/** The ref tree is wide but shallow; this only stops a pathological walk. */
+const REF_LOCK_SCAN_CEILING = 4096
+
+/**
+ * Makes a `packed-refs.lock` Orca left behind attributable, and only that one.
+ *
+ * Git registers signal handlers that clean the lock up, but SIGKILL and power
+ * loss bypass them, and Git never removes a stale `packed-refs.lock` on its own
+ * -- every later ref deletion in that repository fails until someone deletes a
+ * file they have never heard of. Recording our pid beside the lock lets a later
+ * run recognise its own wreckage.
+ *
+ * Three independent conditions must all hold before anything is unlinked,
+ * because deleting a lock somebody else is holding is far worse than declining
+ * to pack: a marker must exist at all, the lock must be older than any
+ * `pack-refs` could legitimately run for, and the recorded process must be gone.
+ * A marker can outlive its lock, so age is what separates "our wreckage" from a
+ * foreign lock that happened to appear afterwards.
+ */
+export class PackRefsLockOwnership {
+  private readonly lockPath: string
+  private readonly markerPath: string
+
+  constructor(gitCommonDir: string) {
+    const path = isWindowsAbsolutePathLike(gitCommonDir) ? win32 : posix
+    this.lockPath = path.join(gitCommonDir, 'packed-refs.lock')
+    this.markerPath = path.join(gitCommonDir, 'packed-refs.orca-owner')
+  }
+
+  /** Refused when the lock belongs to something we cannot prove is our own wreckage. */
+  async claim(now = Date.now()): Promise<PackRefsLockClaim> {
+    const reclaim = await this.reclaimAbandonedLock(now)
+    if (!reclaim.ok) {
+      return reclaim
+    }
+    // Per-ref strands outlive their pack and are invisible to Git, which never
+    // clears a `refs/**\/*.lock` it did not create in this process.
+    await this.reclaimStrandedRefLocks(now)
+    try {
+      await writeFile(this.markerPath, JSON.stringify({ pid: process.pid }), 'utf-8')
+    } catch {
+      // Losing the marker only costs attribution on the next run, never correctness.
+    }
+    return { ok: true }
+  }
+
+  /**
+   * Poll `packed-refs.lock` so the scheduler knows when the exclusive rewrite
+   * window opens and closes. Cheap: one `stat` on a fixed path.
+   */
+  watchLock(report: (held: boolean) => void): { stop: () => void } {
+    let stopped = false
+    let last = false
+    const tick = async (): Promise<void> => {
+      if (stopped) {
+        return
+      }
+      const held = (await fileAgeMs(this.lockPath, Date.now())) !== null
+      if (!stopped && held !== last) {
+        last = held
+        report(held)
+      }
+    }
+    const timer = setInterval(() => void tick(), PACKED_REFS_LOCK_POLL_MS)
+    timer.unref?.()
+    void tick()
+    return {
+      stop: () => {
+        stopped = true
+        clearInterval(timer)
+      }
+    }
+  }
+
+  async release(): Promise<void> {
+    await rm(this.markerPath, { force: true }).catch(() => {})
+  }
+
+  private async reclaimAbandonedLock(now: number): Promise<PackRefsLockClaim> {
+    const lockAgeMs = await fileAgeMs(this.lockPath, now)
+    if (lockAgeMs === null) {
+      return { ok: true }
+    }
+    // No marker means the lock is not ours to reason about, let alone remove.
+    const marker = await readOwnerMarker(this.markerPath)
+    if (marker === null) {
+      return { ok: false, reason: 'held by another process' }
+    }
+    if (lockAgeMs < ABANDONED_LOCK_AGE_MS) {
+      // Ours, but too young to be certain the writer is gone. Worth retrying soon.
+      return { ok: false, reason: 'our own lock, not yet old enough to reclaim' }
+    }
+    // Past the pid-reuse horizon the pid proves nothing, and a lock this old is
+    // abandoned whoever wrote it -- otherwise a recycled pid would wedge the
+    // repository permanently.
+    if (isProcessAlive(marker.pid) && lockAgeMs < PID_REUSE_HORIZON_MS) {
+      return { ok: false, reason: 'the recorded owner is still running' }
+    }
+    await rm(this.lockPath, { force: true }).catch(() => {})
+    await rm(this.markerPath, { force: true }).catch(() => {})
+    return { ok: true }
+  }
+
+  /**
+   * Clear `refs/**\/*.lock` files a dead pack of ours left behind.
+   *
+   * `tempfile.c` opens the lock `O_EXCL` before `activate_tempfile()` links it
+   * into the list the signal handler walks, so a kill inside that window leaves
+   * a 0-byte file. Afterwards `update-ref -d` and any fetch touching that ref
+   * fail with `cannot lock ref ... File exists`, forever. Same three conditions
+   * as the packed-refs lock, plus a size check: a live writer's lock is not empty.
+   */
+  private async reclaimStrandedRefLocks(now: number): Promise<void> {
+    const marker = await readOwnerMarker(this.markerPath)
+    if (marker === null || isProcessAlive(marker.pid)) {
+      return
+    }
+    const markerAgeMs = await fileAgeMs(this.markerPath, now)
+    if (markerAgeMs === null || markerAgeMs < ABANDONED_LOCK_AGE_MS) {
+      return
+    }
+    const path = isWindowsAbsolutePathLike(this.markerPath) ? win32 : posix
+    const pending = [path.join(path.dirname(this.markerPath), 'refs')]
+    let visited = 0
+    while (pending.length > 0) {
+      const directory = pending.pop()
+      if (directory === undefined || (visited += 1) > REF_LOCK_SCAN_CEILING) {
+        return
+      }
+      let entries: { name: string; isDirectory: () => boolean }[]
+      try {
+        entries = await readdir(directory, { withFileTypes: true })
+      } catch {
+        continue
+      }
+      for (const entry of entries) {
+        const full = path.join(directory, entry.name)
+        if (entry.isDirectory()) {
+          pending.push(full)
+        } else if (entry.name.endsWith('.lock') && (await isEmptyFile(full))) {
+          await rm(full, { force: true }).catch(() => {})
+        }
+      }
+    }
+  }
+}
+
+export type PackRefsLockClaim = { ok: true } | { ok: false; reason: string }
+
+/** A strand from the `O_EXCL` window is 0 bytes; a live writer's lock is not. */
+async function isEmptyFile(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).size === 0
+  } catch {
+    return false
+  }
+}
+
+async function readOwnerMarker(path: string): Promise<{ pid: number } | null> {
+  try {
+    const raw = (await readFile(path, 'utf-8')).slice(0, 256)
+    const pid = (JSON.parse(raw) as { pid?: unknown }).pid
+    return typeof pid === 'number' && Number.isInteger(pid) && pid > 0 ? { pid } : null
+  } catch {
+    return null
+  }
+}
+
+/** Null when the file does not exist. Uses stat: the lock holds a whole packed-refs. */
+async function fileAgeMs(path: string, now: number): Promise<number | null> {
+  try {
+    return Math.max(0, now - (await stat(path)).mtimeMs)
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'ENOENT' ? null : 0
+  }
+}
+
+function isProcessAlive(pid: number): boolean {
+  if (pid === process.pid) {
+    return true
+  }
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code !== 'ESRCH'
+  }
+}
diff --git a/src/main/git/remote.ts b/src/main/git/remote.ts
index c1557bdd806..2baf3b77137 100644
--- a/src/main/git/remote.ts
+++ b/src/main/git/remote.ts
@@ -7,6 +7,10 @@ import { gitRefTargetsBranchOnRemote } from '../../shared/git-remote-branch-name
 import type { GitPushTarget } from '../../shared/worktree/types'
 import type { GitRuntimeOptions } from './git-runtime-options'
 import { gitOptionsForWorktree } from './git-runtime-options'
+import {
+  postponeRepoRefMaintenance,
+  withRepoRefMaintenancePaused
+} from './local-repo-ref-maintenance'
 import { validateGitPushTarget } from './push-target-validation'
 import { gitExecFileAsync } from './runner'
 import { fetchForkRemoteWithStaleRefspecRepair } from './fork-remote-stale-branch-refspec'
@@ -260,8 +264,11 @@ export async function gitPull(
   // Why: plain `git pull` uses the user's configured pull strategy (merge by
   // default) so diverged branches reconcile instead of erroring out. Conflicts
   // surface through the existing conflict-resolution flow.
-  await runWithGitWorktreeOperationLock(worktreePath, options.signal, () =>
-    runWithGitReadCacheInvalidation(() => gitPullWithArgs(worktreePath, [], pushTarget, options))
+  postponeRepoRefMaintenance()
+  await withRepoRefMaintenancePaused('git-pull', () =>
+    runWithGitWorktreeOperationLock(worktreePath, options.signal, () =>
+      runWithGitReadCacheInvalidation(() => gitPullWithArgs(worktreePath, [], pushTarget, options))
+    )
   )
 }
 
@@ -270,9 +277,12 @@ export async function gitFastForward(
   pushTarget?: GitPushTarget,
   options: GitRuntimeOptions = {}
 ): Promise<void> {
-  await runWithGitWorktreeOperationLock(worktreePath, options.signal, () =>
-    runWithGitReadCacheInvalidation(() =>
-      gitPullWithArgs(worktreePath, ['--ff-only'], pushTarget, options)
+  postponeRepoRefMaintenance()
+  await withRepoRefMaintenancePaused('git-fast-forward', () =>
+    runWithGitWorktreeOperationLock(worktreePath, options.signal, () =>
+      runWithGitReadCacheInvalidation(() =>
+        gitPullWithArgs(worktreePath, ['--ff-only'], pushTarget, options)
+      )
     )
   )
 }
@@ -282,22 +292,28 @@ export async function gitFetch(
   pushTarget?: GitPushTarget,
   options: GitRuntimeOptions = {}
 ): Promise<void> {
+  // `--prune` deletes remote-tracking refs, which needs the `packed-refs` lock a
+  // running idle pack holds while it rewrites -- ~1.4s at most. This is the user
+  // clicking Fetch, so wait that window out rather than letting it fail on the lock.
+  postponeRepoRefMaintenance()
   try {
-    if (pushTarget) {
-      const target = await validateGitPushTarget(worktreePath, pushTarget, options)
-      const runtimeOptions = gitOptionsForWorktree(worktreePath, options)
-      await fetchForkRemoteWithStaleRefspecRepair(
-        (args, cwd) => gitExecFileAsync(args, { ...runtimeOptions, cwd }),
-        worktreePath,
-        target.remoteName,
-        () =>
-          gitExecFileAsync(['fetch', '--prune', target.remoteName], runtimeOptions).then(
-            () => undefined
-          )
-      )
-      return
-    }
-    await gitExecFileAsync(['fetch', '--prune'], gitOptionsForWorktree(worktreePath, options))
+    await withRepoRefMaintenancePaused('git-fetch', async () => {
+      if (pushTarget) {
+        const target = await validateGitPushTarget(worktreePath, pushTarget, options)
+        const runtimeOptions = gitOptionsForWorktree(worktreePath, options)
+        await fetchForkRemoteWithStaleRefspecRepair(
+          (args, cwd) => gitExecFileAsync(args, { ...runtimeOptions, cwd }),
+          worktreePath,
+          target.remoteName,
+          () =>
+            gitExecFileAsync(['fetch', '--prune', target.remoteName], runtimeOptions).then(
+              () => undefined
+            )
+        )
+        return
+      }
+      await gitExecFileAsync(['fetch', '--prune'], gitOptionsForWorktree(worktreePath, options))
+    })
   } catch (error) {
     throw new Error(normalizeGitErrorMessage(error, 'fetch'))
   }
diff --git a/src/main/git/repo-ref-maintenance-real-git.test.ts b/src/main/git/repo-ref-maintenance-real-git.test.ts
new file mode 100644
index 00000000000..30c67b0365a
--- /dev/null
+++ b/src/main/git/repo-ref-maintenance-real-git.test.ts
@@ -0,0 +1,290 @@
+import { execFileSync } from 'node:child_process'
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { countLooseRefs } from '../../shared/loose-ref-count'
+import { RepoRefMaintenance } from '../../shared/repo-ref-maintenance'
+import {
+  _resetLocalRepoRefMaintenanceForTests,
+  createLocalRepoRefMaintenanceTarget,
+  getLocalRepoRefMaintenance,
+  setRepoMaintenanceActivityProbe
+} from './local-repo-ref-maintenance'
+import { forceDeleteLocalBranch } from './worktree-branch-removal'
+
+const roots: string[] = []
+// Large enough that the deferral ladder (1x, 2x, 4x ... capped at 8x) outlasts
+// three real `pack-refs` runs before the deferral budget is spent.
+const QUIET_MS = 25
+const THRESHOLD = 20
+
+function git(cwd: string, args: string[]): string {
+  return execFileSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe']
+  }).trim()
+}
+
+/** A repo whose only loose-ref backlog is the one the test asks for. */
+async function createRepo(looseRefs: number): Promise<{ repoPath: string; refsDir: string }> {
+  const root = await mkdtemp(join(tmpdir(), 'orca-ref-maintenance-git-'))
+  roots.push(root)
+  const repoPath = join(root, 'repo')
+  execFileSync('git', ['init', '--quiet', repoPath])
+  git(repoPath, ['symbolic-ref', 'HEAD', 'refs/heads/main'])
+  git(repoPath, ['config', 'user.email', 'test@example.com'])
+  git(repoPath, ['config', 'user.name', 'Test User'])
+  await writeFile(join(repoPath, 'file.txt'), 'one\n')
+  git(repoPath, ['add', 'file.txt'])
+  git(repoPath, ['commit', '--quiet', '-m', 'initial'])
+  const head = git(repoPath, ['rev-parse', 'HEAD'])
+  // Written directly: `update-ref` for thousands of refs is the slow part of the fixture.
+  const namespace = join(repoPath, '.git', 'refs', 'remotes', 'origin')
+  await mkdir(namespace, { recursive: true })
+  for (let index = 0; index < looseRefs; index += 1) {
+    await writeFile(join(namespace, `branch-${index}`), `${head}\n`)
+  }
+  return { repoPath, refsDir: join(repoPath, '.git', 'refs') }
+}
+
+function createMaintenance(onPackRefs: () => void = () => {}): {
+  maintenance: RepoRefMaintenance
+  arm: (repoPath: string) => void
+} {
+  const maintenance = new RepoRefMaintenance({
+    quietPeriodMs: QUIET_MS,
+    looseRefThreshold: THRESHOLD
+  })
+  return {
+    maintenance,
+    arm: (repoPath: string) => {
+      const target = createLocalRepoRefMaintenanceTarget({
+        key: `local::${repoPath}`,
+        repoPath
+      })
+      maintenance.arm({
+        ...target,
+        packRefs: async (signal) => {
+          onPackRefs()
+          await target.packRefs(signal)
+        }
+      })
+    }
+  }
+}
+
+async function settle(maintenance: RepoRefMaintenance): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, QUIET_MS * 4))
+  await maintenance.whenAttemptSettled()
+}
+
+/** Deferred repos re-arm for another quiet period, so drain rather than count rounds. */
+async function settleUntil(
+  maintenance: RepoRefMaintenance,
+  done: () => Promise<boolean>
+): Promise<void> {
+  for (let round = 0; round < 100; round += 1) {
+    if (await done()) {
+      return
+    }
+    await settle(maintenance)
+  }
+}
+
+afterEach(async () => {
+  _resetLocalRepoRefMaintenanceForTests()
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })))
+})
+
+describe('idle ref maintenance against real Git', () => {
+  it('packs a backlogged repository down to zero loose refs', async () => {
+    const { repoPath, refsDir } = await createRepo(THRESHOLD + 30)
+    const { maintenance, arm } = createMaintenance()
+
+    await expect(countLooseRefs(refsDir, 10_000)).resolves.toMatchObject({
+      count: THRESHOLD + 31
+    })
+
+    arm(repoPath)
+    await settle(maintenance)
+    maintenance.dispose()
+
+    await expect(countLooseRefs(refsDir, 10_000)).resolves.toEqual({ count: 0, saturated: false })
+    // The refs survived the move into packed-refs; nothing was lost.
+    expect(git(repoPath, ['for-each-ref', '--format=%(refname)']).split('\n')).toHaveLength(
+      THRESHOLD + 31
+    )
+    expect(git(repoPath, ['rev-parse', '--verify', 'refs/remotes/origin/branch-0'])).toMatch(
+      /^[0-9a-f]{40}$/
+    )
+  }, 30_000)
+
+  it('leaves a healthy repository untouched', async () => {
+    const { repoPath, refsDir } = await createRepo(2)
+    let packed = 0
+    const { maintenance, arm } = createMaintenance(() => {
+      packed += 1
+    })
+
+    arm(repoPath)
+    await settle(maintenance)
+    maintenance.dispose()
+
+    expect(packed).toBe(0)
+    await expect(countLooseRefs(refsDir, 10_000)).resolves.toMatchObject({ count: 3 })
+  }, 30_000)
+
+  it('honours maintenance.auto=false in the repository config', async () => {
+    const { repoPath, refsDir } = await createRepo(THRESHOLD + 30)
+    git(repoPath, ['config', 'maintenance.auto', 'false'])
+    let packed = 0
+    const { maintenance, arm } = createMaintenance(() => {
+      packed += 1
+    })
+
+    arm(repoPath)
+    await settle(maintenance)
+    maintenance.dispose()
+
+    expect(packed).toBe(0)
+    await expect(countLooseRefs(refsDir, 10_000)).resolves.toMatchObject({
+      count: THRESHOLD + 31
+    })
+  }, 30_000)
+
+  it('runs one repository at a time even when several go quiet together', async () => {
+    const repos = await Promise.all([
+      createRepo(THRESHOLD + 5),
+      createRepo(THRESHOLD + 5),
+      createRepo(THRESHOLD + 5)
+    ])
+    let concurrent = 0
+    let peak = 0
+    const maintenance = new RepoRefMaintenance({
+      quietPeriodMs: QUIET_MS,
+      looseRefThreshold: THRESHOLD
+    })
+    for (const { repoPath } of repos) {
+      const target = createLocalRepoRefMaintenanceTarget({
+        key: `local::${repoPath}`,
+        repoPath
+      })
+      maintenance.arm({
+        ...target,
+        packRefs: async (signal) => {
+          concurrent += 1
+          peak = Math.max(peak, concurrent)
+          try {
+            await target.packRefs(signal)
+          } finally {
+            concurrent -= 1
+          }
+        }
+      })
+    }
+
+    const allPacked = async (): Promise<boolean> => {
+      const counts = await Promise.all(repos.map(({ refsDir }) => countLooseRefs(refsDir, 10_000)))
+      return counts.every((scan) => scan.count === 0)
+    }
+    await settleUntil(maintenance, allPacked)
+    maintenance.dispose()
+
+    expect(peak).toBe(1)
+    for (const { refsDir } of repos) {
+      await expect(countLooseRefs(refsDir, 10_000)).resolves.toEqual({
+        count: 0,
+        saturated: false
+      })
+    }
+  }, 60_000)
+})
+
+describe('yielding the repository to work that deletes refs', () => {
+  it('waits for the packed-refs lock and succeeds while the prune continues', async () => {
+    // The pack is never killed. `packed-refs.lock` is held for ~1.4s of a 30s
+    // run; the rest is the prune, during which a concurrent `update-ref -d`
+    // succeeds on its own because per-ref locks last microseconds. Signalling
+    // the child there strands a `refs/**` lock Git never clears.
+    const { repoPath } = await createRepo(0)
+    git(repoPath, ['branch', 'doomed'])
+    const head = git(repoPath, ['rev-parse', 'refs/heads/doomed'])
+
+    let packing = false
+    let releaseLock: (() => void) | undefined
+    _resetLocalRepoRefMaintenanceForTests({ quietPeriodMs: QUIET_MS, looseRefThreshold: 1 })
+    setRepoMaintenanceActivityProbe(() => false)
+    getLocalRepoRefMaintenance().arm({
+      key: `local::${repoPath}`,
+      resolveRefsDirectory: async () => join(repoPath, '.git', 'refs'),
+      packRefs: async (lock) => {
+        packing = true
+        lock.setHeld(true)
+        // Stands in for the rewrite window, then the long prune that follows it.
+        await new Promise<void>((resolve) => {
+          releaseLock = () => {
+            lock.setHeld(false)
+            resolve()
+          }
+        })
+      }
+    })
+    for (let attempt = 0; attempt < 200 && !packing; attempt += 1) {
+      await new Promise((resolve) => setTimeout(resolve, QUIET_MS))
+    }
+    expect(packing).toBe(true)
+
+    // The real deletion path, which routes through withRepoRefMaintenancePaused.
+    let deleted = false
+    const deletion = forceDeleteLocalBranch(repoPath, 'doomed', head).then(() => {
+      deleted = true
+    })
+
+    // It must still be waiting: the rewrite window is open.
+    await new Promise((resolve) => setTimeout(resolve, QUIET_MS * 4))
+    expect(deleted).toBe(false)
+    expect(git(repoPath, ['branch', '--list', 'doomed'])).toContain('doomed')
+
+    // Releasing the window is enough -- the pack is never cancelled.
+    releaseLock?.()
+    await deletion
+    expect(deleted).toBe(true)
+    expect(git(repoPath, ['branch', '--list', 'doomed'])).toBe('')
+  }, 30_000)
+
+  it('does not block the caller once the rewrite window has closed', async () => {
+    // The prune phase is concurrency-safe, so a caller arriving during it pays
+    // nothing at all.
+    const { repoPath } = await createRepo(0)
+    git(repoPath, ['branch', 'doomed'])
+    const head = git(repoPath, ['rev-parse', 'refs/heads/doomed'])
+
+    let pruning = false
+    let finishPrune: (() => void) | undefined
+    _resetLocalRepoRefMaintenanceForTests({ quietPeriodMs: QUIET_MS, looseRefThreshold: 1 })
+    setRepoMaintenanceActivityProbe(() => false)
+    getLocalRepoRefMaintenance().arm({
+      key: `local::${repoPath}`,
+      resolveRefsDirectory: async () => join(repoPath, '.git', 'refs'),
+      packRefs: async (lock) => {
+        lock.setHeld(true)
+        lock.setHeld(false)
+        pruning = true
+        await new Promise<void>((resolve) => {
+          finishPrune = resolve
+        })
+      }
+    })
+    for (let attempt = 0; attempt < 200 && !pruning; attempt += 1) {
+      await new Promise((resolve) => setTimeout(resolve, QUIET_MS))
+    }
+
+    const startedAt = Date.now()
+    await expect(forceDeleteLocalBranch(repoPath, 'doomed', head)).resolves.toBeUndefined()
+    expect(Date.now() - startedAt).toBeLessThan(2_000)
+
+    finishPrune?.()
+  }, 30_000)
+})
diff --git a/src/main/git/worktree-add.ts b/src/main/git/worktree-add.ts
index 3cd761f4d13..ea6ec704b46 100644
--- a/src/main/git/worktree-add.ts
+++ b/src/main/git/worktree-add.ts
@@ -4,6 +4,7 @@ import type {
   LocalBaseRefUpdateSuggestion
 } from '../../shared/worktree/base-ref-drift-types'
 import { windowsLongPathGitArgs } from '../../shared/windows-long-path-git-args'
+import { withRepoRefMaintenancePaused } from './local-repo-ref-maintenance'
 import { gitExecFileAsync } from './runner'
 import { runWithGitReadCacheInvalidation } from './status'
 import { invalidateWslLinkedWorktreeGitRouting } from './wsl-linked-worktree-git-routing'
@@ -149,15 +150,17 @@ export async function addWorktree(
   options: AddWorktreeOptions = {}
 ): Promise<AddWorktreeResult> {
   try {
-    return await runWithGitReadCacheInvalidation(() =>
-      performAddWorktree(
-        repoPath,
-        worktreePath,
-        branch,
-        baseBranch,
-        refreshLocalBaseRef,
-        noCheckout,
-        options
+    return await withRepoRefMaintenancePaused('worktree-add', () =>
+      runWithGitReadCacheInvalidation(() =>
+        performAddWorktree(
+          repoPath,
+          worktreePath,
+          branch,
+          baseBranch,
+          refreshLocalBaseRef,
+          noCheckout,
+          options
+        )
       )
     )
   } finally {
diff --git a/src/main/git/worktree-branch-removal.ts b/src/main/git/worktree-branch-removal.ts
index 5e64b4a582d..08b6b21a1e3 100644
--- a/src/main/git/worktree-branch-removal.ts
+++ b/src/main/git/worktree-branch-removal.ts
@@ -4,6 +4,7 @@ import {
 } from '../../shared/git-branch-cleanup'
 import type { RemoveWorktreeResult } from '../../shared/worktree/create-types'
 import { withLocalGitCapabilityCacheForExecution } from './git-capability-state'
+import { withRepoRefMaintenancePaused } from './local-repo-ref-maintenance'
 import { gitExecFileAsync } from './runner'
 import { parseWorktreeList } from './worktree-list-parser'
 import type { GitWorktreeExecOptions, RemoveWorktreeOptions } from './worktree-operation-options'
@@ -152,7 +153,11 @@ export async function forceDeleteLocalBranch(
   }
   // Why: stale toast actions must not delete a branch that moved; `update-ref -d` deletes only if the ref still == expectedHead.
   try {
-    await runGit(['update-ref', '-d', `refs/heads/${branchName}`, expectedHead], repoPath)
+    // `update-ref -d` needs the packed-refs lock a running idle pack holds while
+    // it rewrites; waits it out rather than cancelling the pack.
+    await withRepoRefMaintenancePaused('branch-delete', () =>
+      runGit(['update-ref', '-d', `refs/heads/${branchName}`, expectedHead], repoPath)
+    )
   } catch {
     throw new Error(
       `Local branch "${branchName}" changed after the workspace was deleted. Review it before deleting it.`
diff --git a/src/main/git/worktree-create-preparation.ts b/src/main/git/worktree-create-preparation.ts
index 3be0fee1648..b60dc01ec33 100644
--- a/src/main/git/worktree-create-preparation.ts
+++ b/src/main/git/worktree-create-preparation.ts
@@ -10,6 +10,7 @@ import {
   WORKTREE_REMOVAL_REGISTRATION_TIMEOUT_MS
 } from './worktree'
 import { hasWorktreeBaseCommitRef } from './worktree-base-ref-probe'
+import { withRepoRefMaintenancePaused } from './local-repo-ref-maintenance'
 import { gitExecFileAsync } from './runner'
 import { runWithGitReadCacheInvalidation } from './status'
 import { invalidateWslLinkedWorktreeGitRouting } from './wsl-linked-worktree-git-routing'
@@ -69,46 +70,48 @@ export async function prepareWorktreeCreateCheckout(
   options: GitWorktreeExecOptions = {}
 ): Promise<void> {
   try {
-    await runWithGitReadCacheInvalidation(async () => {
-      const effectiveBase = await resolveWorktreeAddBaseRef(baseBranch, (qualifiedRef) =>
-        hasWorktreeBaseCommitRef(repoPath, qualifiedRef, options)
-      )
-      try {
-        await gitExecFileAsync(
-          [
-            ...windowsLongPathGitArgs(repoPath),
-            'worktree',
-            'add',
-            '--detach',
-            '--no-checkout',
-            worktreePath,
-            effectiveBase
-          ],
-          { ...gitExecOptions(repoPath, options), timeout: resolveWorktreeAddTimeoutMs() }
+    await withRepoRefMaintenancePaused('worktree-prepare', () =>
+      runWithGitReadCacheInvalidation(async () => {
+        const effectiveBase = await resolveWorktreeAddBaseRef(baseBranch, (qualifiedRef) =>
+          hasWorktreeBaseCommitRef(repoPath, qualifiedRef, options)
         )
-        // The add just wrote the marker; drop any pre-create route before the reset routes Git.
-        invalidateWslLinkedWorktreeGitRouting(worktreePath)
-        // Why: reset materializes files without running user post-checkout hooks before submit.
-        await gitExecFileAsync(
-          [...windowsLongPathGitArgs(worktreePath), 'reset', '--hard', effectiveBase],
-          { ...gitExecOptions(worktreePath, options), timeout: resolveWorktreeAddTimeoutMs() }
-        )
-        await gitExecFileAsync(
-          [
-            ...windowsLongPathGitArgs(repoPath),
-            'worktree',
-            'lock',
-            '--reason',
-            lockReason,
-            worktreePath
-          ],
-          { ...gitExecOptions(repoPath, options), timeout: resolveWorktreeAddTimeoutMs() }
-        )
-      } catch (error) {
-        await performDiscardPreparedWorktree(repoPath, worktreePath, options).catch(() => {})
-        throw error
-      }
-    })
+        try {
+          await gitExecFileAsync(
+            [
+              ...windowsLongPathGitArgs(repoPath),
+              'worktree',
+              'add',
+              '--detach',
+              '--no-checkout',
+              worktreePath,
+              effectiveBase
+            ],
+            { ...gitExecOptions(repoPath, options), timeout: resolveWorktreeAddTimeoutMs() }
+          )
+          // The add just wrote the marker; drop any pre-create route before the reset routes Git.
+          invalidateWslLinkedWorktreeGitRouting(worktreePath)
+          // Why: reset materializes files without running user post-checkout hooks before submit.
+          await gitExecFileAsync(
+            [...windowsLongPathGitArgs(worktreePath), 'reset', '--hard', effectiveBase],
+            { ...gitExecOptions(worktreePath, options), timeout: resolveWorktreeAddTimeoutMs() }
+          )
+          await gitExecFileAsync(
+            [
+              ...windowsLongPathGitArgs(repoPath),
+              'worktree',
+              'lock',
+              '--reason',
+              lockReason,
+              worktreePath
+            ],
+            { ...gitExecOptions(repoPath, options), timeout: resolveWorktreeAddTimeoutMs() }
+          )
+        } catch (error) {
+          await performDiscardPreparedWorktree(repoPath, worktreePath, options).catch(() => {})
+          throw error
+        }
+      })
+    )
   } finally {
     notifyPreparedWorktreeMutation(repoPath)
   }
diff --git a/src/main/git/worktree-removal.ts b/src/main/git/worktree-removal.ts
index c6743a4a7e2..afe1bf2a9c1 100644
--- a/src/main/git/worktree-removal.ts
+++ b/src/main/git/worktree-removal.ts
@@ -22,6 +22,7 @@ import {
 } from './worktree-operation-options'
 import { areWorktreePathsEqual } from './worktree-path-comparison'
 import { assertWorktreeCleanForRemoval } from './worktree-removal-preflight'
+import { withRepoRefMaintenancePaused } from './local-repo-ref-maintenance'
 import { bumpWorktreeScanGeneration, listWorktrees } from './worktree-scan-cache'
 import { invalidateSparseCheckoutState } from './worktree-sparse-checkout-cache'
 
@@ -36,8 +37,13 @@ export async function removeWorktree(
   options: RemoveWorktreeOptions = {}
 ): Promise<RemoveWorktreeResult> {
   try {
-    return await runWithGitReadCacheInvalidation(() =>
-      performRemoveWorktree(repoPath, worktreePath, force, options)
+    // Removal deletes branches, and a ref deletion needs the packed-refs lock a
+    // running idle pack holds while it rewrites. Waits that window out; the
+    // prune phase that follows it is concurrency-safe and is left to finish.
+    return await withRepoRefMaintenancePaused('worktree-remove', () =>
+      runWithGitReadCacheInvalidation(() =>
+        performRemoveWorktree(repoPath, worktreePath, force, options)
+      )
     )
   } finally {
     invalidateWslLinkedWorktreeGitRouting(worktreePath)
diff --git a/src/main/ipc/repos-create.test.ts b/src/main/ipc/repos-create.test.ts
index 86e2dc5ee10..44a16f8e10d 100644
--- a/src/main/ipc/repos-create.test.ts
+++ b/src/main/ipc/repos-create.test.ts
@@ -61,8 +61,11 @@ vi.mock('fs/promises', () => ({
   rm: rmMock
 }))
 
+// `availableParallelism` is read at module load by the git admission scheduler,
+// which this module graph reaches; a partial `os` mock breaks that import.
 vi.mock('os', () => ({
-  homedir: homedirMock
+  homedir: homedirMock,
+  availableParallelism: () => 8
 }))
 
 vi.mock('../git/runner', () => ({
diff --git a/src/main/ipc/worktrees.ts b/src/main/ipc/worktrees.ts
index ff58a561ee3..3fd2fb41908 100644
--- a/src/main/ipc/worktrees.ts
+++ b/src/main/ipc/worktrees.ts
@@ -17,7 +17,10 @@ import { registerSparseCheckoutCacheInvalidation } from './worktrees/listing/reg
 import { registerWorktreeMetadataHandlers } from './worktrees/metadata/register-worktree-metadata-handlers'
 import { registerWorktreeForgetHandlers } from './worktrees/removal/register-worktree-forget-handlers'
 import { registerWorktreeRemovalHandlers } from './worktrees/removal/register-worktree-removal-handlers'
-import type { WorktreeIpcContext } from './worktrees/worktree-ipc-context'
+import {
+  createWorktreeRemovalRegistry,
+  type WorktreeIpcContext
+} from './worktrees/worktree-ipc-context'
 
 registerDetectedWorktreeScanInvalidation()
 
@@ -66,7 +69,7 @@ export function registerWorktreeHandlers(
     runtime,
     ...(options ? { options } : {}),
     detectedWorktreeCancellations: createSenderScopedRequestCancellations(),
-    worktreeRemovalsInFlight: new Map()
+    worktreeRemovalsInFlight: createWorktreeRemovalRegistry()
   }
 
   // Remove all stale registrations before installing any replacement handler.
diff --git a/src/main/ipc/worktrees/worktree-ipc-context.ts b/src/main/ipc/worktrees/worktree-ipc-context.ts
index 5455a71d06e..153e4b723ec 100644
--- a/src/main/ipc/worktrees/worktree-ipc-context.ts
+++ b/src/main/ipc/worktrees/worktree-ipc-context.ts
@@ -14,3 +14,18 @@ export type WorktreeIpcContext = {
   detectedWorktreeCancellations: SenderScopedRequestCancellations
   worktreeRemovalsInFlight: Map<string, WorktreeRemovalInFlight>
 }
+
+// Why: removal and forget both delete refs, and a ref deletion has to take the
+// `packed-refs` lock. Idle ref maintenance needs a process-wide view of that
+// registry so it never packs while one is running.
+let activeWorktreeRemovals: ReadonlyMap<string, WorktreeRemovalInFlight> | null = null
+
+export function createWorktreeRemovalRegistry(): Map<string, WorktreeRemovalInFlight> {
+  const registry = new Map<string, WorktreeRemovalInFlight>()
+  activeWorktreeRemovals = registry
+  return registry
+}
+
+export function hasWorktreeRemovalsInFlight(): boolean {
+  return (activeWorktreeRemovals?.size ?? 0) > 0
+}
diff --git a/src/main/repo-maintenance-idle-gate.test.ts b/src/main/repo-maintenance-idle-gate.test.ts
new file mode 100644
index 00000000000..78728f3a43a
--- /dev/null
+++ b/src/main/repo-maintenance-idle-gate.test.ts
@@ -0,0 +1,134 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const isOnBatteryPowerMock = vi.hoisted(() => vi.fn(() => false))
+const hasPendingPreparationsMock = vi.hoisted(() => vi.fn(() => false))
+const hasRemovalsInFlightMock = vi.hoisted(() => vi.fn(() => false))
+const setProbeMock = vi.hoisted(() => vi.fn())
+const disposeMock = vi.hoisted(() => vi.fn(async () => {}))
+const postponeMock = vi.hoisted(() => vi.fn())
+const powerListeners = vi.hoisted(() => new Map<string, () => void>())
+const appListeners = vi.hoisted(() => new Map<string, () => void>())
+
+vi.mock('electron', () => ({
+  app: {
+    on: (event: string, listener: () => void) => appListeners.set(event, listener),
+    off: (event: string) => appListeners.delete(event)
+  },
+  powerMonitor: {
+    isOnBatteryPower: isOnBatteryPowerMock,
+    on: (event: string, listener: () => void) => powerListeners.set(event, listener),
+    off: (event: string) => powerListeners.delete(event)
+  }
+}))
+
+vi.mock('./worktree-create-preparation', () => ({
+  hasPendingWorktreeCreatePreparations: hasPendingPreparationsMock
+}))
+
+vi.mock('./ipc/worktrees/worktree-ipc-context', () => ({
+  hasWorktreeRemovalsInFlight: hasRemovalsInFlightMock
+}))
+
+vi.mock('./git/local-repo-ref-maintenance', () => ({
+  setRepoMaintenanceActivityProbe: setProbeMock,
+  disposeLocalRepoRefMaintenance: disposeMock,
+  postponeRepoRefMaintenance: postponeMock
+}))
+
+import { installRepoMaintenanceIdleGate } from './repo-maintenance-idle-gate'
+
+function installProbe(
+  overrides: Partial<{ isQuitting: () => boolean; getWorkingAgentCount: () => number }> = {}
+): { probe: () => boolean; uninstall: () => Promise<void> } {
+  const uninstall = installRepoMaintenanceIdleGate({
+    isQuitting: () => false,
+    getWorkingAgentCount: () => 0,
+    ...overrides
+  })
+  return { probe: setProbeMock.mock.calls.at(-1)?.[0] as () => boolean, uninstall }
+}
+
+beforeEach(() => {
+  isOnBatteryPowerMock.mockReturnValue(false)
+  hasPendingPreparationsMock.mockReturnValue(false)
+  hasRemovalsInFlightMock.mockReturnValue(false)
+  postponeMock.mockClear()
+  powerListeners.clear()
+  appListeners.clear()
+  setProbeMock.mockClear()
+  disposeMock.mockClear()
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+describe('repo maintenance idle gate', () => {
+  it('reports idle when nothing is happening', () => {
+    expect(installProbe().probe()).toBe(false)
+  })
+
+  it('vetoes while an agent is working', () => {
+    expect(installProbe({ getWorkingAgentCount: () => 1 }).probe()).toBe(true)
+  })
+
+  it('vetoes while a worktree create is prepared or in flight', () => {
+    hasPendingPreparationsMock.mockReturnValue(true)
+
+    expect(installProbe().probe()).toBe(true)
+  })
+
+  it('vetoes while a worktree removal is deleting refs', () => {
+    // Removal deletes branches, and a ref deletion needs the same packed-refs lock.
+    hasRemovalsInFlightMock.mockReturnValue(true)
+
+    expect(installProbe().probe()).toBe(true)
+  })
+
+  it('vetoes on battery power', () => {
+    isOnBatteryPowerMock.mockReturnValue(true)
+
+    expect(installProbe().probe()).toBe(true)
+  })
+
+  it('vetoes during shutdown', () => {
+    expect(installProbe({ isQuitting: () => true }).probe()).toBe(true)
+  })
+
+  it('treats an unavailable power API as not-on-battery', () => {
+    isOnBatteryPowerMock.mockImplementation(() => {
+      throw new Error('unsupported')
+    })
+
+    expect(installProbe().probe()).toBe(false)
+  })
+
+  it('pushes the next attempt out when the machine drops onto battery', () => {
+    // Do-not-start, never stop-what-is-running: killing a pack to honour a
+    // battery change would strand a ref lock to save a little unlinking.
+    installProbe()
+
+    powerListeners.get('on-battery')?.()
+
+    expect(postponeMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('pushes the next attempt out when the user comes back to the window', () => {
+    // A focus transition, not focus itself: a window left focused while the user
+    // walks away fires no event and blocks nothing.
+    installProbe()
+
+    appListeners.get('browser-window-focus')?.()
+
+    expect(postponeMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('cancels armed timers, unsubscribes both sources, and clears the probe when uninstalled', async () => {
+    await installProbe().uninstall()
+
+    expect(disposeMock).toHaveBeenCalledTimes(1)
+    expect(powerListeners.has('on-battery')).toBe(false)
+    expect(appListeners.has('browser-window-focus')).toBe(false)
+    expect(setProbeMock).toHaveBeenLastCalledWith(null)
+  })
+})
diff --git a/src/main/repo-maintenance-idle-gate.ts b/src/main/repo-maintenance-idle-gate.ts
new file mode 100644
index 00000000000..78bb25fe68c
--- /dev/null
+++ b/src/main/repo-maintenance-idle-gate.ts
@@ -0,0 +1,67 @@
+import { app, powerMonitor } from 'electron'
+import {
+  disposeLocalRepoRefMaintenance,
+  postponeRepoRefMaintenance,
+  setRepoMaintenanceActivityProbe
+} from './git/local-repo-ref-maintenance'
+import { hasWorktreeRemovalsInFlight } from './ipc/worktrees/worktree-ipc-context'
+import { hasPendingWorktreeCreatePreparations } from './worktree-create-preparation'
+
+/**
+ * The app-wide "not now" answer for idle repo maintenance.
+ *
+ * `pack-refs` holds a general git admission slot for its whole run, which on a
+ * large backlog is minutes, and takes the `packed-refs` lock while it writes.
+ * Any ref deletion needs that same lock and gives up after
+ * `core.packedRefsTimeout` (1s), so worktree removal in particular has to veto
+ * this -- as does a create in flight, an agent mid-run, and shutdown. Battery is
+ * a veto too: this is work the user did not ask for, and a plugged-in quiet
+ * window always comes along later.
+ */
+export type RepoMaintenanceIdleInputs = {
+  isQuitting: () => boolean
+  getWorkingAgentCount: () => number
+}
+
+export function installRepoMaintenanceIdleGate(
+  inputs: RepoMaintenanceIdleInputs
+): () => Promise<void> {
+  setRepoMaintenanceActivityProbe(
+    () =>
+      inputs.isQuitting() ||
+      inputs.getWorkingAgentCount() > 0 ||
+      hasPendingWorktreeCreatePreparations() ||
+      hasWorktreeRemovalsInFlight() ||
+      isOnBatteryPower()
+  )
+  // Do-not-start, never stop-what-is-running. Killing a pack to honour a battery
+  // or focus change would strand a ref lock roughly one time in five to save at
+  // most a couple of minutes of background unlinking; pushing the next attempt
+  // out costs nothing and risks nothing.
+  const onBattery = (): void => {
+    postponeRepoRefMaintenance()
+  }
+  const onFocus = (): void => {
+    postponeRepoRefMaintenance()
+  }
+  powerMonitor.on('on-battery', onBattery)
+  app.on('browser-window-focus', onFocus)
+  return () => {
+    app.off('browser-window-focus', onFocus)
+    powerMonitor.off('on-battery', onBattery)
+    // Order matters: clearing the probe alone would leave armed timers running
+    // against a gate that can no longer see agents, creates, or shutdown.
+    const stopped = disposeLocalRepoRefMaintenance()
+    setRepoMaintenanceActivityProbe(null)
+    return stopped
+  }
+}
+
+function isOnBatteryPower(): boolean {
+  try {
+    return powerMonitor.isOnBatteryPower()
+  } catch {
+    // Absence of the API is not evidence of battery; desktops answer false anyway.
+    return false
+  }
+}
diff --git a/src/main/runtime/fetch-remote-cache.test.ts b/src/main/runtime/fetch-remote-cache.test.ts
index fc2d761c059..c97966c344e 100644
--- a/src/main/runtime/fetch-remote-cache.test.ts
+++ b/src/main/runtime/fetch-remote-cache.test.ts
@@ -133,9 +133,11 @@ describe('OrcaRuntimeService.fetchRemoteWithCache', () => {
     const first = runtime.fetchRemoteWithCache('/repo/c', 'origin')
     const second = runtime.fetchRemoteWithCache('/repo/c', 'origin')
 
-    // Allow both callers to register before we resolve.
-    await Promise.resolve()
-    await Promise.resolve()
+    // Allow both callers to register before we resolve. Each canonicalizes the
+    // repo key first, so the dispatch lands several microtasks in.
+    for (let tick = 0; tick < 8; tick += 1) {
+      await Promise.resolve()
+    }
     expect(fetchCallCount()).toBe(1)
 
     resolveFetch()
diff --git a/src/main/runtime/runtime-remote-fetch-controller.ts b/src/main/runtime/runtime-remote-fetch-controller.ts
index c48a8437a3d..b3b9df5dcba 100644
--- a/src/main/runtime/runtime-remote-fetch-controller.ts
+++ b/src/main/runtime/runtime-remote-fetch-controller.ts
@@ -1,4 +1,9 @@
 import { GIT_FETCH_SKIP_AUTO_MAINTENANCE_CONFIG_ARGS } from '../../shared/git-fetch-auto-maintenance'
+import { getCanonicalRepoKey } from '../git/canonical-repo-key'
+import {
+  armLocalRepoRefMaintenance,
+  setRepoRefMaintenanceBusyProbe
+} from '../git/local-repo-ref-maintenance'
 import { gitExecFileAsync } from '../git/runner'
 import { setBoundedMapEntry } from './runtime-async-boundaries'
 
@@ -33,6 +38,11 @@ export class RuntimeRemoteFetchController {
     return this.fetchLastCompletedAt
   }
 
+  /** `${runtimeKey}::${gitCommonDir}` -- one repo on one execution host. */
+  async getCanonicalRepoKey(repoPath: string, gitOptions: GitOptions = {}): Promise<string> {
+    return getCanonicalRepoKey(repoPath, gitOptions)
+  }
+
   async getCanonicalFetchKey(
     repoPath: string,
     remote: string,
@@ -45,23 +55,41 @@ export class RuntimeRemoteFetchController {
       setBoundedMapEntry(this.canonicalFetchKeyCache, cacheKey, cached, REMOTE_FETCH_CACHE_MAX)
       return cached
     }
-    let resolved = cacheKey
-    try {
-      const { stdout } = await gitExecFileAsync(
-        ['rev-parse', '--path-format=absolute', '--git-common-dir'],
-        { cwd: repoPath, ...gitOptions }
-      )
-      const commonDir = stdout.trim()
-      if (commonDir) {
-        resolved = `${runtimeKey}::${commonDir}::${remote}`
-      }
-    } catch {
-      // The caller path remains a safe serialization key when canonicalization fails.
-    }
+    const resolved = `${await this.getCanonicalRepoKey(repoPath, gitOptions)}::${remote}`
     setBoundedMapEntry(this.canonicalFetchKeyCache, cacheKey, resolved, REMOTE_FETCH_CACHE_MAX)
     return resolved
   }
 
+  /**
+   * Orca strips git's auto-maintenance off these fetches, so every one of them
+   * adds to a loose-ref backlog nothing else will ever pack. Arm the idle sweep
+   * that pays it back; each fetch pushes the attempt a further quiet period out.
+   */
+  private armRefMaintenance(repoPath: string, gitOptions: GitOptions): void {
+    void this.getCanonicalRepoKey(repoPath, gitOptions)
+      .then((key) => {
+        setRepoRefMaintenanceBusyProbe(key, () => this.hasInflightFetchForRepo(key))
+        armLocalRepoRefMaintenance({
+          key,
+          repoPath,
+          ...(gitOptions.wslDistro ? { wslDistro: gitOptions.wslDistro } : {})
+        })
+      })
+      .catch(() => {
+        // Maintenance is best effort; a repo we cannot name is a repo we skip.
+      })
+  }
+
+  private hasInflightFetchForRepo(repoKey: string): boolean {
+    const prefix = `${repoKey}::`
+    for (const key of this.fetchInflight.keys()) {
+      if (key.startsWith(prefix)) {
+        return true
+      }
+    }
+    return false
+  }
+
   private enqueueRemoteFetch(
     remoteKey: string,
     runFetch: () => Promise<RemoteFetchResult>
@@ -123,6 +151,7 @@ export class RuntimeRemoteFetchController {
         })
     ).finally(() => {
       this.fetchInflight.delete(key)
+      this.armRefMaintenance(repoPath, gitOptions)
     })
     this.fetchInflight.set(key, promise)
     return promise
@@ -178,6 +207,7 @@ export class RuntimeRemoteFetchController {
         })
     }).finally(() => {
       this.fetchInflight.delete(key)
+      this.armRefMaintenance(repoPath, gitOptions)
     })
     this.fetchInflight.set(key, promise)
     return promise
diff --git a/src/main/runtime/runtime-remote-fetch-ref-maintenance.test.ts b/src/main/runtime/runtime-remote-fetch-ref-maintenance.test.ts
new file mode 100644
index 00000000000..f577da24854
--- /dev/null
+++ b/src/main/runtime/runtime-remote-fetch-ref-maintenance.test.ts
@@ -0,0 +1,145 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+// Why: Orca's fetches are what create the loose-ref backlog (they suppress
+// git's auto-maintenance), so the fetch controller is where the idle sweep has
+// to be armed. These tests pin that wiring and the per-repo busy signal it
+// hands the sweep.
+
+const gitExecFileAsyncMock = vi.hoisted(() => vi.fn())
+const armMock = vi.hoisted(() => vi.fn())
+const busyProbeMock = vi.hoisted(() => vi.fn())
+
+vi.mock('../git/runner', async (importOriginal) => ({
+  ...((await importOriginal()) as Record<string, unknown>),
+  gitExecFileAsync: gitExecFileAsyncMock
+}))
+
+vi.mock('../git/local-repo-ref-maintenance', async (importOriginal) => ({
+  ...((await importOriginal()) as Record<string, unknown>),
+  armLocalRepoRefMaintenance: armMock,
+  setRepoRefMaintenanceBusyProbe: busyProbeMock
+}))
+
+import { _resetCanonicalRepoKeyCacheForTests } from '../git/canonical-repo-key'
+import { RuntimeRemoteFetchController } from './runtime-remote-fetch-controller'
+
+function armedTargets(): { key: string }[] {
+  return armMock.mock.calls.map(([args]) => args as { key: string })
+}
+
+/** The per-repo "a fetch is in flight" answer the controller registers for a key. */
+function busyProbeFor(key: string): (() => boolean) | undefined {
+  return busyProbeMock.mock.calls.findLast(([registered]) => registered === key)?.[1] as
+    | (() => boolean)
+    | undefined
+}
+
+beforeEach(() => {
+  _resetCanonicalRepoKeyCacheForTests()
+  gitExecFileAsyncMock.mockReset()
+  armMock.mockReset()
+  busyProbeMock.mockReset()
+  gitExecFileAsyncMock.mockImplementation(async (argv: string[]) =>
+    argv[0] === 'rev-parse' ? { stdout: '/repo/.git\n', stderr: '' } : { stdout: '', stderr: '' }
+  )
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+describe('fetch-armed ref maintenance', () => {
+  it('arms the sweep for the repo after a remote fetch, keyed by common dir', async () => {
+    const controller = new RuntimeRemoteFetchController()
+
+    await controller.getOrStartRemoteFetch('/repo/worktrees/a', 'origin')
+
+    expect(armedTargets().map((target) => target.key)).toEqual(['local::/repo/.git'])
+  })
+
+  it('gives every worktree of one repo the same maintenance key', async () => {
+    const controller = new RuntimeRemoteFetchController()
+
+    await controller.getOrStartRemoteFetch('/repo/worktrees/a', 'origin')
+    await controller.getOrStartRemoteTrackingBaseRefresh('/repo/worktrees/b', {
+      remote: 'origin',
+      branch: 'main',
+      ref: 'refs/remotes/origin/main',
+      base: 'origin/main'
+    })
+
+    const keys = new Set(armedTargets().map((target) => target.key))
+    expect(keys).toEqual(new Set(['local::/repo/.git']))
+  })
+
+  it('scopes the key to the WSL distro that executes the repo', async () => {
+    const controller = new RuntimeRemoteFetchController()
+
+    await controller.getOrStartRemoteFetch('//wsl$/Ubuntu/repo', 'origin', {
+      wslDistro: 'Ubuntu'
+    })
+
+    expect(armedTargets()[0]?.key).toBe('wsl:Ubuntu::/repo/.git')
+  })
+
+  it('does not collapse every repo onto one key on Git older than 2.31', async () => {
+    // Old Git echoes the unrecognized `--path-format` flag, exits 0, and prints a
+    // relative `.git`; taking that raw would name every repository identically.
+    gitExecFileAsyncMock.mockImplementation(async (argv: string[]) =>
+      argv[0] === 'rev-parse'
+        ? { stdout: '--path-format=absolute\n.git\n', stderr: '' }
+        : { stdout: '', stderr: '' }
+    )
+    const controller = new RuntimeRemoteFetchController()
+
+    await controller.getOrStartRemoteFetch('/repo/one', 'origin')
+    await controller.getOrStartRemoteFetch('/repo/two', 'origin')
+
+    expect(armedTargets().map((entry) => entry.key)).toEqual([
+      'local::/repo/one/.git',
+      'local::/repo/two/.git'
+    ])
+  })
+
+  it('reports the repo as busy while another fetch on it is in flight', async () => {
+    const controller = new RuntimeRemoteFetchController()
+    await controller.getOrStartRemoteFetch('/repo', 'first')
+    const isBusy = busyProbeFor('local::/repo/.git')
+    expect(isBusy?.()).toBe(false)
+
+    let releaseFetch: (() => void) | undefined
+    gitExecFileAsyncMock.mockImplementation(async (argv: string[]) => {
+      if (argv[0] === 'rev-parse') {
+        return { stdout: '/repo/.git\n', stderr: '' }
+      }
+      await new Promise<void>((resolve) => {
+        releaseFetch = resolve
+      })
+      return { stdout: '', stderr: '' }
+    })
+    const second = controller.getOrStartRemoteFetch('/repo', 'second')
+    await vi.waitFor(() => expect(releaseFetch).toBeDefined())
+    expect(isBusy?.()).toBe(true)
+
+    releaseFetch?.()
+    await second
+    expect(isBusy?.()).toBe(false)
+  })
+
+  it('arms even when the fetch fails, because a partial fetch still writes refs', async () => {
+    const controller = new RuntimeRemoteFetchController()
+    gitExecFileAsyncMock.mockImplementation(async (argv: string[]) => {
+      if (argv[0] === 'rev-parse') {
+        return { stdout: '/repo/.git\n', stderr: '' }
+      }
+      throw new Error('network is unreachable')
+    })
+    vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    await expect(controller.getOrStartRemoteFetch('/repo', 'origin')).resolves.toEqual({
+      ok: false,
+      errorKind: 'git_error'
+    })
+    expect(armedTargets()).toHaveLength(1)
+  })
+})
diff --git a/src/main/startup/main-process-observers.ts b/src/main/startup/main-process-observers.ts
index c3d83450b7c..ba37b0a312f 100644
--- a/src/main/startup/main-process-observers.ts
+++ b/src/main/startup/main-process-observers.ts
@@ -18,6 +18,7 @@ import { AgentSessionTransitionRecorder } from '../stats/agent-session-transitio
 import { ClaudeUsageStore } from '../claude-usage/store'
 import { CodexUsageStore } from '../codex-usage/store'
 import { OpenCodeUsageStore } from '../opencode-usage/store'
+import { installRepoMaintenanceIdleGate } from '../repo-maintenance-idle-gate'
 import { mainProcessState as state } from './main-process-state'
 
 export function initializeMainProcessObservers(): void {
@@ -35,6 +36,10 @@ export function initializeMainProcessObservers(): void {
   )
   // Why: start from empty — disk-hydrated status rows are UI continuity only; only this runtime's hook events keep the computer awake.
   state.agentAwakeService.setStatuses([])
+  state.uninstallRepoMaintenanceIdleGate = installRepoMaintenanceIdleGate({
+    isQuitting: () => state.isQuitting,
+    getWorkingAgentCount: () => state.agentAwakeService?.getWorkingAgentCount() ?? 0
+  })
   const collectChangedProviderSessionWorktrees = createHookProviderSessionInvalidator()
   const publishProviderSessionChanges = (identities: AgentHookProviderSessionIdentity[]): void => {
     const ownedIdentities = identities.map((identity) => ({
diff --git a/src/main/startup/main-process-quit.ts b/src/main/startup/main-process-quit.ts
index ec893456c5a..61203bc3164 100644
--- a/src/main/startup/main-process-quit.ts
+++ b/src/main/startup/main-process-quit.ts
@@ -14,6 +14,7 @@ import { clearRuntimeMetadataIfOwned } from '../runtime/runtime-metadata'
 import { shutdownPairedRuntimeBrowserClientHosts } from '../browser/paired-runtime-browser-client-host-runtime'
 import { browserManager } from '../browser/browser-manager'
 import { stopCodexStateDbBackfillRecoveries } from '../codex/codex-state-db-backfill-recovery'
+import { awaitPackedRefsLockRelease } from '../git/local-repo-ref-maintenance'
 import { settleTeardownWithinDeadline, settleWithinMs } from '../quit-teardown-deadline'
 import { quitTeardownStartGate } from '../quit-teardown-start-gate'
 import { setUnreadDockBadgeCount } from '../dock/unread-badge'
@@ -33,6 +34,8 @@ let daemonDisconnectDone = false
 let watcherShutdownPromise: Promise<void> | null = null
 // Why 2s: a config delete is best-effort, not durable state.
 const GROK_HOOK_CLEANUP_DEADLINE_MS = 2_000
+// Why 2s: long enough for a `pack-refs` child to take SIGTERM and unlink its lock.
+const REF_MAINTENANCE_QUIT_DEADLINE_MS = 2_000
 
 function shutdownWatchersOnce(): Promise<void> {
   if (state.watcherShutdownDone) {
@@ -73,6 +76,10 @@ function installBeforeQuitHandler(): void {
     state.unsubscribeAgentAwakeStatusChanges = null
     state.agentAwakeService?.dispose()
     state.agentAwakeService = null
+    // Why wait but not uninstall: a renderer beforeunload can still veto this
+    // quit, and tearing the sweep down here would kill it for the rest of the
+    // session. `isQuitting` already vetoes new attempts; will-quit does the teardown.
+    state.repoMaintenanceShutdown = awaitPackedRefsLockRelease()
     // Why: defer PTY cleanup to will-quit so the renderer captures scrollback before PTY-exit events unmount TerminalPane (dropping its capture callbacks).
     state.rateLimits?.stop()
   })
@@ -123,6 +130,16 @@ function installWillQuitHandler(): void {
     const structuredAgentSessionShutdown = stopStructuredAgentSessionRuntime()
     state.pluginService = null
     setUnreadDockBadgeCount(0)
+    // Why wait rather than kill: the child finishes fine orphaned, and signalling
+    // it mid-prune strands a ref lock Git never clears. The wait is only for the
+    // short rewrite window, and is bounded so a quit can never hang on it.
+    const refMaintenanceShutdown = settleWithinMs(
+      Promise.all([state.repoMaintenanceShutdown, state.uninstallRepoMaintenanceIdleGate?.()]).then(
+        () => {}
+      ),
+      REF_MAINTENANCE_QUIT_DEADLINE_MS
+    ).then(() => {})
+    state.uninstallRepoMaintenanceIdleGate = null
     agentHookServer.stop()
     // Why Windows only: POSIX hooks short-circuit on ORCA_PANE_KEY, while Windows must register a
     // bare script path that cannot express the guard and would otherwise keep spawning after quit.
@@ -219,6 +236,7 @@ function installWillQuitHandler(): void {
       { name: 'plugin-hosts', promise: pluginHostShutdown },
       { name: 'skill-uploads', promise: skillUploadShutdown },
       { name: 'grok-hooks', promise: grokHookCleanup },
+      { name: 'ref-maintenance', promise: refMaintenanceShutdown },
       { name: 'codex-backfill-recovery', promise: codexBackfillRecoveryShutdown },
       { name: 'structured-agent-session', promise: structuredAgentSessionShutdown },
       { name: 'usage-cache', promise: usageCacheFlush },
diff --git a/src/main/startup/main-process-state.ts b/src/main/startup/main-process-state.ts
index 05c45d5b567..d48219b461e 100644
--- a/src/main/startup/main-process-state.ts
+++ b/src/main/startup/main-process-state.ts
@@ -71,6 +71,8 @@ export const mainProcessState = {
   headlessBrowserDisplayAvailable: false,
   starNag: null as StarNagService | null,
   agentAwakeService: null as AgentAwakeService | null,
+  uninstallRepoMaintenanceIdleGate: null as (() => Promise<void>) | null,
+  repoMaintenanceShutdown: Promise.resolve() as Promise<void>,
   crashReports: null as CrashReportStore | null,
   unsubscribeAgentAwakeStatusChanges: null as (() => void) | null,
   publishProviderSessionChanges: null as
diff --git a/src/main/worktree-create-preparation.ts b/src/main/worktree-create-preparation.ts
index 22bcf5d1e2c..b4d86923490 100644
--- a/src/main/worktree-create-preparation.ts
+++ b/src/main/worktree-create-preparation.ts
@@ -61,6 +61,11 @@ type ConsumePreparedWorktreeArgs = {
 
 const preparations = new Map<string, PreparationEntry>()
 
+/** A prepared checkout is a create that is either in flight or imminent. */
+export function hasPendingWorktreeCreatePreparations(): boolean {
+  return preparations.size > 0 || staleCleanupInFlight.size > 0
+}
+
 function pathOps(path: string): Pick<typeof posix, 'dirname' | 'join' | 'normalize'> {
   return isWindowsAbsolutePathLike(path) ? win32 : posix
 }
diff --git a/src/shared/git-binary-compatibility.test.ts b/src/shared/git-binary-compatibility.test.ts
index 3a8f562dff1..2861c447788 100644
--- a/src/shared/git-binary-compatibility.test.ts
+++ b/src/shared/git-binary-compatibility.test.ts
@@ -277,6 +277,39 @@ describeBinaryCompatibility('real Git binary compatibility', () => {
     ).rejects.toMatchObject({ code: 1 })
   })
 
+  it('packs loose refs and reads the maintenance opt-out at the baseline', async () => {
+    // Why: idle ref maintenance runs `pack-refs --all --prune` on every supported
+    // Git rather than the 2.45+ `--auto` form, and reads `maintenance.auto` to
+    // honour a user who disabled Git's own auto-maintenance. Both must work at 2.25.
+    const head = (await runGit(['rev-parse', 'HEAD'])).stdout.trim()
+    const packedRef = 'refs/remotes/origin/compat-pack-refs'
+    await runGit(['update-ref', packedRef, head])
+    await expect(readFile(join(repoPath, '.git', packedRef), 'utf-8')).resolves.toContain(head)
+
+    await expect(runGit(['pack-refs', '--all', '--prune'])).resolves.toBeDefined()
+
+    // The loose file is gone and the ref still resolves through packed-refs.
+    await expect(readFile(join(repoPath, '.git', packedRef), 'utf-8')).rejects.toMatchObject({
+      code: 'ENOENT'
+    })
+    await expect(runGit(['rev-parse', '--verify', packedRef])).resolves.toMatchObject({
+      stdout: `${head}\n`
+    })
+    await expect(readFile(join(repoPath, '.git', 'packed-refs'), 'utf-8')).resolves.toContain(
+      packedRef
+    )
+
+    // `--get` exits 1 on an unset key; that absence must read as consent, not opt-out.
+    await expect(runGit(['config', '--bool', '--get', 'maintenance.auto'])).rejects.toMatchObject({
+      code: 1
+    })
+    await runGit(['config', 'maintenance.auto', 'false'])
+    await expect(runGit(['config', '--bool', '--get', 'maintenance.auto'])).resolves.toMatchObject({
+      stdout: 'false\n'
+    })
+    await runGit(['config', '--unset', 'maintenance.auto'])
+  })
+
   it('fetches hosted review heads into dedicated refs', async () => {
     const head = (await runGit(['rev-parse', 'HEAD'])).stdout.trim()
     await runGit(['update-ref', 'refs/pull/42/head', head])
diff --git a/src/shared/loose-ref-count.test.ts b/src/shared/loose-ref-count.test.ts
new file mode 100644
index 00000000000..c69f655121a
--- /dev/null
+++ b/src/shared/loose-ref-count.test.ts
@@ -0,0 +1,119 @@
+import { mkdir, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+// Wraps the real `readdir` so the walk's concurrency is observable without
+// changing what it reads.
+const readdirCalls = vi.hoisted(() => ({ outstanding: 0, peak: 0, count: 0 }))
+
+vi.mock('node:fs/promises', async (importOriginal) => {
+  const actual = await importOriginal<Record<string, unknown>>()
+  const realReaddir = actual.readdir as (...args: unknown[]) => Promise<never>
+  return {
+    ...actual,
+    readdir: async (...args: unknown[]) => {
+      readdirCalls.outstanding += 1
+      readdirCalls.count += 1
+      readdirCalls.peak = Math.max(readdirCalls.peak, readdirCalls.outstanding)
+      try {
+        return await realReaddir(...args)
+      } finally {
+        readdirCalls.outstanding -= 1
+      }
+    }
+  }
+})
+
+import { countLooseRefs } from './loose-ref-count'
+
+const roots: string[] = []
+
+async function makeRefsTree(counts: Record<string, number>): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), 'orca-loose-refs-'))
+  roots.push(root)
+  const refs = join(root, 'refs')
+  for (const [namespace, count] of Object.entries(counts)) {
+    const directory = join(refs, namespace)
+    await mkdir(directory, { recursive: true })
+    for (let index = 0; index < count; index += 1) {
+      await writeFile(join(directory, `ref-${index}`), 'a'.repeat(40))
+    }
+  }
+  await mkdir(refs, { recursive: true })
+  return refs
+}
+
+afterEach(async () => {
+  vi.restoreAllMocks()
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })))
+})
+
+describe('countLooseRefs', () => {
+  it('counts files across nested namespaces', async () => {
+    const refs = await makeRefsTree({ heads: 3, 'remotes/origin': 4, 'remotes/fork/deep': 2 })
+
+    await expect(countLooseRefs(refs, 100)).resolves.toEqual({ count: 9, saturated: false })
+  })
+
+  it('stops at the budget instead of walking the whole backlog', async () => {
+    const refs = await makeRefsTree({ 'remotes/origin': 500 })
+
+    const result = await countLooseRefs(refs, 10)
+
+    expect(result).toEqual({ count: 10, saturated: true })
+  })
+
+  it('reports zero for a repository with no refs directory', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'orca-loose-refs-missing-'))
+    roots.push(root)
+
+    await expect(countLooseRefs(join(root, 'refs'), 100)).resolves.toEqual({
+      count: 0,
+      saturated: false
+    })
+  })
+
+  it('never has more than one directory read outstanding', async () => {
+    // libuv's filesystem thread pool has four slots shared with the whole main
+    // process. A probe that fanned out would stall unrelated fs work, so this
+    // pins the walk as strictly sequential rather than merely bounded.
+    const refs = await makeRefsTree({
+      'remotes/a': 3,
+      'remotes/b': 3,
+      'remotes/c': 3,
+      'remotes/d': 3,
+      'remotes/e/deep': 3
+    })
+    readdirCalls.peak = 0
+    readdirCalls.count = 0
+
+    await countLooseRefs(refs, 1000)
+
+    expect(readdirCalls.count).toBeGreaterThan(1)
+    expect(readdirCalls.peak).toBe(1)
+  })
+
+  it('reads each directory once rather than streaming it in batches', async () => {
+    // One thread-pool round trip per directory is what makes the probe ~8x
+    // cheaper than the streaming form on a real degraded repository.
+    const refs = await makeRefsTree({ 'remotes/origin': 400 })
+    readdirCalls.count = 0
+
+    await countLooseRefs(refs, 1000)
+
+    // refs/ plus refs/remotes plus refs/remotes/origin.
+    expect(readdirCalls.count).toBe(3)
+  })
+
+  it('does not follow directory symlinks into a loop', async () => {
+    const refs = await makeRefsTree({ heads: 2 })
+    await symlink(refs, join(refs, 'loop'), 'dir')
+
+    const result = await countLooseRefs(refs, 100)
+
+    expect(result.saturated).toBe(false)
+    // The symlink is one dirent, never a second traversal of the tree.
+    expect(result.count).toBe(3)
+  })
+})
diff --git a/src/shared/loose-ref-count.ts b/src/shared/loose-ref-count.ts
new file mode 100644
index 00000000000..8f31d8b03a8
--- /dev/null
+++ b/src/shared/loose-ref-count.ts
@@ -0,0 +1,80 @@
+import { readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+
+export type LooseRefCount = {
+  /** Loose ref files seen, never above `budget`. */
+  count: number
+  /** The walk stopped early, so `count` is a floor rather than the total. */
+  saturated: boolean
+}
+
+// Why: a ref tree is shallow and wide; this bounds both the directories visited
+// and the queue holding those still to visit, so neither a symlink loop nor a
+// pathological repo turns a gate probe into an unbounded walk.
+const DIRECTORY_VISIT_CEILING = 4096
+
+/**
+ * Count loose refs under a repository's `refs/` directory, stopping at `budget`.
+ *
+ * Deliberately budgeted: callers use this as an admission gate, so the cost has
+ * to be bounded by the threshold being tested and not by the size of the
+ * backlog it is testing for.
+ *
+ * One `readdir` per directory, dirents only -- no `stat` per entry, and no
+ * `opendir` streaming. Measured against a real 36,600-loose-ref repository, the
+ * batched form is ~8x faster (23ms vs 177ms median to reach a 1000 threshold)
+ * and holds the event loop for less than half as long, because streaming issues
+ * a thread-pool round trip every 32 entries where this issues one per
+ * directory. The cost is holding one directory's dirents at a time, which is
+ * bounded by the widest ref namespace rather than by the size of the tree.
+ *
+ * Strictly sequential on purpose: it awaits one directory before opening the
+ * next, so it can never occupy more than one of libuv's four thread-pool slots
+ * and cannot stall unrelated main-process filesystem work.
+ *
+ * `signal` stops the walk between directories. A single hung `readdir` is not
+ * interruptible, but it holds no Git lock, so it delays only maintenance.
+ */
+export async function countLooseRefs(
+  refsDirectory: string,
+  budget: number,
+  signal?: AbortSignal
+): Promise<LooseRefCount> {
+  const pending = [refsDirectory]
+  let count = 0
+  let visited = 0
+  while (pending.length > 0) {
+    const directory = pending.pop()
+    if (directory === undefined) {
+      break
+    }
+    visited += 1
+    // A cancelled walk reports what it saw as a floor rather than throwing; callers
+    // already have to treat a saturated result as "not known to be clean".
+    if (
+      signal?.aborted === true ||
+      visited > DIRECTORY_VISIT_CEILING ||
+      pending.length > DIRECTORY_VISIT_CEILING
+    ) {
+      return { count, saturated: true }
+    }
+    let entries: { name: string; isDirectory: () => boolean }[]
+    try {
+      entries = await readdir(directory, { withFileTypes: true })
+    } catch {
+      // A missing or unreadable namespace contributes nothing to the count.
+      continue
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        pending.push(join(directory, entry.name))
+        continue
+      }
+      count += 1
+      if (count >= budget) {
+        return { count, saturated: true }
+      }
+    }
+  }
+  return { count, saturated: false }
+}
diff --git a/src/shared/packed-refs-lock-gate.ts b/src/shared/packed-refs-lock-gate.ts
new file mode 100644
index 00000000000..f5cff6b8c4a
--- /dev/null
+++ b/src/shared/packed-refs-lock-gate.ts
@@ -0,0 +1,43 @@
+/**
+ * Tracks the one window in a pack that actually excludes anybody: the
+ * `packed-refs` rewrite. Callers about to touch refs wait this out rather than
+ * killing the child, because a signal delivered into the prune phase strands a
+ * `refs/**\/*.lock` roughly one time in five and Git never clears those.
+ */
+export class PackedRefsLockGate {
+  private held = false
+  private waiters: (() => void)[] = []
+
+  setHeld(held: boolean): void {
+    this.held = held
+    if (held) {
+      return
+    }
+    const waiting = this.waiters
+    this.waiters = []
+    for (const resolve of waiting) {
+      resolve()
+    }
+  }
+
+  /** Resolves on release, or on `timeoutMs` -- past which Git's own retry is the better bet. */
+  whenReleased(timeoutMs: number): Promise<void> {
+    if (!this.held) {
+      return Promise.resolve()
+    }
+    return new Promise<void>((resolve) => {
+      let settled = false
+      const finish = (): void => {
+        if (settled) {
+          return
+        }
+        settled = true
+        clearTimeout(timer)
+        resolve()
+      }
+      const timer = setTimeout(finish, timeoutMs)
+      timer.unref?.()
+      this.waiters.push(finish)
+    })
+  }
+}
diff --git a/src/shared/repo-ref-maintenance-policy.ts b/src/shared/repo-ref-maintenance-policy.ts
new file mode 100644
index 00000000000..7dc8edd1de3
--- /dev/null
+++ b/src/shared/repo-ref-maintenance-policy.ts
@@ -0,0 +1,166 @@
+/**
+ * Idle-time loose-ref packing for repositories Orca itself degrades.
+ *
+ * Orca strips git's auto-maintenance off its own frequent fetches
+ * (`GIT_FETCH_SKIP_AUTO_MAINTENANCE_CONFIG_ARGS`) and never compensated, so an
+ * Orca-driven checkout accumulates loose refs forever and every ref
+ * enumeration -- `show-ref`, `for-each-ref`, worktree create -- pays for them.
+ * This is the compensation: after a repo goes quiet, probe it, and pack only
+ * when the backlog is real.
+ *
+ * The engine is host-agnostic on purpose. The execution host owns everything
+ * that touches execution, so each host supplies its own target (which git to
+ * run, which filesystem to walk) and all state here is keyed per host.
+ */
+
+/**
+ * Below this, ref enumeration is already fast and `pack-refs` would cost more
+ * than it saves.
+ *
+ * Git's own files-backend auto heuristic (2.47+) packs at
+ * `max(16, log2(packed_refs_bytes / 100) * 5)` loose refs -- about 76 for the
+ * 4.1 MB `packed-refs` that motivated this work. A flat 1000 is roughly an
+ * order of magnitude more conservative on purpose: this runs unasked against a
+ * real checkout, and being late is cheap where being wrong is not.
+ */
+export const LOOSE_REF_PACK_THRESHOLD = 1000
+
+/** No fetch, create, or other tracked write on the repo for this long. */
+export const REF_MAINTENANCE_QUIET_PERIOD_MS = 10 * 60_000
+
+/** Packing empties the backlog; there is nothing to do again for a long while. */
+export const REF_MAINTENANCE_PACKED_COOLDOWN_MS = 12 * 60 * 60_000
+
+/** A healthy or unresolvable repo should not be re-probed on every quiet window. */
+export const REF_MAINTENANCE_CLEAN_COOLDOWN_MS = 6 * 60 * 60_000
+
+/** A failing repo (permissions, stale lock) must not be retried in a loop. */
+export const REF_MAINTENANCE_FAILURE_COOLDOWN_MS = 6 * 60 * 60_000
+
+/**
+ * A repository whose `packed-refs.lock` is a strand from our own dead process
+ * becomes reclaimable at `PACK_REFS_TIMEOUT_MS`, so retry near that rather than
+ * serving the full failure cooldown -- otherwise a Windows force-kill leaves
+ * every ref deletion in that repo failing for six hours instead of thirty
+ * minutes.
+ */
+export const REF_MAINTENANCE_LOCKED_COOLDOWN_MS = 30 * 60_000
+
+/**
+ * `pack-refs` holds `packed-refs.lock` only while it rewrites the file --
+ * measured at 0.03-1.37s of a 23-32s run, the other ~95% being the prune phase
+ * unlinking loose refs. A caller about to touch refs waits out that window
+ * instead of killing the pack.
+ */
+export const PACKED_REFS_LOCK_POLL_MS = 50
+
+/**
+ * Ceiling on that wait. Past this we stop blocking the user and let Git's own
+ * retry (`core.filesRefLockTimeout`, `core.packedRefsTimeout`) handle it, which
+ * is what happens today without any of this.
+ */
+export const PACKED_REFS_LOCK_WAIT_MS = 5_000
+
+/**
+ * `pack-refs --prune` unlinks one file per loose ref. Paying off a 36k-ref
+ * backlog measured at ~83s on APFS, so the deadline has to clear a cold repo on
+ * a slow disk by a wide margin. A kill mid-run is safe -- git renames
+ * `packed-refs` into place atomically and the surviving loose refs stay
+ * authoritative -- but it wastes the work.
+ */
+export const PACK_REFS_TIMEOUT_MS = 15 * 60_000
+
+/**
+ * Ancient, safe on the Git 2.25 baseline, and does exactly one thing.
+ *
+ * Not `pack-refs --auto`: that arrived in 2.45 and unconditionally rewrote
+ * `packed-refs` on the files backend until 2.47, so it is both unavailable at
+ * our baseline and wrong on two shipped releases. Not `git maintenance run`
+ * either -- newer, and it pulls in commit-graph and repack work we did not ask
+ * for. `--all` is required because the backlog is `refs/heads` and
+ * `refs/remotes`, which a bare `pack-refs` leaves alone.
+ */
+export const PACK_REFS_ARGS = ['pack-refs', '--all', '--prune'] as const
+
+/**
+ * Backstop on a whole attempt: aborts it, rather than abandoning it. Every Git
+ * child is already deadlined, but an admission wait is not, and the whole app
+ * shares one maintenance slot. Abandoning would release that slot while a pack
+ * that may still hold `packed-refs.lock` runs on, so the deadline cancels the
+ * work instead and the slot is held until it really stops.
+ */
+export const REF_MAINTENANCE_ATTEMPT_DEADLINE_MS = PACK_REFS_TIMEOUT_MS + 5 * 60_000
+
+export type RefMaintenanceOutcome =
+  | 'packed'
+  | 'below_threshold'
+  | 'unresolved'
+  | 'opted_out'
+  | 'deferred'
+  | 'interrupted'
+  | 'locked'
+  | 'timed_out'
+  | 'failed'
+
+/** Structurally satisfied by the tracer's `ActiveSpan`. */
+export type RefMaintenanceSpan = {
+  setAttribute(key: string, value: unknown): void
+}
+
+export type RepoRefMaintenanceTarget = {
+  /** Repo identity scoped to its execution host; all state here is keyed by it. */
+  readonly key: string
+  /** Absolute `refs/` path *on the host that runs the walk*, or undefined if unresolvable. */
+  resolveRefsDirectory(signal: AbortSignal): Promise<string | undefined>
+  /** A user who told Git not to auto-maintain this repo has told Orca too. */
+  isOptedOut?(signal: AbortSignal): Promise<boolean>
+  /** True while work on *this repo* is in flight -- a fetch, a create, a removal. */
+  isBusy?(): boolean
+  /**
+   * Runs `pack-refs` to completion. Deliberately takes no abort signal: killing
+   * a pack is measurably worse than waiting for it (see `PACKED_REFS_LOCK_*`).
+   * It must report `packed-refs.lock` transitions through `lock` so callers can
+   * wait for the short window that actually blocks them.
+   */
+  packRefs(lock: PackedRefsLockReporter): Promise<void>
+}
+
+/** How `packRefs` tells the scheduler whether the exclusive write window is open. */
+export type PackedRefsLockReporter = {
+  setHeld(held: boolean): void
+}
+
+export type RepoRefMaintenanceOptions = {
+  now?: () => number
+  /** True while app-wide work this must not race is in flight (create, live agent, battery, quit). */
+  isBusy?: () => boolean
+  /** Wraps one attempt so a host can trace it; must invoke and await `attempt`. */
+  observe?: (attempt: (span: RefMaintenanceSpan) => Promise<void>) => Promise<void>
+  quietPeriodMs?: number
+  looseRefThreshold?: number
+  onError?: (error: unknown) => void
+}
+
+/** Marks an abort Orca asked for, so the attempt is retried rather than blamed on the repo. */
+export class RefMaintenanceInterrupted extends Error {
+  constructor(
+    reason: string,
+    /** True when the attempt ran out of time rather than yielding to real work. */
+    readonly deadline = false
+  ) {
+    super(`Ref maintenance interrupted: ${reason}`)
+    this.name = 'RefMaintenanceInterrupted'
+  }
+}
+
+/**
+ * The repository's `packed-refs.lock` is held by something we must not touch.
+ * Distinct from a failure so a strand our own dead process left can be retried
+ * once it ages into reclaimability, rather than parked for six hours.
+ */
+export class RefMaintenanceRepoLocked extends Error {
+  constructor(detail: string) {
+    super(`packed-refs.lock is held: ${detail}`)
+    this.name = 'RefMaintenanceRepoLocked'
+  }
+}
diff --git a/src/shared/repo-ref-maintenance.test.ts b/src/shared/repo-ref-maintenance.test.ts
new file mode 100644
index 00000000000..f59b894748f
--- /dev/null
+++ b/src/shared/repo-ref-maintenance.test.ts
@@ -0,0 +1,530 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { RepoRefMaintenance } from './repo-ref-maintenance'
+import {
+  RefMaintenanceRepoLocked,
+  REF_MAINTENANCE_PACKED_COOLDOWN_MS,
+  PACKED_REFS_LOCK_WAIT_MS,
+  type PackedRefsLockReporter,
+  type RefMaintenanceSpan,
+  type RepoRefMaintenanceOptions,
+  type RepoRefMaintenanceTarget
+} from './repo-ref-maintenance-policy'
+
+const QUIET_MS = 1000
+const THRESHOLD = 5
+const roots: string[] = []
+
+async function refsDirectoryWith(looseRefs: number): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), 'orca-ref-maintenance-'))
+  roots.push(root)
+  const refs = join(root, 'refs', 'remotes', 'origin')
+  await mkdir(refs, { recursive: true })
+  for (let index = 0; index < looseRefs; index += 1) {
+    await writeFile(join(refs, `ref-${index}`), 'a')
+  }
+  return join(root, 'refs')
+}
+
+/** More directories than `countLooseRefs` will visit, but very few files. */
+async function saturatingRefsDirectory(): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), 'orca-ref-maintenance-wide-'))
+  roots.push(root)
+  const refs = join(root, 'refs')
+  for (let index = 0; index < 4200; index += 1) {
+    await mkdir(join(refs, `ns-${index}`), { recursive: true })
+  }
+  return refs
+}
+
+/** Stands in for a pack that moved the refs into packed-refs before erroring. */
+async function emptyRefsDirectory(refs: string): Promise<void> {
+  await rm(refs, { recursive: true, force: true })
+}
+
+function attributesOf(span: RefMaintenanceSpan): Record<string, unknown> {
+  return (span as unknown as { recorded: Record<string, unknown> }).recorded
+}
+
+function recordingSpan(): RefMaintenanceSpan {
+  const recorded: Record<string, unknown> = {}
+  return {
+    recorded,
+    setAttribute(key: string, value: unknown) {
+      recorded[key] = value
+    }
+  } as unknown as RefMaintenanceSpan
+}
+
+type Harness = {
+  maintenance: RepoRefMaintenance
+  spans: RefMaintenanceSpan[]
+  packRefs: ((lock: PackedRefsLockReporter) => Promise<void>) & { mock: { calls: unknown[] } }
+}
+
+function createHarness(
+  overrides: Partial<RepoRefMaintenanceOptions> & {
+    packRefs?: (lock: PackedRefsLockReporter) => Promise<void>
+  } = {}
+): Harness {
+  const spans: RefMaintenanceSpan[] = []
+  const packRefs = vi.fn<(lock: PackedRefsLockReporter) => Promise<void>>(
+    overrides.packRefs ?? (async () => {})
+  )
+  const maintenance = new RepoRefMaintenance({
+    quietPeriodMs: QUIET_MS,
+    looseRefThreshold: THRESHOLD,
+    now: () => Date.now(),
+    observe: (attempt) => {
+      const span = recordingSpan()
+      spans.push(span)
+      return attempt(span)
+    },
+    ...overrides
+  })
+  return { maintenance, spans, packRefs }
+}
+
+function target(
+  key: string,
+  refsDirectory: string,
+  packRefs: (lock: PackedRefsLockReporter) => Promise<void>,
+  extra: Partial<RepoRefMaintenanceTarget> = {}
+): RepoRefMaintenanceTarget {
+  return {
+    key,
+    resolveRefsDirectory: async () => refsDirectory,
+    packRefs,
+    ...extra
+  }
+}
+
+/** Resolves the first time the pack starts, so tests never race real filesystem I/O. */
+function packStartSignal(): {
+  started: Promise<PackedRefsLockReporter>
+  onStart: (lock: PackedRefsLockReporter) => void
+} {
+  let onStart: (lock: PackedRefsLockReporter) => void = () => {}
+  const started = new Promise<PackedRefsLockReporter>((resolve) => {
+    onStart = resolve
+  })
+  return { started, onStart }
+}
+
+function yieldToIo(): Promise<void> {
+  return new Promise<void>((resolve) => setImmediate(resolve))
+}
+
+/**
+ * Spins the real event loop until `predicate` holds, so filesystem completions
+ * can land while `setTimeout` is faked. Bounded by wall clock rather than by a
+ * turn count: a loaded CI runner exhausts a fixed number of turns long before
+ * the I/O finishes, which fails as a confusing assertion somewhere else.
+ */
+async function until(predicate: () => boolean, what: string): Promise<void> {
+  const deadline = Date.now() + 10_000
+  while (!predicate() && Date.now() < deadline) {
+    await yieldToIo()
+  }
+  if (!predicate()) {
+    throw new Error(`timed out after 10s waiting for ${what}`)
+  }
+}
+
+/**
+ * Like `until`, but for conditions that also need a scheduled retry to fire:
+ * spinning the real loop alone can never satisfy them, because `setTimeout` is
+ * faked. Alternates advancing the fake clock with yielding to real I/O.
+ */
+async function untilWithTimers(predicate: () => boolean, what: string): Promise<void> {
+  const deadline = Date.now() + 10_000
+  while (!predicate() && Date.now() < deadline) {
+    await vi.advanceTimersByTimeAsync(QUIET_MS)
+    await yieldToIo()
+  }
+  if (!predicate()) {
+    throw new Error(`timed out after 10s waiting for ${what}`)
+  }
+}
+
+/** Fires the quiet-period timer and waits for the attempt it starts. */
+async function elapseQuietPeriod(maintenance: RepoRefMaintenance, periods = 1): Promise<void> {
+  await vi.advanceTimersByTimeAsync(QUIET_MS * periods)
+  await maintenance.whenAttemptSettled()
+}
+
+/** Only the quiet-period timer is faked; real filesystem I/O still has to complete. */
+beforeEach(() => {
+  vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] })
+})
+
+afterEach(async () => {
+  vi.useRealTimers()
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })))
+})
+
+describe('RepoRefMaintenance gating', () => {
+  it('packs only after the repo has been quiet for the full period', async () => {
+    const refs = await refsDirectoryWith(THRESHOLD + 2)
+    const { maintenance, spans, packRefs } = createHarness()
+    const repo = target('local::/repo/.git', refs, packRefs)
+
+    maintenance.arm(repo)
+    await vi.advanceTimersByTimeAsync(QUIET_MS - 1)
+    expect(packRefs).not.toHaveBeenCalled()
+
+    // A second write restarts the countdown rather than shortening it.
+    maintenance.arm(repo)
+    await vi.advanceTimersByTimeAsync(QUIET_MS - 1)
+    expect(packRefs).not.toHaveBeenCalled()
+
+    await elapseQuietPeriod(maintenance)
+    expect(packRefs).toHaveBeenCalledTimes(1)
+    expect(attributesOf(spans[0])).toMatchObject({
+      'repo.maintenance_outcome': 'packed',
+      'repo.maintenance_key': 'local::/repo/.git',
+      'git.loose_ref_count': THRESHOLD + 1
+    })
+  })
+
+  it('leaves a healthy repository alone', async () => {
+    const refs = await refsDirectoryWith(THRESHOLD - 1)
+    const { maintenance, spans, packRefs } = createHarness()
+
+    maintenance.arm(target('local::/healthy/.git', refs, packRefs))
+    await elapseQuietPeriod(maintenance)
+
+    expect(packRefs).not.toHaveBeenCalled()
+    expect(attributesOf(spans[0])).toMatchObject({
+      'repo.maintenance_outcome': 'below_threshold',
+      'git.loose_ref_count': THRESHOLD - 1
+    })
+  })
+
+  it('does not run while the app is busy', async () => {
+    const refs = await refsDirectoryWith(THRESHOLD + 2)
+    let busy = true
+    const { maintenance, packRefs } = createHarness({ isBusy: () => busy })
+
+    maintenance.arm(target('local::/busy/.git', refs, packRefs))
+    await elapseQuietPeriod(maintenance)
+    expect(packRefs).not.toHaveBeenCalled()
+
+    // The deferral re-arms on a backed-off delay, so the next window picks it up.
+    busy = false
+    await elapseQuietPeriod(maintenance, 2)
+    expect(packRefs).toHaveBeenCalledTimes(1)
+  })
+
+  it('does not run while the repo itself has work in flight', async () => {
+    const refs = await refsDirectoryWith(THRESHOLD + 2)
+    const { maintenance, packRefs } = createHarness()
+
+    maintenance.arm(target('local::/fetching/.git', refs, packRefs, { isBusy: () => true }))
+    await elapseQuietPeriod(maintenance)
+
+    expect(packRefs).not.toHaveBeenCalled()
+  })
+
+  it('honours a user who disabled Git auto-maintenance for the repo', async () => {
+    const refs = await refsDirectoryWith(THRESHOLD + 2)
+    const { maintenance, spans, packRefs } = createHarness()
+
+    maintenance.arm(
+      target('local::/opted-out/.git', refs, packRefs, { isOptedOut: async () => true })
+    )
+    await elapseQuietPeriod(maintenance)
+
+    expect(packRefs).not.toHaveBeenCalled()
+    expect(attributesOf(spans[0])['repo.maintenance_outcome']).toBe('opted_out')
+  })
+
+  it('never reads a truncated walk as a clean repository', async () => {
+    const { maintenance, spans, packRefs } = createHarness()
+
+    // A walk that stopped early reports a floor, so a low count is not evidence of health.
+    maintenance.arm({
+      key: 'local::/saturated/.git',
+      resolveRefsDirectory: async () => saturatingRefsDirectory(),
+      packRefs
+    })
+    await elapseQuietPeriod(maintenance)
+
+    expect(packRefs).toHaveBeenCalledTimes(1)
+    expect(attributesOf(spans[0])['repo.maintenance_outcome']).toBe('packed')
+  })
+
+  it('records a repo whose packed-refs lock is held, and retries sooner than a failure', async () => {
+    const refs = await refsDirectoryWith(THRESHOLD + 2)
+    const { maintenance, spans } = createHarness()
+
+    maintenance.arm(
+      target('local::/locked/.git', refs, async () => {
+        throw new RefMaintenanceRepoLocked('our own lock, not yet old enough to reclaim')
+      })
+    )
+    await elapseQuietPeriod(maintenance)
+
+    expect(attributesOf(spans[0])['repo.maintenance_outcome']).toBe('locked')
+  })
+
+  it('skips a repository whose common dir cannot be resolved', async () => {
+    const { maintenance, spans, packRefs } = createHarness()
+
+    maintenance.arm({
+      key: 'local::/gone/.git',
+      resolveRefsDirectory: async () => undefined,
+      packRefs
+    })
+    await elapseQuietPeriod(maintenance)
+
+    expect(packRefs).not.toHaveBeenCalled()
+    expect(attributesOf(spans[0])['repo.maintenance_outcome']).toBe('unresolved')
+  })
+})
+
+describe('RepoRefMaintenance single-flight and backoff', () => {
+  it('runs one repository at a time', async () => {
+    const refs = await refsDirectoryWith(THRESHOLD + 2)
+    let concurrent = 0
+    let peak = 0
+    const releases: (() => void)[] = []
+    const { maintenance } = createHarness()
+    const slowPack = async (): Promise<void> => {
+      concurrent += 1
+      peak = Math.max(peak, concurrent)
+      await new Promise<void>((resolve) => releases.push(resolve))
+      concurrent -= 1
+    }
+
+    maintenance.arm(target('local::/a/.git', refs, slowPack))
+    maintenance.arm(target('local::/b/.git', refs, slowPack))
+    await vi.advanceTimersByTimeAsync(QUIET_MS)
+    await until(() => concurrent === 1, 'a pack to start')
+    expect(concurrent).toBe(1)
+
+    releases.shift()?.()
+    await maintenance.whenAttemptSettled()
+    // The second repo was deferred behind the first, so its retry is on a timer.
+    await untilWithTimers(() => concurrent === 1, 'the second repo to start')
+    releases.shift()?.()
+    await maintenance.whenAttemptSettled()
+
+    expect(peak).toBe(1)
+    expect(concurrent).toBe(0)
+  })
+
+  it('waits out the rewrite window instead of killing the pack', async () => {
+    const refs = await refsDirectoryWith(THRESHOLD + 2)
+    let finished = false
+    let release: (() => void) | undefined
+    const { maintenance } = createHarness()
+    const started = packStartSignal()
+
+    maintenance.arm(
+      target('local::/yield/.git', refs, async (lock) => {
+        lock.setHeld(true)
+        started.onStart(lock)
+        await new Promise<void>((resolve) => {
+          release = () => {
+            lock.setHeld(false)
+            resolve()
+          }
+        })
+        finished = true
+      })
+    )
+    await vi.advanceTimersByTimeAsync(QUIET_MS)
+    await started.started
+
+    let paused = false
+    void maintenance.pause('worktree-remove').then(() => {
+      paused = true
+    })
+    await vi.advanceTimersByTimeAsync(1)
+    // Blocked while the rewrite window is open...
+    expect(paused).toBe(false)
+    expect(finished).toBe(false)
+
+    release?.()
+    await until(() => paused, 'pause() to resolve')
+    // ...and released without the pack ever being cancelled.
+    expect(paused).toBe(true)
+    expect(finished).toBe(true)
+  })
+
+  it('gives up waiting on the lock rather than blocking the user indefinitely', async () => {
+    const refs = await refsDirectoryWith(THRESHOLD + 2)
+    const { maintenance } = createHarness()
+    const started = packStartSignal()
+
+    maintenance.arm(
+      target('local::/stuck-lock/.git', refs, async (lock) => {
+        lock.setHeld(true)
+        started.onStart(lock)
+        await new Promise<void>(() => {})
+      })
+    )
+    await vi.advanceTimersByTimeAsync(QUIET_MS)
+    await started.started
+
+    let paused = false
+    void maintenance.pause('git-fetch').then(() => {
+      paused = true
+    })
+    await vi.advanceTimersByTimeAsync(PACKED_REFS_LOCK_WAIT_MS)
+    await until(() => paused, 'pause() to resolve')
+
+    expect(paused).toBe(true)
+  })
+
+  it('reopens the window only when the last overlapping caller releases', async () => {
+    const refs = await refsDirectoryWith(THRESHOLD + 2)
+    const { maintenance, packRefs } = createHarness()
+
+    const outer = await maintenance.pause('worktree-add')
+    const inner = await maintenance.pause('git-fetch')
+    maintenance.arm(target('local::/nested/.git', refs, packRefs))
+
+    await elapseQuietPeriod(maintenance, 8)
+    expect(packRefs).not.toHaveBeenCalled()
+
+    inner()
+    await elapseQuietPeriod(maintenance, 8)
+    expect(packRefs).not.toHaveBeenCalled()
+
+    outer()
+    await elapseQuietPeriod(maintenance, 8)
+    expect(packRefs).toHaveBeenCalledTimes(1)
+  })
+
+  it('restarts every armed countdown when the user does ref work themselves', async () => {
+    const refs = await refsDirectoryWith(THRESHOLD + 2)
+    const { maintenance, packRefs } = createHarness()
+
+    const firstPack = packStartSignal()
+    const observed = target('local::/a/.git', refs, async (lock) => {
+      firstPack.onStart(lock)
+      await packRefs(lock)
+    })
+    maintenance.arm(observed)
+    maintenance.arm(target('local::/b/.git', refs, packRefs))
+    await vi.advanceTimersByTimeAsync(QUIET_MS - 1)
+
+    // A manual fetch says the user is at the keyboard, so nothing may fire yet.
+    maintenance.postponeAll()
+    await vi.advanceTimersByTimeAsync(QUIET_MS - 1)
+    expect(packRefs).not.toHaveBeenCalled()
+
+    await vi.advanceTimersByTimeAsync(QUIET_MS)
+    await firstPack.started
+    expect(packRefs).toHaveBeenCalled()
+  })
+
+  it('costs nothing when no pack is running', async () => {
+    const { maintenance } = createHarness()
+
+    const release = await maintenance.pause('git-fetch')
+    release()
+    // Releasing twice must not leave the window wedged shut.
+    release()
+    const refs = await refsDirectoryWith(THRESHOLD + 2)
+    const { packRefs } = createHarness()
+    maintenance.arm(target('local::/free/.git', refs, packRefs))
+    await elapseQuietPeriod(maintenance)
+
+    expect(packRefs).toHaveBeenCalledTimes(1)
+  })
+
+  it('does not re-pack a repository inside its cooldown', async () => {
+    const refs = await refsDirectoryWith(THRESHOLD + 2)
+    let clock = 0
+    const { maintenance, packRefs } = createHarness({ now: () => clock })
+    const repo = target('local::/cooldown/.git', refs, packRefs)
+
+    maintenance.arm(repo)
+    await elapseQuietPeriod(maintenance)
+    expect(packRefs).toHaveBeenCalledTimes(1)
+
+    clock = REF_MAINTENANCE_PACKED_COOLDOWN_MS - 1
+    maintenance.arm(repo)
+    await elapseQuietPeriod(maintenance)
+    expect(packRefs).toHaveBeenCalledTimes(1)
+
+    clock = REF_MAINTENANCE_PACKED_COOLDOWN_MS + 1
+    maintenance.arm(repo)
+    await elapseQuietPeriod(maintenance)
+    expect(packRefs).toHaveBeenCalledTimes(2)
+  })
+
+  it('counts a pack that could not lock every ref as a success', async () => {
+    // Field-observed on a machine running several Orca sessions: a branch moved
+    // mid-pack, Git reported an error, and 36,688 loose refs still became 3.
+    // Retrying that aggressively would be wrong -- the backlog is gone.
+    const refs = await refsDirectoryWith(THRESHOLD + 2)
+    const { maintenance, spans } = createHarness()
+    const repo = target('local::/raced/.git', refs, async () => {
+      await emptyRefsDirectory(refs)
+      throw new Error("error: cannot lock ref 'refs/heads/moved'")
+    })
+
+    maintenance.arm(repo)
+    await elapseQuietPeriod(maintenance)
+
+    expect(attributesOf(spans[0])).toMatchObject({
+      'repo.maintenance_outcome': 'packed',
+      'git.pack_refs_partial': true,
+      'git.loose_ref_count_after': 0
+    })
+
+    // And it serves the full post-pack cooldown rather than retrying.
+    maintenance.arm(repo)
+    await elapseQuietPeriod(maintenance)
+    expect(spans).toHaveLength(1)
+  })
+
+  it('records a failure when the pack left the backlog in place', async () => {
+    const refs = await refsDirectoryWith(THRESHOLD + 2)
+    const { maintenance, spans } = createHarness({
+      packRefs: async () => {
+        throw new Error('permission denied')
+      }
+    })
+
+    maintenance.arm(target('local::/denied/.git', refs, () => Promise.reject(new Error('denied'))))
+    await elapseQuietPeriod(maintenance)
+
+    expect(attributesOf(spans[0])['repo.maintenance_outcome']).toBe('failed')
+  })
+
+  it('records a failure instead of throwing, and backs off', async () => {
+    const refs = await refsDirectoryWith(THRESHOLD + 2)
+    const { maintenance, spans, packRefs } = createHarness({
+      packRefs: async () => {
+        throw new Error('packed-refs.lock exists')
+      }
+    })
+    const repo = target('local::/failing/.git', refs, packRefs)
+
+    maintenance.arm(repo)
+    await elapseQuietPeriod(maintenance)
+    expect(attributesOf(spans[0])['repo.maintenance_outcome']).toBe('failed')
+
+    maintenance.arm(repo)
+    await elapseQuietPeriod(maintenance)
+    expect(packRefs).toHaveBeenCalledTimes(1)
+  })
+
+  it('stops scheduling once disposed', async () => {
+    const refs = await refsDirectoryWith(THRESHOLD + 2)
+    const { maintenance, packRefs } = createHarness()
+
+    maintenance.arm(target('local::/disposed/.git', refs, packRefs))
+    maintenance.dispose()
+    await elapseQuietPeriod(maintenance)
+
+    expect(packRefs).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/shared/repo-ref-maintenance.ts b/src/shared/repo-ref-maintenance.ts
new file mode 100644
index 00000000000..97e228fab52
--- /dev/null
+++ b/src/shared/repo-ref-maintenance.ts
@@ -0,0 +1,366 @@
+import { countLooseRefs } from './loose-ref-count'
+import { PackedRefsLockGate } from './packed-refs-lock-gate'
+import {
+  LOOSE_REF_PACK_THRESHOLD,
+  REF_MAINTENANCE_ATTEMPT_DEADLINE_MS,
+  REF_MAINTENANCE_CLEAN_COOLDOWN_MS,
+  REF_MAINTENANCE_FAILURE_COOLDOWN_MS,
+  REF_MAINTENANCE_PACKED_COOLDOWN_MS,
+  REF_MAINTENANCE_QUIET_PERIOD_MS,
+  PACKED_REFS_LOCK_WAIT_MS,
+  REF_MAINTENANCE_LOCKED_COOLDOWN_MS,
+  RefMaintenanceInterrupted,
+  RefMaintenanceRepoLocked,
+  type RefMaintenanceOutcome,
+  type RefMaintenanceSpan,
+  type RepoRefMaintenanceOptions,
+  type RepoRefMaintenanceTarget
+} from './repo-ref-maintenance-policy'
+
+/**
+ * The scheduler half of idle loose-ref packing: when to probe, when to pack,
+ * when to stand down. The thresholds and the host contract it works against
+ * live in `./repo-ref-maintenance-policy`.
+ */
+
+/** Give up until the next real activity rather than re-arming forever. */
+const MAX_DEFERRALS = 6
+/** Each deferral doubles the wait, so a busy app is retried rarely, not hammered. */
+const MAX_DEFERRAL_BACKOFF_MULTIPLIER = 8
+/** Armed repos are evicted oldest-first past this; the next write on one re-arms it. */
+const MAX_TRACKED_REPOS = 64
+
+type TrackedRepo = {
+  target: RepoRefMaintenanceTarget
+  timer: ReturnType<typeof setTimeout> | null
+  deferrals: number
+}
+
+const noopSpan: RefMaintenanceSpan = { setAttribute: () => {} }
+
+/** A deadline means something is stuck: back off instead of retrying straight away. */
+function hitDeadline(signal: AbortSignal): boolean {
+  return signal.reason instanceof RefMaintenanceInterrupted && signal.reason.deadline
+}
+
+export class RepoRefMaintenance {
+  private readonly tracked = new Map<string, TrackedRepo>()
+  private readonly cooldownUntil = new Map<string, number>()
+  private readonly now: () => number
+  private readonly isAppBusy: () => boolean
+  private readonly observe: NonNullable<RepoRefMaintenanceOptions['observe']>
+  private readonly quietPeriodMs: number
+  private readonly looseRefThreshold: number
+  private readonly onError: (error: unknown) => void
+  // Why: at most one pack-refs anywhere. It holds a general git admission slot
+  // for its whole run, and two at once would halve git throughput on a small host.
+  // The slot is never released while a pack that could hold `packed-refs.lock`
+  // is still running -- an interrupt cancels the work and waits for it to stop.
+  private inFlight: Promise<void> | null = null
+  private inFlightAbort: AbortController | null = null
+  private readonly lockGate = new PackedRefsLockGate()
+  // Why a count, not a flag: several ref-touching operations overlap routinely
+  // (a create's fetch inside a create), and the last one out reopens the window.
+  private suspensions = 0
+  private lastAttempt: Promise<void> = Promise.resolve()
+  private disposed = false
+
+  constructor(options: RepoRefMaintenanceOptions = {}) {
+    this.now = options.now ?? Date.now
+    this.isAppBusy = options.isBusy ?? (() => false)
+    this.observe = options.observe ?? ((attempt) => attempt(noopSpan))
+    this.quietPeriodMs = options.quietPeriodMs ?? REF_MAINTENANCE_QUIET_PERIOD_MS
+    this.looseRefThreshold = options.looseRefThreshold ?? LOOSE_REF_PACK_THRESHOLD
+    this.onError = options.onError ?? (() => {})
+  }
+
+  /**
+   * Record a write to `target`'s repo and (re)start its quiet-period countdown.
+   * Every call pushes the attempt further out, so a burst of fetches or a
+   * worktree create can never be interrupted by maintenance it triggered.
+   */
+  arm(target: RepoRefMaintenanceTarget): void {
+    if (this.disposed) {
+      return
+    }
+    const existing = this.tracked.get(target.key)
+    if (existing?.timer) {
+      clearTimeout(existing.timer)
+    }
+    const tracked: TrackedRepo = { target, timer: null, deferrals: existing?.deferrals ?? 0 }
+    this.tracked.delete(target.key)
+    this.evictOldestBeyondCap()
+    this.tracked.set(target.key, tracked)
+    this.schedule(target.key, tracked)
+  }
+
+  /** Resolves once the attempt started by the most recent timer has settled. */
+  whenAttemptSettled(): Promise<void> {
+    return this.lastAttempt
+  }
+
+  /**
+   * Wait out the `packed-refs` rewrite, if one is in progress.
+   *
+   * Deliberately not a kill. The lock is held for 0.03-1.37s of a 23-32s pack;
+   * the rest is the prune phase, during which a concurrent `fetch --prune`,
+   * `branch -D` or `update-ref` measurably succeeds because per-ref locks last
+   * microseconds and Git retries for `core.filesRefLockTimeout`. Signalling the
+   * child there buys nothing and strands a lock file about one time in five.
+   *
+   * Free when no pack is running, which is almost always.
+   */
+  awaitPackedRefsLockRelease(): Promise<void> {
+    return this.lockGate.whenReleased(PACKED_REFS_LOCK_WAIT_MS)
+  }
+
+  /**
+   * Push every armed repository's attempt out by a full quiet period.
+   *
+   * User-initiated ref work is evidence the user is active in the app, not just
+   * in one repo, and it is free -- no key to resolve, no subprocess, nothing at
+   * all when nothing is armed.
+   */
+  postponeAll(): void {
+    if (this.disposed) {
+      return
+    }
+    for (const [key, tracked] of this.tracked) {
+      if (tracked.timer) {
+        clearTimeout(tracked.timer)
+      }
+      tracked.deferrals = 0
+      this.schedule(key, tracked)
+    }
+  }
+
+  /**
+   * Hold the repository open for work that is about to touch refs.
+   *
+   * Two things at once: no *new* attempt can start for any repository until the
+   * returned release is called, and the caller waits out any `packed-refs`
+   * rewrite already in progress. A prune already running is left alone to
+   * finish -- it does not block the caller.
+   */
+  async pause(_reason: string): Promise<() => void> {
+    this.suspensions += 1
+    let released = false
+    try {
+      await this.awaitPackedRefsLockRelease()
+    } catch {
+      // The wait cannot reject, but a release must exist even if it did.
+    }
+    return () => {
+      if (!released) {
+        released = true
+        this.suspensions -= 1
+      }
+    }
+  }
+
+  dispose(): void {
+    this.disposed = true
+    this.inFlightAbort?.abort(new RefMaintenanceInterrupted('disposed'))
+    for (const tracked of this.tracked.values()) {
+      if (tracked.timer) {
+        clearTimeout(tracked.timer)
+      }
+    }
+    this.tracked.clear()
+    this.cooldownUntil.clear()
+  }
+
+  private isBusy(tracked: TrackedRepo): boolean {
+    return this.isAppBusy() || (tracked.target.isBusy?.() ?? false)
+  }
+
+  private schedule(key: string, tracked: TrackedRepo, delayMs = this.quietPeriodMs): void {
+    const timer = setTimeout(() => {
+      tracked.timer = null
+      this.lastAttempt = this.attempt(key).catch((error) => this.onError(error))
+    }, delayMs)
+    // Never hold the process open for maintenance.
+    timer.unref?.()
+    tracked.timer = timer
+  }
+
+  private evictOldestBeyondCap(): void {
+    while (this.tracked.size >= MAX_TRACKED_REPOS) {
+      const oldest = this.tracked.keys().next()
+      if (oldest.done) {
+        return
+      }
+      const evicted = this.tracked.get(oldest.value)
+      if (evicted?.timer) {
+        clearTimeout(evicted.timer)
+      }
+      this.tracked.delete(oldest.value)
+    }
+  }
+
+  /**
+   * `counted` spends the give-up budget. Waiting behind another repository's
+   * pack, or yielding to work Orca asked us to yield to, does not: both end on
+   * their own, so charging for them would let a busy machine starve a repo
+   * until its next fetch. Only "the app is busy" is charged.
+   */
+  private defer(key: string, tracked: TrackedRepo, counted: boolean): void {
+    // A fetch that landed while this attempt was probing already re-armed the
+    // repo; that entry is fresher, so the deferral must not overwrite it.
+    if (this.disposed || this.tracked.has(key)) {
+      return
+    }
+    if (counted) {
+      if (tracked.deferrals >= MAX_DEFERRALS) {
+        return
+      }
+      tracked.deferrals += 1
+    }
+    this.tracked.set(key, tracked)
+    const multiplier = Math.min(2 ** tracked.deferrals, MAX_DEFERRAL_BACKOFF_MULTIPLIER)
+    this.schedule(key, tracked, this.quietPeriodMs * multiplier)
+  }
+
+  private async attempt(key: string): Promise<void> {
+    const tracked = this.tracked.get(key)
+    if (!tracked || this.disposed) {
+      return
+    }
+    this.tracked.delete(key)
+    const cooldownUntil = this.cooldownUntil.get(key)
+    if (cooldownUntil !== undefined && this.now() < cooldownUntil) {
+      return
+    }
+    if (this.inFlight !== null) {
+      this.defer(key, tracked, false)
+      return
+    }
+    if (this.suspensions > 0 || this.isBusy(tracked)) {
+      this.defer(key, tracked, true)
+      return
+    }
+    const abort = new AbortController()
+    const deadline = setTimeout(
+      () => abort.abort(new RefMaintenanceInterrupted('attempt deadline', true)),
+      REF_MAINTENANCE_ATTEMPT_DEADLINE_MS
+    )
+    deadline.unref?.()
+    const run = this.observe((span) => this.packIfNeeded(key, tracked, span, abort.signal))
+    this.inFlight = run
+    this.inFlightAbort = abort
+    try {
+      await run
+    } finally {
+      clearTimeout(deadline)
+      if (this.inFlight === run) {
+        this.inFlight = null
+        this.inFlightAbort = null
+      }
+    }
+  }
+
+  private async packIfNeeded(
+    key: string,
+    tracked: TrackedRepo,
+    span: RefMaintenanceSpan,
+    signal: AbortSignal
+  ): Promise<void> {
+    span.setAttribute('repo.maintenance_key', key)
+    // Every await below carries the signal, so a caller waiting in `pause()` is
+    // never stuck behind a probe that has already been told to stop.
+    if (await tracked.target.isOptedOut?.(signal)) {
+      this.settle(key, span, 'opted_out', REF_MAINTENANCE_CLEAN_COOLDOWN_MS)
+      return
+    }
+    if (signal.aborted) {
+      this.yieldTo(key, tracked, span, signal)
+      return
+    }
+    const refsDirectory = await tracked.target.resolveRefsDirectory(signal)
+    if (!refsDirectory) {
+      this.settle(key, span, 'unresolved', REF_MAINTENANCE_CLEAN_COOLDOWN_MS)
+      return
+    }
+    const budget = this.looseRefThreshold + 1
+    const before = await countLooseRefs(refsDirectory, budget, signal)
+    if (signal.aborted) {
+      this.yieldTo(key, tracked, span, signal)
+      return
+    }
+    span.setAttribute('git.loose_ref_count', before.count)
+    span.setAttribute('git.loose_ref_threshold', this.looseRefThreshold)
+    // A saturated walk stopped early, so `count` is a floor -- never read it as "clean".
+    if (!before.saturated && before.count < this.looseRefThreshold) {
+      this.settle(key, span, 'below_threshold', REF_MAINTENANCE_CLEAN_COOLDOWN_MS)
+      return
+    }
+    // The quiet window can close while the probe walks; re-check before spending a git slot.
+    if (this.suspensions > 0 || this.isBusy(tracked)) {
+      span.setAttribute('repo.maintenance_outcome', 'deferred' satisfies RefMaintenanceOutcome)
+      this.defer(key, tracked, true)
+      return
+    }
+    const startedAt = this.now()
+    let partial = false
+    try {
+      // No signal: the pack runs to completion. Callers that need the refs wait
+      // out the rewrite window through `pause()` instead of killing it.
+      await tracked.target.packRefs(this.lockGate)
+    } catch (error) {
+      span.setAttribute('repo.maintenance_error', String(error))
+      if (error instanceof RefMaintenanceRepoLocked) {
+        this.settle(key, span, 'locked', REF_MAINTENANCE_LOCKED_COOLDOWN_MS)
+        return
+      }
+      partial = true
+    } finally {
+      this.lockGate.setHeld(false)
+    }
+    span.setAttribute('git.pack_refs_ms', this.now() - startedAt)
+    // Judge by the backlog, not by the exit code. On a machine running several
+    // Orca sessions a branch moving mid-pack is the normal case, and Git's
+    // response -- leave that one ref loose, pack the rest -- is the correct one.
+    // Measured in the field: 36,688 loose refs down to 3, reported as an error.
+    const after = await countLooseRefs(refsDirectory, budget, signal)
+    span.setAttribute('git.loose_ref_count_after', after.count)
+    if (partial && (after.saturated || after.count >= this.looseRefThreshold)) {
+      this.settle(key, span, 'failed', REF_MAINTENANCE_FAILURE_COOLDOWN_MS)
+      return
+    }
+    span.setAttribute('git.pack_refs_partial', partial)
+    this.settle(key, span, 'packed', REF_MAINTENANCE_PACKED_COOLDOWN_MS)
+  }
+
+  /** Record an aborted attempt: retry soon if Orca yielded, back off if it stalled. */
+  private yieldTo(
+    key: string,
+    tracked: TrackedRepo,
+    span: RefMaintenanceSpan,
+    signal: AbortSignal
+  ): void {
+    if (hitDeadline(signal)) {
+      this.settle(key, span, 'timed_out', REF_MAINTENANCE_FAILURE_COOLDOWN_MS)
+      return
+    }
+    span.setAttribute('repo.maintenance_outcome', 'interrupted' satisfies RefMaintenanceOutcome)
+    this.defer(key, tracked, false)
+  }
+
+  private settle(
+    key: string,
+    span: RefMaintenanceSpan,
+    outcome: RefMaintenanceOutcome,
+    cooldownMs: number
+  ): void {
+    span.setAttribute('repo.maintenance_outcome', outcome)
+    // Re-insert so Map order stays newest-last and the eviction below drops the oldest.
+    this.cooldownUntil.delete(key)
+    this.cooldownUntil.set(key, this.now() + cooldownMs)
+    if (this.cooldownUntil.size > MAX_TRACKED_REPOS * 4) {
+      const oldest = this.cooldownUntil.keys().next()
+      if (!oldest.done) {
+        this.cooldownUntil.delete(oldest.value)
+      }
+    }
+  }
+}

From 0352c239c249a355a26c132b9aeb071b55bc66fb Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Tue, 1 Sep 2026 19:20:48 -0700
Subject: [PATCH 25/32] Add Copy Session ID menu item to terminal tabs (#18039)

* Add Copy Session ID menu item to terminal tabs

Adds a menu item to copy the active pane's agent session ID when available.
The item only appears when the session is still live and has reported an ID.

* Add Copy Session ID i18n strings and e2e test

- Add localized strings for Session ID context menu item
- Add e2e test coverage for copying session ID from terminal tabs
- Fix dev build permissions when copying private Electron app bundles

* Drop the Electron dev-bundle fix from this branch

It landed on main as 519af49a58, which restores write permission inside
copyPrivateTree itself rather than at the dev runner's call site, so every
caller of the private-copy contract is covered and not just this one. That
commit also fixes the test that should have caught the crash: the wrapper ran
with stdio: 'ignore', so a hard failure presented as a bare timeout.

This branch predated that commit and carried a narrower duplicate, mixed into
an i18n/e2e commit where it did not belong.

* refactor: use dedicated i18n keys for copy session ID toasts

Replace auto-generated translation keys with specific, dedicated keys
for copy session ID success and error messages. This improves
maintainability and makes the strings easier to translate across all
supported languages.
---
 .../tab-bar/SortableTabContextMenu.test.tsx   |  59 +++++++
 .../tab-bar/SortableTabContextMenu.tsx        |   7 +
 .../TabAgentSessionIdMenuItem.test.tsx        |  79 +++++++++
 .../tab-bar/TabAgentSessionIdMenuItem.tsx     |  48 ++++++
 .../tab-bar/tab-agent-session-id.test.ts      | 159 ++++++++++++++++++
 .../tab-bar/tab-agent-session-id.ts           |  32 ++++
 .../tab-context-menu-consistency.test.tsx     |   1 +
 src/renderer/src/i18n/locales/en.json         |   5 +-
 src/renderer/src/i18n/locales/es.json         |   5 +-
 src/renderer/src/i18n/locales/ja.json         |   5 +-
 src/renderer/src/i18n/locales/ko.json         |   5 +-
 src/renderer/src/i18n/locales/zh.json         |   5 +-
 tests/e2e/tab-context-menu-session-id.spec.ts |  76 +++++++++
 13 files changed, 481 insertions(+), 5 deletions(-)
 create mode 100644 src/renderer/src/components/tab-bar/TabAgentSessionIdMenuItem.test.tsx
 create mode 100644 src/renderer/src/components/tab-bar/TabAgentSessionIdMenuItem.tsx
 create mode 100644 src/renderer/src/components/tab-bar/tab-agent-session-id.test.ts
 create mode 100644 src/renderer/src/components/tab-bar/tab-agent-session-id.ts
 create mode 100644 tests/e2e/tab-context-menu-session-id.spec.ts

diff --git a/src/renderer/src/components/tab-bar/SortableTabContextMenu.test.tsx b/src/renderer/src/components/tab-bar/SortableTabContextMenu.test.tsx
index 76d5d8d145a..e51c599f669 100644
--- a/src/renderer/src/components/tab-bar/SortableTabContextMenu.test.tsx
+++ b/src/renderer/src/components/tab-bar/SortableTabContextMenu.test.tsx
@@ -55,6 +55,7 @@ vi.mock('lucide-react', () => ({
   ArrowRight: () => null,
   ArrowUp: () => null,
   Columns2: () => null,
+  Copy: () => null,
   ListX: () => null,
   MessageSquare: () => null,
   PanelBottomClose: () => null,
@@ -71,6 +72,8 @@ vi.mock('@/i18n/i18n', () => ({
   translate: (_key: string, fallback: string) => fallback
 }))
 
+vi.mock('sonner', () => ({ toast: { success: vi.fn(), error: vi.fn() } }))
+
 vi.mock('../../store', () => ({
   useAppStore: Object.assign(
     (selector: (state: Record<string, unknown>) => unknown) => selector(storeMock.state),
@@ -289,4 +292,60 @@ describe('SortableTabContextMenu', () => {
     expect(container.textContent).not.toContain('Move Tab to Split')
     expect(container.textContent).toContain('Split terminal right')
   })
+
+  describe('copy session id', () => {
+    const LEAF = '11111111-1111-4111-8111-111111111111'
+
+    function withLiveAgent(sessionId: string | null): void {
+      storeMock.state = {
+        ...storeMock.state,
+        terminalLayoutsByTabId: {
+          'term-1': { root: { type: 'leaf', leafId: LEAF }, activeLeafId: LEAF }
+        },
+        agentStatusByPaneKey: {
+          [`term-1:${LEAF}`]: {
+            state: 'done',
+            prompt: '',
+            updatedAt: 1,
+            stateStartedAt: 1,
+            paneKey: `term-1:${LEAF}`,
+            agentType: 'claude',
+            stateHistory: [],
+            ...(sessionId ? { providerSession: { key: 'session_id', id: sessionId } } : {})
+          }
+        },
+        paneForegroundAgentByPaneKey: {}
+      }
+    }
+
+    it('omits the item for a tab with no agent', () => {
+      const { container } = renderMenu()
+
+      expect(container.textContent).not.toContain('Copy Session ID')
+    })
+
+    it('omits the item until the active agent reports a session id', () => {
+      withLiveAgent(null)
+      const { container } = renderMenu()
+
+      expect(container.textContent).not.toContain('Copy Session ID')
+    })
+
+    it('copies the active pane session id', async () => {
+      const writeClipboardText = vi.fn().mockResolvedValue(undefined)
+      Object.assign(window, { api: { ui: { writeClipboardText } } })
+      withLiveAgent('session-abc')
+      const { container } = renderMenu()
+
+      act(() => getButton(container, 'Copy Session ID').click())
+      await vi.waitFor(() => expect(writeClipboardText).toHaveBeenCalledWith('session-abc'))
+    })
+
+    it('does not resolve a session id while the menu is closed', () => {
+      withLiveAgent('session-abc')
+      const { container } = renderMenu({ open: false })
+
+      expect(container.textContent).not.toContain('Copy Session ID')
+    })
+  })
 })
diff --git a/src/renderer/src/components/tab-bar/SortableTabContextMenu.tsx b/src/renderer/src/components/tab-bar/SortableTabContextMenu.tsx
index 53b31012d39..b298072f9f6 100644
--- a/src/renderer/src/components/tab-bar/SortableTabContextMenu.tsx
+++ b/src/renderer/src/components/tab-bar/SortableTabContextMenu.tsx
@@ -11,6 +11,8 @@ import type { TerminalTab } from '../../../../shared/terminal-tab-types'
 import { useAppStore } from '../../store'
 import { formatShortcutLabel, useOptionalShortcutLabel } from '@/hooks/useShortcutLabel'
 import { translate } from '@/i18n/i18n'
+import { TabAgentSessionIdMenuItem } from './TabAgentSessionIdMenuItem'
+import { resolveTabAgentSessionId } from './tab-agent-session-id'
 import { TerminalTabSplitMenuSection } from './TerminalTabSplitMenuSection'
 import { TAB_CONTEXT_MENU_CONTENT_CLASS } from './tab-context-menu-sizing'
 
@@ -121,6 +123,10 @@ export function SortableTabContextMenu({
   onTogglePin
 }: SortableTabContextMenuProps): React.JSX.Element {
   const keybindings = useAppStore((state) => state.keybindings)
+  // The id is a primitive, so unchanged sessions stay referentially stable without a cache.
+  const agentSessionId = useAppStore((state) =>
+    open ? resolveTabAgentSessionId(state, tab.id) : null
+  )
   const splitRightShortcut = formatShortcutLabel('terminal.splitRight', keybindings)
   const splitDownShortcut = formatShortcutLabel('terminal.splitDown', keybindings)
 
@@ -188,6 +194,7 @@ export function SortableTabContextMenu({
           {translate('auto.components.tab.bar.SortableTabContextMenu.2f697b3c31', 'Change Title')}
           {renameShortcut ? <DropdownMenuShortcut>{renameShortcut}</DropdownMenuShortcut> : null}
         </DropdownMenuItem>
+        <TabAgentSessionIdMenuItem sessionId={agentSessionId} />
         <div className="px-2 pt-1.5 pb-1">
           <div className="text-xs font-medium text-muted-foreground mb-1.5">
             {translate('auto.components.tab.bar.SortableTabContextMenu.35e8892fd0', 'Tab Color')}
diff --git a/src/renderer/src/components/tab-bar/TabAgentSessionIdMenuItem.test.tsx b/src/renderer/src/components/tab-bar/TabAgentSessionIdMenuItem.test.tsx
new file mode 100644
index 00000000000..da857ec57bf
--- /dev/null
+++ b/src/renderer/src/components/tab-bar/TabAgentSessionIdMenuItem.test.tsx
@@ -0,0 +1,79 @@
+/**
+ * @vitest-environment happy-dom
+ */
+import { act, type ReactNode } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { TabAgentSessionIdMenuItem } from './TabAgentSessionIdMenuItem'
+
+const toastMock = vi.hoisted(() => ({ success: vi.fn(), error: vi.fn() }))
+
+vi.mock('@/components/ui/dropdown-menu', () => ({
+  DropdownMenuItem: ({
+    children,
+    disabled,
+    onSelect,
+    'aria-label': ariaLabel
+  }: {
+    children?: ReactNode
+    disabled?: boolean
+    onSelect?: () => void
+    'aria-label'?: string
+  }) => (
+    <button type="button" disabled={disabled} aria-label={ariaLabel} onClick={() => onSelect?.()}>
+      {children}
+    </button>
+  )
+}))
+
+vi.mock('lucide-react', () => ({ Copy: () => null }))
+vi.mock('@/i18n/i18n', () => ({ translate: (_key: string, fallback: string) => fallback }))
+vi.mock('sonner', () => ({ toast: toastMock }))
+
+const mounted: { container: HTMLDivElement; root: Root }[] = []
+
+function render(sessionId: string | null): HTMLDivElement {
+  const container = document.createElement('div')
+  document.body.appendChild(container)
+  const root = createRoot(container)
+  act(() => root.render(<TabAgentSessionIdMenuItem sessionId={sessionId} />))
+  mounted.push({ container, root })
+  return container
+}
+
+afterEach(() => {
+  for (const { container, root } of mounted.splice(0)) {
+    act(() => root.unmount())
+    container.remove()
+  }
+  toastMock.success.mockReset()
+  toastMock.error.mockReset()
+})
+
+describe('TabAgentSessionIdMenuItem', () => {
+  it('renders nothing when no session id is available', () => {
+    expect(render(null).textContent).toBe('')
+  })
+
+  it('copies on select when an id is known', async () => {
+    const writeClipboardText = vi.fn().mockResolvedValue(undefined)
+    Object.assign(window, { api: { ui: { writeClipboardText } } })
+    const container = render('abc-123')
+
+    const button = container.querySelector('button')
+    expect(button?.disabled).toBe(false)
+    act(() => button?.click())
+    await vi.waitFor(() => expect(writeClipboardText).toHaveBeenCalledWith('abc-123'))
+  })
+
+  it('reports clipboard failures', async () => {
+    const writeClipboardText = vi.fn().mockRejectedValue(new Error('clipboard unavailable'))
+    Object.assign(window, { api: { ui: { writeClipboardText } } })
+    const button = render('abc-123').querySelector('button')
+
+    act(() => button?.click())
+    await vi.waitFor(() =>
+      expect(toastMock.error).toHaveBeenCalledWith('Failed to copy Session ID')
+    )
+  })
+})
diff --git a/src/renderer/src/components/tab-bar/TabAgentSessionIdMenuItem.tsx b/src/renderer/src/components/tab-bar/TabAgentSessionIdMenuItem.tsx
new file mode 100644
index 00000000000..73f3f128e5d
--- /dev/null
+++ b/src/renderer/src/components/tab-bar/TabAgentSessionIdMenuItem.tsx
@@ -0,0 +1,48 @@
+import { Copy } from 'lucide-react'
+import { toast } from 'sonner'
+import { DropdownMenuItem } from '@/components/ui/dropdown-menu'
+import { translate } from '@/i18n/i18n'
+
+async function copySessionId(sessionId: string): Promise<void> {
+  try {
+    await window.api.ui.writeClipboardText(sessionId)
+    toast.success(
+      translate(
+        'components.tab.bar.SortableTabContextMenu.copySessionIdSuccess',
+        'Session ID copied'
+      )
+    )
+  } catch {
+    toast.error(
+      translate(
+        'components.tab.bar.SortableTabContextMenu.copySessionIdError',
+        'Failed to copy Session ID'
+      )
+    )
+  }
+}
+
+/** Copies the active pane's provider session id when one is available. */
+export function TabAgentSessionIdMenuItem({
+  sessionId
+}: {
+  sessionId: string | null
+}): React.JSX.Element | null {
+  if (sessionId === null) {
+    return null
+  }
+  const label = translate(
+    'components.tab.bar.SortableTabContextMenu.copySessionId',
+    'Copy Session ID'
+  )
+  return (
+    <DropdownMenuItem
+      onSelect={() => {
+        void copySessionId(sessionId)
+      }}
+    >
+      <Copy className="size-3.5" />
+      {label}
+    </DropdownMenuItem>
+  )
+}
diff --git a/src/renderer/src/components/tab-bar/tab-agent-session-id.test.ts b/src/renderer/src/components/tab-bar/tab-agent-session-id.test.ts
new file mode 100644
index 00000000000..2f06f0a8db7
--- /dev/null
+++ b/src/renderer/src/components/tab-bar/tab-agent-session-id.test.ts
@@ -0,0 +1,159 @@
+import { describe, expect, it } from 'vitest'
+import type { AgentStatusEntry } from '../../../../shared/agent-status-types'
+import { resolveTabAgentSessionId, type TabAgentSessionIdState } from './tab-agent-session-id'
+
+const LEAF_A = '11111111-1111-4111-8111-111111111111'
+const LEAF_B = '22222222-2222-4222-8222-222222222222'
+
+function entry(overrides: Partial<AgentStatusEntry> = {}): AgentStatusEntry {
+  return {
+    state: 'done',
+    prompt: '',
+    updatedAt: 1,
+    stateStartedAt: 1,
+    paneKey: `tab-1:${LEAF_A}`,
+    agentType: 'claude',
+    stateHistory: [],
+    ...overrides
+  }
+}
+
+function state(overrides: Partial<TabAgentSessionIdState> = {}): TabAgentSessionIdState {
+  return {
+    terminalLayoutsByTabId: {
+      'tab-1': {
+        root: { type: 'leaf', leafId: LEAF_A },
+        activeLeafId: LEAF_A,
+        expandedLeafId: null
+      }
+    },
+    agentStatusByPaneKey: {},
+    paneForegroundAgentByPaneKey: {},
+    ...overrides
+  }
+}
+
+describe('resolveTabAgentSessionId', () => {
+  it('is absent when the pane has no agent row', () => {
+    expect(resolveTabAgentSessionId(state(), 'tab-1')).toBeNull()
+  })
+
+  it('is absent for a tab with no layout', () => {
+    expect(resolveTabAgentSessionId(state(), 'tab-missing')).toBeNull()
+  })
+
+  it('reads the id reported by the active pane', () => {
+    const resolved = resolveTabAgentSessionId(
+      state({
+        agentStatusByPaneKey: {
+          [`tab-1:${LEAF_A}`]: entry({ providerSession: { key: 'session_id', id: 'abc-123' } })
+        }
+      }),
+      'tab-1'
+    )
+    expect(resolved).toBe('abc-123')
+  })
+
+  it('is absent until the agent reports an id', () => {
+    const resolved = resolveTabAgentSessionId(
+      state({ agentStatusByPaneKey: { [`tab-1:${LEAF_A}`]: entry() } }),
+      'tab-1'
+    )
+    expect(resolved).toBeNull()
+  })
+
+  describe('liveness', () => {
+    it('is absent for a hydrated row with no live hook since restore', () => {
+      const resolved = resolveTabAgentSessionId(
+        state({
+          agentStatusByPaneKey: {
+            [`tab-1:${LEAF_A}`]: entry({
+              restoredUnconfirmed: true,
+              providerSession: { key: 'session_id', id: 'abc-123' }
+            })
+          }
+        }),
+        'tab-1'
+      )
+      expect(resolved).toBeNull()
+    })
+
+    it('is absent once the pane is proven back at the shell', () => {
+      const resolved = resolveTabAgentSessionId(
+        state({
+          agentStatusByPaneKey: {
+            [`tab-1:${LEAF_A}`]: entry({ providerSession: { key: 'session_id', id: 'abc-123' } })
+          },
+          paneForegroundAgentByPaneKey: {
+            [`tab-1:${LEAF_A}`]: { agent: null, shellForeground: true }
+          }
+        }),
+        'tab-1'
+      )
+      expect(resolved).toBeNull()
+    })
+
+    it('keeps a session whose foreground evidence is only that an agent runs', () => {
+      const resolved = resolveTabAgentSessionId(
+        state({
+          agentStatusByPaneKey: {
+            [`tab-1:${LEAF_A}`]: entry({ providerSession: { key: 'session_id', id: 'abc-123' } })
+          },
+          paneForegroundAgentByPaneKey: {
+            [`tab-1:${LEAF_A}`]: { agent: 'claude', shellForeground: false }
+          }
+        }),
+        'tab-1'
+      )
+      expect(resolved).toBe('abc-123')
+    })
+
+    it('keeps a working session that reported a session boundary', () => {
+      // Why: sessionBoundary marks a resume/clear landing idle — a session start,
+      // not a session end, and exactly when the first id arrives.
+      const resolved = resolveTabAgentSessionId(
+        state({
+          agentStatusByPaneKey: {
+            [`tab-1:${LEAF_A}`]: entry({
+              sessionBoundary: true,
+              providerSession: { key: 'session_id', id: 'fresh-1' }
+            })
+          }
+        }),
+        'tab-1'
+      )
+      expect(resolved).toBe('fresh-1')
+    })
+  })
+
+  describe('split tabs', () => {
+    const splitState = (activeLeafId: string): TabAgentSessionIdState =>
+      state({
+        terminalLayoutsByTabId: {
+          'tab-1': {
+            root: {
+              type: 'split',
+              direction: 'vertical',
+              first: { type: 'leaf', leafId: LEAF_A },
+              second: { type: 'leaf', leafId: LEAF_B }
+            },
+            activeLeafId,
+            expandedLeafId: null
+          }
+        },
+        agentStatusByPaneKey: {
+          [`tab-1:${LEAF_A}`]: entry({ providerSession: { key: 'session_id', id: 'left' } }),
+          [`tab-1:${LEAF_B}`]: entry({ providerSession: { key: 'session_id', id: 'right' } })
+        }
+      })
+
+    it('reads the active pane, not a sibling', () => {
+      expect(resolveTabAgentSessionId(splitState(LEAF_B), 'tab-1')).toBe('right')
+    })
+
+    it('is absent when the active leaf id no longer exists in the layout', () => {
+      const stale = '33333333-3333-4333-8333-333333333333'
+      expect(resolveTabAgentSessionId(splitState(stale), 'tab-1')).toBeNull()
+    })
+  })
+})
diff --git a/src/renderer/src/components/tab-bar/tab-agent-session-id.ts b/src/renderer/src/components/tab-bar/tab-agent-session-id.ts
new file mode 100644
index 00000000000..e0d804bc4c5
--- /dev/null
+++ b/src/renderer/src/components/tab-bar/tab-agent-session-id.ts
@@ -0,0 +1,32 @@
+import type { AgentStatusEntry } from '../../../../shared/agent-status-types'
+import type { TerminalLayoutSnapshot } from '../../../../shared/terminal-tab-types'
+import type { PaneForegroundAgentEntry } from '../../store/slices/pane-foreground-agent'
+import { resolveNativeChatActiveLayoutLeafId } from '../native-chat/native-chat-leaf-routing'
+
+export type TabAgentSessionIdState = {
+  agentStatusByPaneKey?: Record<string, AgentStatusEntry>
+  terminalLayoutsByTabId?: Record<string, TerminalLayoutSnapshot>
+  paneForegroundAgentByPaneKey?: Record<string, PaneForegroundAgentEntry>
+}
+
+/** Returns the active pane's provider session id when its agent is still live. */
+export function resolveTabAgentSessionId(
+  state: TabAgentSessionIdState,
+  tabId: string
+): string | null {
+  const leafId = resolveNativeChatActiveLayoutLeafId(state.terminalLayoutsByTabId?.[tabId])
+  if (!leafId) {
+    return null
+  }
+  const paneKey = `${tabId}:${leafId}`
+  const entry = state.agentStatusByPaneKey?.[paneKey]
+  // Hydrated rows may describe a session that ended while no receiver was up.
+  if (!entry?.agentType || entry.restoredUnconfirmed === true) {
+    return null
+  }
+  // OSC 133;D proves the pane is back at the shell, regardless of the last hook state.
+  if (state.paneForegroundAgentByPaneKey?.[paneKey]?.shellForeground === true) {
+    return null
+  }
+  return entry.providerSession?.id ?? null
+}
diff --git a/src/renderer/src/components/tab-bar/tab-context-menu-consistency.test.tsx b/src/renderer/src/components/tab-bar/tab-context-menu-consistency.test.tsx
index c81eae348dd..54f762d4611 100644
--- a/src/renderer/src/components/tab-bar/tab-context-menu-consistency.test.tsx
+++ b/src/renderer/src/components/tab-bar/tab-context-menu-consistency.test.tsx
@@ -13,6 +13,7 @@ import {
 const TAB_MENU_SOURCES = [
   'EditorFileTabContextMenu.tsx',
   'SortableTabContextMenu.tsx',
+  'TabAgentSessionIdMenuItem.tsx',
   'BrowserTab.tsx',
   'TabWorkspaceLayoutMenuSection.tsx',
   'TerminalTabSplitMenuSection.tsx'
diff --git a/src/renderer/src/i18n/locales/en.json b/src/renderer/src/i18n/locales/en.json
index 7fc9c837ebc..22b1695cc3d 100644
--- a/src/renderer/src/i18n/locales/en.json
+++ b/src/renderer/src/i18n/locales/en.json
@@ -16724,7 +16724,10 @@
         "SortableTabContextMenu": {
           "switchToTerminalView": "Switch to terminal view",
           "switchToChatView": "Switch to chat view",
-          "closeTabsToLeft": "Close Tabs To The Left"
+          "closeTabsToLeft": "Close Tabs To The Left",
+          "copySessionId": "Copy Session ID",
+          "copySessionIdSuccess": "Session ID copied",
+          "copySessionIdError": "Failed to copy Session ID"
         },
         "BrowserTab": {
           "closeOthers": "Close Others",
diff --git a/src/renderer/src/i18n/locales/es.json b/src/renderer/src/i18n/locales/es.json
index 1c8a5c7325b..be6e087060d 100644
--- a/src/renderer/src/i18n/locales/es.json
+++ b/src/renderer/src/i18n/locales/es.json
@@ -14646,7 +14646,10 @@
         "SortableTabContextMenu": {
           "switchToTerminalView": "Cambiar a la vista de terminal",
           "switchToChatView": "Cambiar a vista de chat",
-          "closeTabsToLeft": "Cerrar pestañas a la izquierda"
+          "closeTabsToLeft": "Cerrar pestañas a la izquierda",
+          "copySessionId": "Copiar ID de sesión",
+          "copySessionIdSuccess": "ID de sesión copiado",
+          "copySessionIdError": "No se pudo copiar el ID de sesión"
         },
         "BrowserTab": {
           "closeOthers": "Cerrar otras",
diff --git a/src/renderer/src/i18n/locales/ja.json b/src/renderer/src/i18n/locales/ja.json
index 334e9e32d27..20e2fca6553 100644
--- a/src/renderer/src/i18n/locales/ja.json
+++ b/src/renderer/src/i18n/locales/ja.json
@@ -14646,7 +14646,10 @@
         "SortableTabContextMenu": {
           "switchToTerminalView": "ターミナルビューに切り替える",
           "switchToChatView": "チャットビューに切り替える",
-          "closeTabsToLeft": "左側のタブを閉じる"
+          "closeTabsToLeft": "左側のタブを閉じる",
+          "copySessionId": "セッション ID をコピー",
+          "copySessionIdSuccess": "セッション ID をコピーしました",
+          "copySessionIdError": "セッション ID のコピーに失敗しました"
         },
         "BrowserTab": {
           "closeOthers": "その他を閉じる",
diff --git a/src/renderer/src/i18n/locales/ko.json b/src/renderer/src/i18n/locales/ko.json
index 7ef6c53ca86..e9b9c48fcdf 100644
--- a/src/renderer/src/i18n/locales/ko.json
+++ b/src/renderer/src/i18n/locales/ko.json
@@ -14689,7 +14689,10 @@
         "SortableTabContextMenu": {
           "switchToTerminalView": "terminal 보기로 전환",
           "switchToChatView": "채팅 보기로 전환",
-          "closeTabsToLeft": "왼쪽으로 탭 닫기"
+          "closeTabsToLeft": "왼쪽으로 탭 닫기",
+          "copySessionId": "세션 ID 복사",
+          "copySessionIdSuccess": "세션 ID를 복사했습니다",
+          "copySessionIdError": "세션 ID를 복사하지 못했습니다"
         },
         "BrowserTab": {
           "closeOthers": "다른 탭 닫기",
diff --git a/src/renderer/src/i18n/locales/zh.json b/src/renderer/src/i18n/locales/zh.json
index 06fae6cca89..49560989924 100644
--- a/src/renderer/src/i18n/locales/zh.json
+++ b/src/renderer/src/i18n/locales/zh.json
@@ -14689,7 +14689,10 @@
         "SortableTabContextMenu": {
           "switchToTerminalView": "切换到终端视图",
           "switchToChatView": "切换到聊天视图",
-          "closeTabsToLeft": "关闭左侧的选项卡"
+          "closeTabsToLeft": "关闭左侧的选项卡",
+          "copySessionId": "复制会话 ID",
+          "copySessionIdSuccess": "已复制会话 ID",
+          "copySessionIdError": "复制会话 ID 失败"
         },
         "BrowserTab": {
           "closeOthers": "关闭其他",
diff --git a/tests/e2e/tab-context-menu-session-id.spec.ts b/tests/e2e/tab-context-menu-session-id.spec.ts
new file mode 100644
index 00000000000..cab18bace32
--- /dev/null
+++ b/tests/e2e/tab-context-menu-session-id.spec.ts
@@ -0,0 +1,76 @@
+/**
+ * E2E coverage for copying an agent provider session ID from a terminal tab's
+ * context menu.
+ */
+
+import { test, expect } from './helpers/orca-app'
+import {
+  ensureTerminalVisible,
+  getActiveTabId,
+  waitForActiveWorktree,
+  waitForSessionReady
+} from './helpers/store'
+import { waitForPaneIdentitySnapshot } from './helpers/terminal'
+
+const SESSION_ID = 'e2e-terminal-tab-session'
+
+test('terminal tab context menu copies the active agent session ID', async ({ orcaPage }) => {
+  await waitForSessionReady(orcaPage)
+  const worktreeId = await waitForActiveWorktree(orcaPage)
+  await ensureTerminalVisible(orcaPage)
+
+  const tabId = await getActiveTabId(orcaPage)
+  if (!tabId) {
+    throw new Error('No active terminal tab')
+  }
+  const snapshot = await waitForPaneIdentitySnapshot(orcaPage, 1)
+  const leafId = snapshot.panes[0]?.leafId
+  if (!leafId) {
+    throw new Error('No active terminal pane')
+  }
+  const paneKey = `${tabId}:${leafId}`
+
+  // Seed the same renderer state a live agent hook produces while keeping the
+  // test independent of an installed provider CLI.
+  await orcaPage.evaluate(
+    ({ paneKey, tabId, worktreeId, sessionId }) => {
+      const state = window.__store?.getState()
+      if (!state) {
+        throw new Error('Store unavailable')
+      }
+      state.setAgentStatus(
+        paneKey,
+        { state: 'working', prompt: 'copy session id', agentType: 'claude' },
+        'Claude',
+        undefined,
+        { tabId, worktreeId },
+        { providerSession: { key: 'session_id', id: sessionId } }
+      )
+    },
+    { paneKey, tabId, worktreeId, sessionId: SESSION_ID }
+  )
+
+  await expect
+    .poll(
+      () =>
+        orcaPage.evaluate(
+          ({ paneKey }) =>
+            window.__store?.getState().agentStatusByPaneKey[paneKey]?.providerSession?.id,
+          { paneKey }
+        ),
+      { timeout: 3_000 }
+    )
+    .toBe(SESSION_ID)
+
+  const tab = orcaPage.locator(`[data-testid="sortable-tab"][data-tab-id="${tabId}"]`)
+  await expect(tab).toBeVisible()
+  await tab.click({ button: 'right' })
+
+  const copyItem = orcaPage.getByRole('menuitem', { name: 'Copy Session ID', exact: true })
+  await expect(copyItem).toBeVisible()
+  await copyItem.click()
+
+  await expect
+    .poll(() => orcaPage.evaluate(() => window.api.ui.readClipboardText()), { timeout: 3_000 })
+    .toBe(SESSION_ID)
+})

From a7fda48fe3faa55b6248cd570165095be042e769 Mon Sep 17 00:00:00 2001
From: Jinwoo Hong <73622457+Jinwoo-H@users.noreply.github.com>
Date: Tue, 1 Sep 2026 22:33:39 -0400
Subject: [PATCH 26/32] feat(telemetry): measure macOS stale-daemon adoption
 and cwd denials (#18043)

* feat(telemetry): measure macOS stale-daemon adoption and cwd denials

Adds two enum-only PostHog events so #17696 can be sized instead of guessed at:

- daemon_adopted: once per macOS launch that keeps a daemon an earlier app
  launch forked (invisible to daemon_lifecycle, which only sees replacements).
  Carries app-version match, spawner-path class (installed app / Squirrel
  ShipIt cache / other / missing), the existing TCC attribution verdict, and
  the bucketed live-session count.
- daemon_pty_cwd_denied: the symptom itself. The daemon probes the requested
  cwd in its own process (only its TCC context counts) and returns an additive
  cwdReadableByDaemon field; the app emits only when the daemon was denied AND
  the app can read the same path, so a missing or genuinely unreadable cwd
  never counts. Non-permission errors read as readable on purpose.

Both emitters swallow every failure; nothing here can delay or fail daemon
startup or a PTY spawn. Off macOS neither event fires. The new wire field is
optional, so older daemons and clients are unaffected.

* fix(telemetry): keep cwd-denial classification inside the swallow guard

Read the pid record at emit time (inside the try) rather than passing the
adapter's startup snapshot: a throwing app-environment read can no longer
escape spawn(), and a denial after a respawn is billed to the daemon that
actually spawned the PTY.
---
 .../daemon-adoption-telemetry-event.test.ts   | 168 ++++++++++++++++++
 .../daemon/daemon-adoption-telemetry-event.ts |  81 +++++++++
 .../daemon/daemon-create-or-attach-result.ts  |   6 +
 .../daemon/daemon-init-dependency-mocks.ts    |   9 +-
 src/main/daemon/daemon-init-fresh-import.ts   |   4 +-
 src/main/daemon/daemon-init-mock-types.ts     |   3 +
 .../daemon-init-provider-installation.test.ts |  45 +++++
 src/main/daemon/daemon-init-test-harness.ts   |   4 +-
 .../daemon/daemon-out-of-process-launcher.ts  |   1 +
 src/main/daemon/daemon-provider-init.ts       |  31 ++++
 src/main/daemon/daemon-pty-session-spawn.ts   |   4 +
 src/main/daemon/daemon-spawner.ts             |   2 +
 src/main/daemon/daemon-terminal-admission.ts  |   5 +-
 .../daemon/terminal-host-create-contract.ts   |   2 +
 .../terminal-host-cwd-readability.test.ts     |  75 ++++++++
 .../daemon/terminal-host-session-create.ts    |  17 ++
 src/main/ipc/telemetry.ts                     |   2 +
 src/shared/daemon-adoption-telemetry.test.ts  |  89 ++++++++++
 src/shared/daemon-adoption-telemetry.ts       |  67 +++++++
 src/shared/telemetry-daemon-event-schemas.ts  |  27 +++
 src/shared/telemetry-event-registry.ts        |   4 +
 21 files changed, 642 insertions(+), 4 deletions(-)
 create mode 100644 src/main/daemon/daemon-adoption-telemetry-event.test.ts
 create mode 100644 src/main/daemon/daemon-adoption-telemetry-event.ts
 create mode 100644 src/main/daemon/terminal-host-cwd-readability.test.ts
 create mode 100644 src/shared/daemon-adoption-telemetry.test.ts
 create mode 100644 src/shared/daemon-adoption-telemetry.ts

diff --git a/src/main/daemon/daemon-adoption-telemetry-event.test.ts b/src/main/daemon/daemon-adoption-telemetry-event.test.ts
new file mode 100644
index 00000000000..5a5cd7406c4
--- /dev/null
+++ b/src/main/daemon/daemon-adoption-telemetry-event.test.ts
@@ -0,0 +1,168 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { ParsedDaemonPid } from './daemon-pid-file-parse'
+import { validate } from '../telemetry/validator'
+
+const { trackMock, accessSyncMock, existsSyncMock, readFileSyncMock, getVersionMock } = vi.hoisted(
+  () => ({
+    trackMock: vi.fn(),
+    accessSyncMock: vi.fn(),
+    existsSyncMock: vi.fn(() => true),
+    readFileSyncMock: vi.fn(),
+    getVersionMock: vi.fn(() => '1.4.191')
+  })
+)
+vi.mock('../telemetry/client', () => ({ track: trackMock }))
+vi.mock('node:fs', async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  accessSync: accessSyncMock,
+  existsSync: existsSyncMock,
+  readFileSync: readFileSyncMock
+}))
+vi.mock('node:os', async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  homedir: () => '/Users/alice'
+}))
+vi.mock('../../shared/app-environment', () => ({
+  getAppEnvironment: () => ({ getVersion: getVersionMock })
+}))
+
+import {
+  classifyDaemonAdoptionOrigin,
+  trackDaemonAdopted,
+  trackDaemonPtyCwdDeniedIfDiverged
+} from './daemon-adoption-telemetry-event'
+
+const stalePidRecord: ParsedDaemonPid = {
+  pid: 1530,
+  startedAtMs: 1,
+  entryPath: '/x/daemon-entry.js',
+  appVersion: '1.4.187',
+  launchNonce: 'n',
+  linuxStartTicks: null,
+  bootId: null,
+  spawnerExecPath:
+    '/Users/alice/Library/Caches/com.stablyai.orca.ShipIt/u/Orca.app/Contents/MacOS/Orca'
+}
+const origin = { app_version_match: 'different', spawner_path_class: 'updater-cache' } as const
+const PID_PATH = '/fake/daemon.pid'
+
+beforeEach(() => {
+  trackMock.mockReset()
+  accessSyncMock.mockReset()
+  existsSyncMock.mockReset().mockReturnValue(true)
+  readFileSyncMock.mockReset().mockReturnValue(JSON.stringify(stalePidRecord))
+  vi.spyOn(process, 'platform', 'get').mockReturnValue('darwin')
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+describe('classifyDaemonAdoptionOrigin', () => {
+  it('compares the recorded app version and classifies the spawner path', () => {
+    expect(classifyDaemonAdoptionOrigin(stalePidRecord)).toEqual(origin)
+    expect(classifyDaemonAdoptionOrigin({ ...stalePidRecord, appVersion: '1.4.191' })).toEqual({
+      app_version_match: 'same',
+      spawner_path_class: 'updater-cache'
+    })
+    expect(classifyDaemonAdoptionOrigin(null)).toEqual({
+      app_version_match: 'unknown',
+      spawner_path_class: 'unknown'
+    })
+  })
+})
+
+describe('trackDaemonAdopted', () => {
+  it('emits a validator-accepted payload', () => {
+    trackDaemonAdopted(stalePidRecord, 'intact', 7)
+    expect(trackMock).toHaveBeenCalledTimes(1)
+    const [name, props] = trackMock.mock.calls[0]
+    expect(name).toBe('daemon_adopted')
+    expect(props).toEqual({
+      ...origin,
+      tcc_attribution: 'intact',
+      live_session_count_bucket: '6+'
+    })
+    expect(validate('daemon_adopted', props).ok).toBe(true)
+  })
+
+  it('swallows a throwing telemetry client', () => {
+    trackMock.mockImplementationOnce(() => {
+      throw new Error('posthog exploded')
+    })
+    expect(() => trackDaemonAdopted(null, 'unknown', null)).not.toThrow()
+  })
+})
+
+describe('trackDaemonPtyCwdDeniedIfDiverged', () => {
+  it('emits only when the daemon was denied and the app can read the same cwd', () => {
+    trackDaemonPtyCwdDeniedIfDiverged('/Users/alice/Documents/repo', false, PID_PATH)
+    expect(accessSyncMock).toHaveBeenCalledWith('/Users/alice/Documents/repo', expect.any(Number))
+    expect(trackMock).toHaveBeenCalledTimes(1)
+    const [name, props] = trackMock.mock.calls[0]
+    expect(name).toBe('daemon_pty_cwd_denied')
+    expect(props).toEqual({ cwd_class: 'documents', ...origin })
+    expect(validate('daemon_pty_cwd_denied', props).ok).toBe(true)
+  })
+
+  // False positives would drown the signal this event exists to measure, so every
+  // non-divergent shape must stay silent.
+  it('stays silent when the daemon could read the cwd or did not report', () => {
+    trackDaemonPtyCwdDeniedIfDiverged('/Users/alice/Documents/repo', true, PID_PATH)
+    trackDaemonPtyCwdDeniedIfDiverged('/Users/alice/Documents/repo', undefined, PID_PATH)
+    trackDaemonPtyCwdDeniedIfDiverged(undefined, false, PID_PATH)
+    expect(accessSyncMock).not.toHaveBeenCalled()
+    expect(trackMock).not.toHaveBeenCalled()
+  })
+
+  it('stays silent when the app cannot read the cwd either (no divergence)', () => {
+    accessSyncMock.mockImplementation(() => {
+      throw Object.assign(new Error('EACCES'), { code: 'EACCES' })
+    })
+    trackDaemonPtyCwdDeniedIfDiverged('/Users/alice/Documents/repo', false, PID_PATH)
+    expect(trackMock).not.toHaveBeenCalled()
+  })
+
+  it('attributes the denial to the daemon recorded right now, not a startup snapshot', () => {
+    readFileSyncMock.mockReturnValue(
+      JSON.stringify({
+        ...stalePidRecord,
+        appVersion: '1.4.191',
+        spawnerExecPath: '/Applications/Orca.app/Contents/MacOS/Orca'
+      })
+    )
+    trackDaemonPtyCwdDeniedIfDiverged('/Users/alice/Documents/repo', false, PID_PATH)
+    expect(readFileSyncMock).toHaveBeenCalledWith(PID_PATH, 'utf8')
+    expect(trackMock.mock.calls[0][1]).toEqual({
+      cwd_class: 'documents',
+      app_version_match: 'same',
+      spawner_path_class: 'applications'
+    })
+  })
+
+  it('swallows a throwing app environment or pid-record read instead of failing the spawn', () => {
+    getVersionMock.mockImplementationOnce(() => {
+      throw new Error('AppEnvironment not initialized')
+    })
+    expect(() =>
+      trackDaemonPtyCwdDeniedIfDiverged('/Users/alice/Documents/repo', false, PID_PATH)
+    ).not.toThrow()
+    expect(trackMock).not.toHaveBeenCalled()
+  })
+
+  it('stays silent off macOS', () => {
+    vi.spyOn(process, 'platform', 'get').mockReturnValue('linux')
+    trackDaemonPtyCwdDeniedIfDiverged('/home/alice/Documents/repo', false, PID_PATH)
+    expect(accessSyncMock).not.toHaveBeenCalled()
+    expect(trackMock).not.toHaveBeenCalled()
+  })
+
+  it('swallows a throwing telemetry client', () => {
+    trackMock.mockImplementationOnce(() => {
+      throw new Error('posthog exploded')
+    })
+    expect(() =>
+      trackDaemonPtyCwdDeniedIfDiverged('/Users/alice/Documents/repo', false, PID_PATH)
+    ).not.toThrow()
+  })
+})
diff --git a/src/main/daemon/daemon-adoption-telemetry-event.ts b/src/main/daemon/daemon-adoption-telemetry-event.ts
new file mode 100644
index 00000000000..47f554bf9bb
--- /dev/null
+++ b/src/main/daemon/daemon-adoption-telemetry-event.ts
@@ -0,0 +1,81 @@
+// App-side emitters for `daemon_adopted` and `daemon_pty_cwd_denied` (#17696). Both sit on the
+// daemon launch / PTY spawn path, so every failure dies here — telemetry can never cost a terminal.
+
+import { accessSync, constants as fsConstants, existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { getAppEnvironment } from '../../shared/app-environment'
+import {
+  classifyDaemonPtyCwd,
+  classifyDaemonSpawnerPath,
+  type DaemonAdoptedAppVersionMatch,
+  type DaemonSpawnerPathClass
+} from '../../shared/daemon-adoption-telemetry'
+import { bucketDaemonLiveSessionCount } from '../../shared/daemon-lifecycle-telemetry'
+import type { EventProps } from '../../shared/telemetry-events'
+import { track } from '../telemetry/client'
+import { readDaemonPidRecord } from './daemon-endpoint-incarnation'
+import type { ParsedDaemonPid } from './daemon-pid-file-parse'
+import type { MacDaemonTccAttributionHealth } from './daemon-tcc-attribution'
+
+export type DaemonAdoptionOrigin = Pick<
+  EventProps<'daemon_pty_cwd_denied'>,
+  'app_version_match' | 'spawner_path_class'
+>
+
+/** Classifies the adopted daemon's pid record against the running app; enum-only by construction. */
+export function classifyDaemonAdoptionOrigin(
+  pidRecord: ParsedDaemonPid | null
+): DaemonAdoptionOrigin {
+  const appVersionMatch: DaemonAdoptedAppVersionMatch = !pidRecord?.appVersion
+    ? 'unknown'
+    : pidRecord.appVersion === getAppEnvironment().getVersion()
+      ? 'same'
+      : 'different'
+  const spawnerPathClass: DaemonSpawnerPathClass = classifyDaemonSpawnerPath(
+    pidRecord?.spawnerExecPath ?? null,
+    existsSync
+  )
+  return { app_version_match: appVersionMatch, spawner_path_class: spawnerPathClass }
+}
+
+// Adopted a daemon that a previous app launch forked (macOS only; that is where attribution matters).
+export function trackDaemonAdopted(
+  pidRecord: ParsedDaemonPid | null,
+  tccAttribution: MacDaemonTccAttributionHealth,
+  liveSessionCount: number | null
+): void {
+  try {
+    track('daemon_adopted', {
+      ...classifyDaemonAdoptionOrigin(pidRecord),
+      tcc_attribution: tccAttribution,
+      live_session_count_bucket: bucketDaemonLiveSessionCount(liveSessionCount)
+    })
+  } catch {
+    // Telemetry is best-effort; a dropped event must not fail daemon adoption.
+  }
+}
+
+/**
+ * Emits only on proven divergence: the daemon reported the cwd unreadable AND this process can
+ * read it. A cwd neither can read (chmod, ENOENT, unmounted volume) is not the #17696 shape.
+ */
+export function trackDaemonPtyCwdDeniedIfDiverged(
+  cwd: string | undefined,
+  cwdReadableByDaemon: boolean | undefined,
+  pidPath: string | null
+): void {
+  try {
+    if (process.platform !== 'darwin' || !cwd || cwdReadableByDaemon !== false) {
+      return
+    }
+    accessSync(cwd, fsConstants.R_OK | fsConstants.X_OK)
+    // Why read now, not the adapter's startup snapshot: a respawn swaps the daemon under a
+    // long-lived adapter, and the denial must be attributed to the daemon that just spawned.
+    track('daemon_pty_cwd_denied', {
+      cwd_class: classifyDaemonPtyCwd(cwd, homedir()),
+      ...classifyDaemonAdoptionOrigin(readDaemonPidRecord(pidPath))
+    })
+  } catch {
+    // Either the app cannot read it (no divergence) or telemetry failed; neither may reach the caller.
+  }
+}
diff --git a/src/main/daemon/daemon-create-or-attach-result.ts b/src/main/daemon/daemon-create-or-attach-result.ts
index d6668342487..92a7e451a10 100644
--- a/src/main/daemon/daemon-create-or-attach-result.ts
+++ b/src/main/daemon/daemon-create-or-attach-result.ts
@@ -14,6 +14,12 @@ export type DaemonCreateOrAttachResult = {
   wslDistro?: string | null
   agentSessionEnsure?: AgentSessionClaimedSpawnResult
   incarnationId?: PtyIncarnationId
+  /**
+   * Whether the daemon process itself could read the requested cwd at spawn. Only the daemon's own
+   * verdict counts: macOS TCC scopes folder access per process tree, so the app's view of the same
+   * path proves nothing about the daemon's (#17696). Omitted by daemons predating this field.
+   */
+  cwdReadableByDaemon?: boolean
 }
 
 export function getDaemonSessionResultMetadata(session: {
diff --git a/src/main/daemon/daemon-init-dependency-mocks.ts b/src/main/daemon/daemon-init-dependency-mocks.ts
index d920a13866e..d7217d4df63 100644
--- a/src/main/daemon/daemon-init-dependency-mocks.ts
+++ b/src/main/daemon/daemon-init-dependency-mocks.ts
@@ -50,7 +50,8 @@ export function createDaemonInitModuleFactories(state: DaemonInitMockState) {
     unbindLocalProviderListenersMock,
     rebindLocalProviderListenersMock,
     trackDaemonReplacedMock,
-    trackDaemonRetiredMock
+    trackDaemonRetiredMock,
+    trackDaemonAdoptedMock
   } = state
 
   // Why: both fakes are annotated with constructor types so the exported factories widen to
@@ -82,6 +83,9 @@ export function createDaemonInitModuleFactories(state: DaemonInitMockState) {
           if (result.mode) {
             this.handle.mode = result.mode
           }
+          if (result.adopted) {
+            this.handle.adopted = true
+          }
           return {
             socketPath: result.socketPath,
             tokenPath: result.tokenPath
@@ -199,6 +203,9 @@ export function createDaemonInitModuleFactories(state: DaemonInitMockState) {
       trackDaemonReplaced: trackDaemonReplacedMock,
       trackDaemonRetired: trackDaemonRetiredMock
     }),
+    daemonAdoptionTelemetryEvent: () => ({
+      trackDaemonAdopted: trackDaemonAdoptedMock
+    }),
     daemonSpawner: () => ({
       DaemonSpawner: MockDaemonSpawner,
       getDaemonSocketPath: (_dir: string, version?: number) =>
diff --git a/src/main/daemon/daemon-init-fresh-import.ts b/src/main/daemon/daemon-init-fresh-import.ts
index e1cc0416337..39f3625c063 100644
--- a/src/main/daemon/daemon-init-fresh-import.ts
+++ b/src/main/daemon/daemon-init-fresh-import.ts
@@ -41,7 +41,8 @@ export async function importFreshDaemonInit(state: DaemonInitMockState) {
     unbindLocalProviderListenersMock,
     rebindLocalProviderListenersMock,
     trackDaemonReplacedMock,
-    trackDaemonRetiredMock
+    trackDaemonRetiredMock,
+    trackDaemonAdoptedMock
   } = state
 
   vi.resetModules()
@@ -64,6 +65,7 @@ export async function importFreshDaemonInit(state: DaemonInitMockState) {
   rebindLocalProviderListenersMock.mockClear()
   trackDaemonReplacedMock.mockClear()
   trackDaemonRetiredMock.mockClear()
+  trackDaemonAdoptedMock.mockClear()
   checkDaemonHealthMock.mockClear()
   checkDaemonHealthMock.mockResolvedValue('healthy')
   healthCheckDaemonMock.mockClear()
diff --git a/src/main/daemon/daemon-init-mock-types.ts b/src/main/daemon/daemon-init-mock-types.ts
index 8c8b805740f..341fcd26df7 100644
--- a/src/main/daemon/daemon-init-mock-types.ts
+++ b/src/main/daemon/daemon-init-mock-types.ts
@@ -47,6 +47,7 @@ export type MockAdapterConstructor = new (opts: MockAdapter['options']) => MockA
 /** Handle the fake spawner hands back from ensureRunning/getHandle. */
 export type MockSpawnerHandle = {
   mode?: 'degraded-new-pty-fallback'
+  adopted?: true
   releaseAdoptionLease?: () => void
   shutdown: () => Promise<void>
 }
@@ -95,6 +96,7 @@ export type EnsureRunningOverride = () => Promise<{
   socketPath: string
   tokenPath: string
   mode?: 'degraded-new-pty-fallback'
+  adopted?: true
 }>
 
 /** Every stub daemon-init's suites share, plus the control knobs they mutate per test. */
@@ -143,6 +145,7 @@ export type DaemonInitMockState = {
   rebindLocalProviderListenersMock: Mock<(...args: unknown[]) => void>
   trackDaemonReplacedMock: Mock<(...args: unknown[]) => void>
   trackDaemonRetiredMock: Mock<(...args: unknown[]) => void>
+  trackDaemonAdoptedMock: Mock<(...args: unknown[]) => void>
 }
 
 /** net.connect stubs the suites install in beforeEach. */
diff --git a/src/main/daemon/daemon-init-provider-installation.test.ts b/src/main/daemon/daemon-init-provider-installation.test.ts
index ceb7e9dfa69..423ee9ee34f 100644
--- a/src/main/daemon/daemon-init-provider-installation.test.ts
+++ b/src/main/daemon/daemon-init-provider-installation.test.ts
@@ -2,6 +2,8 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 const {
   isPackagedMock,
+  getMacDaemonTccAttributionHealthMock,
+  trackDaemonAdoptedMock,
   probeSocketExistsMock,
   readFileSyncMock,
   unlinkSyncMock,
@@ -42,6 +44,7 @@ vi.mock('./daemon-process-start-time', () => moduleFactories.daemonProcessStartT
 vi.mock('./daemon-pid-file-parse', () => moduleFactories.daemonPidFileParse())
 vi.mock('./client', () => moduleFactories.client())
 vi.mock('./daemon-lifecycle-event', () => moduleFactories.daemonLifecycleEvent())
+vi.mock('./daemon-adoption-telemetry-event', () => moduleFactories.daemonAdoptionTelemetryEvent())
 vi.mock('./daemon-spawner', () => moduleFactories.daemonSpawner())
 vi.mock('./daemon-pty-adapter', () => moduleFactories.daemonPtyAdapter())
 vi.mock('../ipc/pty', () => moduleFactories.ipcPty())
@@ -228,6 +231,48 @@ describe('daemon-init: runRestartDaemon (7-step sequence)', () => {
     expect(adapterInstances[1].disconnectOnly).toHaveBeenCalledOnce()
   })
 
+  // #17696: adopting a daemon from an earlier app launch is invisible to daemon_lifecycle, so
+  // it gets its own event — macOS only, and only for adopted (not freshly forked) daemons.
+  it('reports a macOS daemon adoption with its TCC attribution and live session bucket', async () => {
+    vi.spyOn(process, 'platform', 'get').mockReturnValue('darwin')
+    const mod = await importFresh()
+    ensureRunningOverrides.push(async () => ({
+      socketPath: '/fake/adopted-socket',
+      tokenPath: '/fake/adopted-token',
+      adopted: true
+    }))
+    getMacDaemonTccAttributionHealthMock.mockResolvedValueOnce('severed')
+    defaultListSessionsSessions.push({ sessionId: 'wt-1@@a' }, { sessionId: 'wt-1@@b' })
+
+    await mod.initDaemonPtyProvider()
+    await vi.waitFor(() => expect(trackDaemonAdoptedMock).toHaveBeenCalledOnce())
+
+    // null pid record: the harness has no pid file, which the emitter classifies as 'unknown'.
+    expect(trackDaemonAdoptedMock).toHaveBeenCalledWith(null, 'severed', 2)
+    vi.restoreAllMocks()
+  })
+
+  it('does not report adoption for a freshly forked daemon or off macOS', async () => {
+    vi.spyOn(process, 'platform', 'get').mockReturnValue('darwin')
+    const mod = await importFresh()
+    await mod.initDaemonPtyProvider()
+    await new Promise((resolve) => setImmediate(resolve))
+    expect(trackDaemonAdoptedMock).not.toHaveBeenCalled()
+    vi.restoreAllMocks()
+
+    vi.spyOn(process, 'platform', 'get').mockReturnValue('linux')
+    const linuxMod = await importFresh()
+    ensureRunningOverrides.push(async () => ({
+      socketPath: '/fake/adopted-socket',
+      tokenPath: '/fake/adopted-token',
+      adopted: true
+    }))
+    await linuxMod.initDaemonPtyProvider()
+    await new Promise((resolve) => setImmediate(resolve))
+    expect(trackDaemonAdoptedMock).not.toHaveBeenCalled()
+    vi.restoreAllMocks()
+  })
+
   it('routes fresh PTYs to the local fallback when a preserved daemon cannot spawn new PTYs', async () => {
     const mod = await importFresh()
     ensureRunningOverrides.push(async () => ({
diff --git a/src/main/daemon/daemon-init-test-harness.ts b/src/main/daemon/daemon-init-test-harness.ts
index 6c38720a40b..6060ed9b759 100644
--- a/src/main/daemon/daemon-init-test-harness.ts
+++ b/src/main/daemon/daemon-init-test-harness.ts
@@ -156,6 +156,7 @@ function createDaemonInitMockState(): DaemonInitMockState {
   const rebindLocalProviderListenersMock = vi.fn()
   const trackDaemonReplacedMock = vi.fn()
   const trackDaemonRetiredMock = vi.fn()
+  const trackDaemonAdoptedMock = vi.fn()
 
   return {
     getPathMock,
@@ -197,7 +198,8 @@ function createDaemonInitMockState(): DaemonInitMockState {
     unbindLocalProviderListenersMock,
     rebindLocalProviderListenersMock,
     trackDaemonReplacedMock,
-    trackDaemonRetiredMock
+    trackDaemonRetiredMock,
+    trackDaemonAdoptedMock
   }
 }
 
diff --git a/src/main/daemon/daemon-out-of-process-launcher.ts b/src/main/daemon/daemon-out-of-process-launcher.ts
index b59535a249a..21ff31918ac 100644
--- a/src/main/daemon/daemon-out-of-process-launcher.ts
+++ b/src/main/daemon/daemon-out-of-process-launcher.ts
@@ -41,6 +41,7 @@ function createPreservedDaemonHandle(
   mode?: 'degraded-new-pty-fallback'
 ): DaemonProcessHandle {
   const handle: DaemonProcessHandle = {
+    adopted: true,
     shutdown: async () => {
       await cleanupDaemonForProtocol(runtimeDir, protocolVersion)
     }
diff --git a/src/main/daemon/daemon-provider-init.ts b/src/main/daemon/daemon-provider-init.ts
index 1881e276e97..fa794257bda 100644
--- a/src/main/daemon/daemon-provider-init.ts
+++ b/src/main/daemon/daemon-provider-init.ts
@@ -24,7 +24,10 @@ import {
 import type { DaemonProvider } from './daemon-provider-routing'
 import { installDaemonProvider } from './daemon-provider-state'
 import { DegradedDaemonPtyProvider } from './degraded-daemon-pty-provider'
+import { trackDaemonAdopted } from './daemon-adoption-telemetry-event'
+import { readDaemonPidRecord } from './daemon-endpoint-incarnation'
 import { trackDaemonRetired } from './daemon-lifecycle-event'
+import { getMacDaemonTccAttributionHealth } from './daemon-tcc-attribution'
 import { DaemonPtyAdapter } from './daemon-pty-adapter'
 import type { DaemonRespawnReason } from './daemon-pty-runtime-state'
 import { DaemonPtyRouter } from './daemon-pty-router'
@@ -156,9 +159,37 @@ export async function initDaemonPtyProvider(
   logDaemonMilestone('daemon-init-done', {
     legacyAdapters: legacyAdapters.length
   })
+  if (process.platform === 'darwin' && newSpawner.getHandle()?.adopted) {
+    void reportDaemonAdoption(runtimeDir, info.socketPath, info.tokenPath, newAdapter)
+  }
   await reconcileSeededClaudeLivePtys(routedAdapter)
 }
 
+// Why off the init path: this is measurement of an adopted daemon (#17696), and neither its probes nor their failure may delay or fail startup.
+async function reportDaemonAdoption(
+  runtimeDir: string,
+  socketPath: string,
+  tokenPath: string,
+  adapter: DaemonPtyAdapter
+): Promise<void> {
+  try {
+    const [tccAttribution, liveSessionCount] = await Promise.all([
+      getMacDaemonTccAttributionHealth(runtimeDir, socketPath, tokenPath),
+      adapter.listSessions().then(
+        (sessions) => sessions.length,
+        () => null
+      )
+    ])
+    trackDaemonAdopted(
+      readDaemonPidRecord(getDaemonPidPath(runtimeDir)),
+      tccAttribution,
+      liveSessionCount
+    )
+  } catch {
+    // Best-effort measurement only.
+  }
+}
+
 // 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()) {
diff --git a/src/main/daemon/daemon-pty-session-spawn.ts b/src/main/daemon/daemon-pty-session-spawn.ts
index 62c073f403e..235b286b0bc 100644
--- a/src/main/daemon/daemon-pty-session-spawn.ts
+++ b/src/main/daemon/daemon-pty-session-spawn.ts
@@ -4,6 +4,7 @@ import type {
   HistoryRecoveryContext,
   PendingDaemonSpawnOperation
 } from './daemon-pty-runtime-state'
+import { trackDaemonPtyCwdDeniedIfDiverged } from './daemon-adoption-telemetry-event'
 import { STABLE_PANE_ATTACH_ONLY_DAEMON_PROTOCOL_VERSION } from './daemon-protocol-version'
 import { TerminalKilledError } from './daemon-pty-lifecycle-errors'
 import { DaemonPtySpawnResult } from './daemon-pty-spawn-result'
@@ -246,6 +247,9 @@ export abstract class DaemonPtySessionSpawn extends DaemonPtySpawnResult {
     }
     activeSpawnContext = context
     const result = await this.createOrAttachSpawn(context, context.historySeedSegments)
+    if (result.isNew && !attachOnly) {
+      trackDaemonPtyCwdDeniedIfDiverged(effectiveCwd, result.cwdReadableByDaemon, this.pidPath)
+    }
     return this.finishSpawn(context, result)
   }
 
diff --git a/src/main/daemon/daemon-spawner.ts b/src/main/daemon/daemon-spawner.ts
index a0376ef0fc0..8c50b764b05 100644
--- a/src/main/daemon/daemon-spawner.ts
+++ b/src/main/daemon/daemon-spawner.ts
@@ -31,6 +31,8 @@ export type DaemonPidFile = {
 
 export type DaemonProcessHandle = {
   mode?: 'degraded-new-pty-fallback'
+  /** Set when the launcher kept a daemon some earlier app launch forked, rather than forking one. */
+  adopted?: true
   releaseAdoptionLease?(): void
   shutdown(): Promise<void>
 }
diff --git a/src/main/daemon/daemon-terminal-admission.ts b/src/main/daemon/daemon-terminal-admission.ts
index b47b497fe43..83dadf5f5d2 100644
--- a/src/main/daemon/daemon-terminal-admission.ts
+++ b/src/main/daemon/daemon-terminal-admission.ts
@@ -161,7 +161,10 @@ export class DaemonTerminalAdmission {
       ...(result.launchAgent ? { launchAgent: result.launchAgent } : {}),
       wslDistro: result.wslDistro,
       ...(result.historySeeded !== undefined ? { historySeeded: result.historySeeded } : {}),
-      ...(result.agentSessionEnsure ? { agentSessionEnsure: result.agentSessionEnsure } : {})
+      ...(result.agentSessionEnsure ? { agentSessionEnsure: result.agentSessionEnsure } : {}),
+      ...(result.cwdReadableByDaemon !== undefined
+        ? { cwdReadableByDaemon: result.cwdReadableByDaemon }
+        : {})
     }
   }
 
diff --git a/src/main/daemon/terminal-host-create-contract.ts b/src/main/daemon/terminal-host-create-contract.ts
index aaaffaeb8e8..42f5bf457f4 100644
--- a/src/main/daemon/terminal-host-create-contract.ts
+++ b/src/main/daemon/terminal-host-create-contract.ts
@@ -54,4 +54,6 @@ export type CreateOrAttachResult = {
   attachToken: symbol
   incarnationId: PtyIncarnationId
   agentSessionEnsure?: AgentSessionClaimedSpawnResult
+  /** Daemon-process verdict on the spawn cwd; only set on a fresh spawn that was given a cwd. */
+  cwdReadableByDaemon?: boolean
 }
diff --git a/src/main/daemon/terminal-host-cwd-readability.test.ts b/src/main/daemon/terminal-host-cwd-readability.test.ts
new file mode 100644
index 00000000000..aa9e08379d7
--- /dev/null
+++ b/src/main/daemon/terminal-host-cwd-readability.test.ts
@@ -0,0 +1,75 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { SubprocessHandle } from './session-subprocess-handle'
+import { TerminalHost, type TerminalHostOptions } from './terminal-host'
+
+vi.mock('../pty-descendant-termination', () => ({ killWithDescendantSweep: vi.fn() }))
+
+function createMockSubprocess(): SubprocessHandle {
+  let onExitCb: ((code: number) => void) | null = null
+  return {
+    pid: 99999,
+    getForegroundProcess: vi.fn(() => null),
+    write: vi.fn(),
+    resize: vi.fn(),
+    kill: vi.fn(() => {
+      setTimeout(() => onExitCb?.(0), 5)
+    }),
+    terminateOwnedTree: () => 'unavailable' as const,
+    forceKill: vi.fn(() => onExitCb?.(137)),
+    signal: vi.fn(),
+    onData() {},
+    onExit(cb) {
+      onExitCb = cb
+    },
+    dispose: vi.fn()
+  }
+}
+
+// #17696: only the daemon process can say whether TCC lets it read the cwd, so its verdict
+// rides on the create result. A non-permission failure must never read as denial.
+describe('TerminalHost cwd readability verdict', () => {
+  let host: TerminalHost
+  let platformDescriptor: PropertyDescriptor | undefined
+
+  beforeEach(() => {
+    platformDescriptor = Object.getOwnPropertyDescriptor(process, 'platform')
+    Object.defineProperty(process, 'platform', { configurable: true, value: 'linux' })
+    const spawnSubprocess: TerminalHostOptions['spawnSubprocess'] = () => createMockSubprocess()
+    host = new TerminalHost({ spawnSubprocess })
+  })
+
+  afterEach(async () => {
+    await host.dispose()
+    if (platformDescriptor) {
+      Object.defineProperty(process, 'platform', platformDescriptor)
+    }
+  })
+
+  const create = (sessionId: string, cwd?: string) =>
+    host.createOrAttach({
+      sessionId,
+      cols: 80,
+      rows: 24,
+      ...(cwd ? { cwd } : {}),
+      streamClient: { onData: vi.fn(), onExit: vi.fn() }
+    })
+
+  it('reports a readable cwd as readable', async () => {
+    expect((await create('readable', process.cwd())).cwdReadableByDaemon).toBe(true)
+  })
+
+  it('reports a missing cwd as readable — absence is not a permission denial', async () => {
+    expect((await create('missing', '/definitely/not/a/real/dir')).cwdReadableByDaemon).toBe(true)
+  })
+
+  it('omits the verdict when no cwd was requested', async () => {
+    expect((await create('no-cwd')).cwdReadableByDaemon).toBeUndefined()
+  })
+
+  it('omits the verdict on attach to an existing session', async () => {
+    await create('attach', process.cwd())
+    const attached = await create('attach', process.cwd())
+    expect(attached.isNew).toBe(false)
+    expect(attached.cwdReadableByDaemon).toBeUndefined()
+  })
+})
diff --git a/src/main/daemon/terminal-host-session-create.ts b/src/main/daemon/terminal-host-session-create.ts
index e1c8a22e750..9ee51c9968d 100644
--- a/src/main/daemon/terminal-host-session-create.ts
+++ b/src/main/daemon/terminal-host-session-create.ts
@@ -1,3 +1,4 @@
+import { accessSync, constants as fsConstants } from 'node:fs'
 import { buildStartupCommandSubmission } from '../../shared/startup-command-submission'
 import { resolvePtyOwnerBackend } from '../../shared/pty-owner-backend'
 import { getDaemonSessionResultMetadata } from './daemon-create-or-attach-result'
@@ -88,6 +89,8 @@ async function spawnAndPublishSession(
   ctx: { size: { cols: number; rows: number }; wslDistro: string | undefined }
 ): Promise<CreateOrAttachResult> {
   const { size, wslDistro } = ctx
+  // Why before the fork: the shell's own cwd may already have fallen back, so probe the requested path.
+  const cwdReadableByDaemon = opts.cwd && !wslDistro ? isCwdReadableByThisProcess(opts.cwd) : null
   const subprocess = await deps.spawnSubprocess({
     sessionId: opts.sessionId,
     cols: size.cols,
@@ -184,6 +187,20 @@ async function spawnAndPublishSession(
     shellState: session.shellState,
     incarnationId: session.incarnationId,
     ...getDaemonSessionResultMetadata(session),
+    ...(cwdReadableByDaemon !== null ? { cwdReadableByDaemon } : {}),
     attachToken: token
   }
 }
+
+// Why R_OK|X_OK: listing a directory needs read, and entering it needs search — both are what
+// TCC withholds. A non-permission failure (ENOENT, ENOTDIR) reads as readable so it can never
+// masquerade as a permission denial.
+function isCwdReadableByThisProcess(cwd: string): boolean {
+  try {
+    accessSync(cwd, fsConstants.R_OK | fsConstants.X_OK)
+    return true
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code
+    return code !== 'EACCES' && code !== 'EPERM'
+  }
+}
diff --git a/src/main/ipc/telemetry.ts b/src/main/ipc/telemetry.ts
index c1fe7d0f68d..5e649f51b84 100644
--- a/src/main/ipc/telemetry.ts
+++ b/src/main/ipc/telemetry.ts
@@ -24,7 +24,9 @@ let storeRef: Store | null = null
 
 const MAIN_OWNED_TELEMETRY_EVENTS = new Set<EventName>([
   'app_starred_orca',
+  'daemon_adopted',
   'daemon_audit_eligibility',
+  'daemon_pty_cwd_denied',
   'star_nag_outcome',
   'feature_interaction_usage_bucket_reached'
 ])
diff --git a/src/shared/daemon-adoption-telemetry.test.ts b/src/shared/daemon-adoption-telemetry.test.ts
new file mode 100644
index 00000000000..f02aa431506
--- /dev/null
+++ b/src/shared/daemon-adoption-telemetry.test.ts
@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest'
+import { classifyDaemonPtyCwd, classifyDaemonSpawnerPath } from './daemon-adoption-telemetry'
+import { eventSchemas } from './telemetry-event-registry'
+
+describe('classifyDaemonSpawnerPath', () => {
+  const alwaysExists = () => true
+
+  it('classifies the installed app, the ShipIt staging area, and everything else', () => {
+    expect(
+      classifyDaemonSpawnerPath('/Applications/Orca.app/Contents/MacOS/Orca', alwaysExists)
+    ).toBe('applications')
+    expect(
+      classifyDaemonSpawnerPath('/private/Applications/Orca.app/Contents/MacOS/Orca', alwaysExists)
+    ).toBe('applications')
+    expect(
+      classifyDaemonSpawnerPath(
+        '/Users/a/Library/Caches/com.stablyai.orca.ShipIt/update.abc/Orca.app/Contents/MacOS/Orca',
+        alwaysExists
+      )
+    ).toBe('updater-cache')
+    expect(
+      classifyDaemonSpawnerPath('/Users/a/Applications/Orca.app/Contents/MacOS/Orca', alwaysExists)
+    ).toBe('other')
+    expect(classifyDaemonSpawnerPath('/tmp/OrcaA.app/Contents/MacOS/Orca', alwaysExists)).toBe(
+      'other'
+    )
+  })
+
+  it('reports a deleted spawner as missing and an unrecorded one as unknown', () => {
+    expect(
+      classifyDaemonSpawnerPath('/Applications/Orca.app/Contents/MacOS/Orca', () => false)
+    ).toBe('missing')
+    expect(classifyDaemonSpawnerPath(null, alwaysExists)).toBe('unknown')
+  })
+})
+
+describe('classifyDaemonPtyCwd', () => {
+  it('maps the TCC-protected home folders and separates the rest of home from outside it', () => {
+    expect(classifyDaemonPtyCwd('/Users/a/Documents/repo', '/Users/a')).toBe('documents')
+    expect(classifyDaemonPtyCwd('/Users/a/Desktop', '/Users/a/')).toBe('desktop')
+    expect(classifyDaemonPtyCwd('/Users/a/Downloads/x/y', '/Users/a')).toBe('downloads')
+    expect(classifyDaemonPtyCwd('/Users/a/projects/repo', '/Users/a')).toBe('other-home')
+    expect(classifyDaemonPtyCwd('/Users/a', '/Users/a')).toBe('other-home')
+    expect(classifyDaemonPtyCwd('/Volumes/ext/repo', '/Users/a')).toBe('outside-home')
+    // A sibling home that merely shares the prefix is not inside this home.
+    expect(classifyDaemonPtyCwd('/Users/ab/Documents', '/Users/a')).toBe('outside-home')
+  })
+})
+
+// Privacy invariant: enum-only. A raw path, version, or exact count must be rejected by .strict().
+describe('daemon_adopted / daemon_pty_cwd_denied schemas', () => {
+  const adopted = {
+    app_version_match: 'different',
+    spawner_path_class: 'updater-cache',
+    tcc_attribution: 'intact',
+    live_session_count_bucket: '2-5'
+  }
+  const denied = {
+    cwd_class: 'documents',
+    app_version_match: 'different',
+    spawner_path_class: 'updater-cache'
+  }
+
+  it('accepts the enum payloads', () => {
+    expect(eventSchemas.daemon_adopted.safeParse(adopted).success).toBe(true)
+    expect(eventSchemas.daemon_pty_cwd_denied.safeParse(denied).success).toBe(true)
+  })
+
+  it('rejects leaked paths, versions, counts, and unknown enum values', () => {
+    for (const leak of [
+      { spawner_exec_path: '/Users/alice/Library/Caches/ShipIt/Orca.app' },
+      { app_version: '1.4.187' },
+      { live_session_count: 3 },
+      { cwd: '/Users/alice/Documents' }
+    ]) {
+      expect(eventSchemas.daemon_adopted.safeParse({ ...adopted, ...leak }).success).toBe(false)
+      expect(eventSchemas.daemon_pty_cwd_denied.safeParse({ ...denied, ...leak }).success).toBe(
+        false
+      )
+    }
+    expect(
+      eventSchemas.daemon_adopted.safeParse({ ...adopted, spawner_path_class: '/Applications' })
+        .success
+    ).toBe(false)
+    expect(
+      eventSchemas.daemon_pty_cwd_denied.safeParse({ ...denied, cwd_class: 'Documents' }).success
+    ).toBe(false)
+  })
+})
diff --git a/src/shared/daemon-adoption-telemetry.ts b/src/shared/daemon-adoption-telemetry.ts
new file mode 100644
index 00000000000..72c21647cd3
--- /dev/null
+++ b/src/shared/daemon-adoption-telemetry.ts
@@ -0,0 +1,67 @@
+// Enums for the `daemon_adopted` and `daemon_pty_cwd_denied` telemetry events (#17696).
+// Both exist to measure how often a macOS app runs on a daemon left behind by an earlier app
+// bundle, and how often such a daemon actually spawns a terminal whose cwd it cannot read.
+// Enum-only: no paths, versions, or exact counts ever reach the wire.
+
+/** How the adopted daemon's recorded app version compares to the running app. */
+export const DAEMON_ADOPTED_APP_VERSION_MATCH = ['same', 'different', 'unknown'] as const
+export type DaemonAdoptedAppVersionMatch = (typeof DAEMON_ADOPTED_APP_VERSION_MATCH)[number]
+
+/**
+ * Where the binary that forked the adopted daemon lives now. `updater-cache` is the Squirrel
+ * ShipIt staging area — a daemon attributed there is the reported #17696 shape.
+ */
+export const DAEMON_SPAWNER_PATH_CLASSES = [
+  'applications',
+  'updater-cache',
+  'other',
+  'missing',
+  'unknown'
+] as const
+export type DaemonSpawnerPathClass = (typeof DAEMON_SPAWNER_PATH_CLASSES)[number]
+
+export const DAEMON_TCC_ATTRIBUTION_VALUES = ['intact', 'severed', 'unknown'] as const
+
+/** Which macOS-protected folder class the denied cwd falls under. */
+export const DAEMON_PTY_CWD_CLASSES = [
+  'documents',
+  'desktop',
+  'downloads',
+  'other-home',
+  'outside-home'
+] as const
+export type DaemonPtyCwdClass = (typeof DAEMON_PTY_CWD_CLASSES)[number]
+
+export function classifyDaemonSpawnerPath(
+  spawnerExecPath: string | null,
+  exists: (path: string) => boolean
+): DaemonSpawnerPathClass {
+  if (!spawnerExecPath) {
+    return 'unknown'
+  }
+  if (!exists(spawnerExecPath)) {
+    return 'missing'
+  }
+  if (/\/Library\/Caches\/[^/]*ShipIt\//.test(spawnerExecPath)) {
+    return 'updater-cache'
+  }
+  return /^(?:\/private)?\/Applications\//.test(spawnerExecPath) ? 'applications' : 'other'
+}
+
+export function classifyDaemonPtyCwd(cwd: string, homeDir: string): DaemonPtyCwdClass {
+  const home = homeDir.replace(/\/+$/, '')
+  if (!home || !(cwd === home || cwd.startsWith(`${home}/`))) {
+    return 'outside-home'
+  }
+  const topLevel = cwd.slice(home.length + 1).split('/')[0]
+  switch (topLevel) {
+    case 'Documents':
+      return 'documents'
+    case 'Desktop':
+      return 'desktop'
+    case 'Downloads':
+      return 'downloads'
+    default:
+      return 'other-home'
+  }
+}
diff --git a/src/shared/telemetry-daemon-event-schemas.ts b/src/shared/telemetry-daemon-event-schemas.ts
index a0543d4d49b..c6b2795a333 100644
--- a/src/shared/telemetry-daemon-event-schemas.ts
+++ b/src/shared/telemetry-daemon-event-schemas.ts
@@ -14,6 +14,12 @@ import {
   DAEMON_AUDIT_TRIGGER_VALUES,
   DAEMON_EVIDENCE_SOURCE_VALUES
 } from './daemon-audit-eligibility'
+import {
+  DAEMON_ADOPTED_APP_VERSION_MATCH,
+  DAEMON_PTY_CWD_CLASSES,
+  DAEMON_SPAWNER_PATH_CLASSES,
+  DAEMON_TCC_ATTRIBUTION_VALUES
+} from './daemon-adoption-telemetry'
 import { errorClassSchema, settingsChangedKeySchema } from './telemetry-property-schemas'
 
 // Why: daemon start-failure signal (fleet-wide outage like v1.4.129-rc.1); enum-only so raw stderr never reaches the wire.
@@ -50,6 +56,27 @@ export const mainThreadHangDetectedSchema = z
   })
   .strict()
 
+// Why: #17696 — a macOS app adopting a daemon from an earlier bundle is invisible to
+// `daemon_lifecycle` (nothing is replaced). Once per macOS launch that adopts; enum-only.
+export const daemonAdoptedSchema = z
+  .object({
+    app_version_match: z.enum(DAEMON_ADOPTED_APP_VERSION_MATCH),
+    spawner_path_class: z.enum(DAEMON_SPAWNER_PATH_CLASSES),
+    tcc_attribution: z.enum(DAEMON_TCC_ATTRIBUTION_VALUES),
+    live_session_count_bucket: z.enum(DAEMON_LIFECYCLE_SESSION_BUCKETS)
+  })
+  .strict()
+
+// Why: the #17696 symptom itself — the daemon spawned a terminal into a cwd it cannot read while
+// the app can. Emitted only on that proven divergence, so a missing or app-unreadable cwd never counts.
+export const daemonPtyCwdDeniedSchema = z
+  .object({
+    cwd_class: z.enum(DAEMON_PTY_CWD_CLASSES),
+    app_version_match: z.enum(DAEMON_ADOPTED_APP_VERSION_MATCH),
+    spawner_path_class: z.enum(DAEMON_SPAWNER_PATH_CLASSES)
+  })
+  .strict()
+
 // Why: daemon replace/retire lifecycle signal — issue #7936 was undiagnosable without asking a user for daemon.log.
 // Enum-only + bucketed session count so no paths, raw versions, or exact counts reach the wire.
 // The union keeps each reason pinned to its transition, so a death can't be reported as a replace.
diff --git a/src/shared/telemetry-event-registry.ts b/src/shared/telemetry-event-registry.ts
index 29479f363cb..5a91640359a 100644
--- a/src/shared/telemetry-event-registry.ts
+++ b/src/shared/telemetry-event-registry.ts
@@ -14,8 +14,10 @@ import {
   agentHookTransportBlockedSchema,
   agentHookUnattributedSchema,
   codexTrustGrantSchema,
+  daemonAdoptedSchema,
   daemonAuditEligibilitySchema,
   daemonLifecycleSchema,
+  daemonPtyCwdDeniedSchema,
   daemonStartFailedSchema,
   mainThreadHangDetectedSchema,
   remoteOutboundBudgetCloseSchema,
@@ -122,6 +124,8 @@ export const eventSchemas = {
   daemon_start_failed: daemonStartFailedSchema,
   main_thread_hang_detected: mainThreadHangDetectedSchema,
   daemon_lifecycle: daemonLifecycleSchema,
+  daemon_adopted: daemonAdoptedSchema,
+  daemon_pty_cwd_denied: daemonPtyCwdDeniedSchema,
   daemon_audit_eligibility: daemonAuditEligibilitySchema,
   runtime_rpc_start_failed: runtimeRpcStartFailedSchema,
   remote_outbound_budget_close: remoteOutboundBudgetCloseSchema,

From 7f6cf271ceedb0030c280eae4db4458bdd892c28 Mon Sep 17 00:00:00 2001
From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com>
Date: Tue, 1 Sep 2026 19:53:11 -0700
Subject: [PATCH 27/32] fix(terminal): preserve panes when restored PTY owner
 is unverifiable (#17860)

* fix(terminal): preserve unverifiable restored pane bindings

* test(terminal): cover unverifiable restored pane identity

* fix(terminal): settle direct SSH retry on unverifiable owner

* fix(terminal): make owner warning actionable

* fix(terminal): harden owner warning recovery feedback

* test(terminal): consolidate fixture imports

---------

Co-authored-by: Merge Sim <sim@local>
---
 .../terminal-pane/TerminalErrorToast.test.ts  | 84 ++++++++++++++++-
 .../terminal-pane/TerminalErrorToast.tsx      | 84 ++++++++++++++---
 .../terminal-pane/TerminalPaneSurface.tsx     | 22 ++++-
 ...-connection-direct-ssh-spawn-retry.test.ts | 92 ++++++++++++++++++-
 .../pty-connection-session-liveness.test.ts   | 65 +++++++++++++
 .../deferred-session-reattach-connect.ts      | 20 ++++
 src/renderer/src/i18n/locales/en.json         |  6 +-
 7 files changed, 354 insertions(+), 19 deletions(-)

diff --git a/src/renderer/src/components/terminal-pane/TerminalErrorToast.test.ts b/src/renderer/src/components/terminal-pane/TerminalErrorToast.test.ts
index 069ed371ec0..220f968cd98 100644
--- a/src/renderer/src/components/terminal-pane/TerminalErrorToast.test.ts
+++ b/src/renderer/src/components/terminal-pane/TerminalErrorToast.test.ts
@@ -1,7 +1,7 @@
 // @vitest-environment happy-dom
 
 import React from 'react'
-import { cleanup, render, waitFor } from '@testing-library/react'
+import { cleanup, fireEvent, render, waitFor } from '@testing-library/react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 const environmentMocks = vi.hoisted(() => ({
@@ -15,6 +15,7 @@ vi.mock('@/lib/client-environment-info', () => ({
 import {
   TerminalErrorToast,
   humanizeTerminalError,
+  isPaneOwnerUnverifiedError,
   isExplainedTerminalError,
   isSshReconnectOwnedTerminalError,
   shouldOfferDaemonRestart,
@@ -69,7 +70,15 @@ describe('humanizeTerminalError', () => {
   it('replaces the pane-owner-unverified code with actionable copy', () => {
     const humanized = humanizeTerminalError('terminal_pane_owner_unverified')
     expect(humanized).not.toContain('terminal_pane_owner_unverified')
-    expect(humanized).toContain('Reopen this pane to retry')
+    expect(humanized).toContain('Click Retry to try reconnecting now')
+    expect(humanized).toContain('Orca left the saved session unchanged')
+    expect(humanized).not.toContain('was not closed or deleted')
+  })
+
+  it('identifies the owner-unverified safety state', () => {
+    expect(isPaneOwnerUnverifiedError('terminal_pane_owner_unverified')).toBe(true)
+    expect(isPaneOwnerUnverifiedError('Paste failed.')).toBe(false)
+    expect(isPaneOwnerUnverifiedError('Paste failed.\nterminal_pane_owner_unverified')).toBe(false)
   })
 
   it('humanizes an IPC-wrapped pane-owner-unverified error', () => {
@@ -78,6 +87,22 @@ describe('humanizeTerminalError', () => {
     expect(humanizeTerminalError(wrapped)).not.toContain('terminal_pane_owner_unverified')
   })
 
+  it('humanizes an owner marker without classifying mixed errors as safe warnings', () => {
+    const mixed = humanizeTerminalError('Paste failed.\nterminal_pane_owner_unverified')
+    expect(mixed).toContain('Paste failed.')
+    expect(mixed).toContain("Orca couldn't verify this terminal's owner.")
+    expect(mixed).not.toContain('terminal_pane_owner_unverified')
+    expect(isPaneOwnerUnverifiedError('Paste failed.\nterminal_pane_owner_unverified')).toBe(false)
+  })
+
+  it('humanizes every owner marker in an aggregated warning', () => {
+    const repeated = humanizeTerminalError(
+      "terminal_pane_owner_unverified\nError invoking remote method 'pty:spawn': Error: terminal_pane_owner_unverified"
+    )
+
+    expect(repeated).not.toContain('terminal_pane_owner_unverified')
+  })
+
   it('leaves other errors untouched', () => {
     expect(humanizeTerminalError('Paste failed.')).toBe('Paste failed.')
   })
@@ -302,4 +327,59 @@ describe('TerminalErrorToast environment footer', () => {
 
     await waitFor(() => expect(environmentMocks.resolveFooter).not.toHaveBeenCalled())
   })
+
+  it('renders owner-unverified as a warning without an issue link', () => {
+    const onRetry = vi.fn().mockResolvedValue(true)
+    const view = render(
+      React.createElement(TerminalErrorToast, {
+        error: 'terminal_pane_owner_unverified',
+        onDismiss: vi.fn(),
+        onRetry
+      })
+    )
+
+    const toast = view.container.querySelector('[data-terminal-error-toast]')
+    expect(toast?.getAttribute('data-terminal-error-kind')).toBe('owner-unverified')
+    expect(toast?.querySelector('a')).toBeNull()
+    expect(toast?.textContent).toContain('Orca left the saved session unchanged')
+    expect(view.getByRole('button', { name: 'Retry' }).getAttribute('data-slot')).toBe('button')
+    fireEvent.click(view.getByRole('button', { name: 'Retry' }))
+    expect(onRetry).toHaveBeenCalledTimes(1)
+  })
+
+  it('keeps Retry available when the recovery attempt rejects', async () => {
+    const onRetry = vi.fn().mockRejectedValue(new Error('recovery unavailable'))
+    const view = render(
+      React.createElement(TerminalErrorToast, {
+        error: 'terminal_pane_owner_unverified',
+        onDismiss: vi.fn(),
+        onRetry
+      })
+    )
+
+    fireEvent.click(view.getByRole('button', { name: 'Retry' }))
+
+    await waitFor(() =>
+      expect((view.getByRole('button', { name: 'Retry' }) as HTMLButtonElement).disabled).toBe(
+        false
+      )
+    )
+    expect(onRetry).toHaveBeenCalledTimes(1)
+  })
+
+  it('explains when Retry is temporarily unavailable', async () => {
+    const onRetry = vi.fn().mockResolvedValue(false)
+    const view = render(
+      React.createElement(TerminalErrorToast, {
+        error: 'terminal_pane_owner_unverified',
+        onDismiss: vi.fn(),
+        onRetry
+      })
+    )
+
+    fireEvent.click(view.getByRole('button', { name: 'Retry' }))
+    await waitFor(() =>
+      expect(view.container.textContent).toContain('Retry could not reconnect yet')
+    )
+  })
 })
diff --git a/src/renderer/src/components/terminal-pane/TerminalErrorToast.tsx b/src/renderer/src/components/terminal-pane/TerminalErrorToast.tsx
index ee876ae719e..2ba98a180d6 100644
--- a/src/renderer/src/components/terminal-pane/TerminalErrorToast.tsx
+++ b/src/renderer/src/components/terminal-pane/TerminalErrorToast.tsx
@@ -1,6 +1,7 @@
 import { useEffect, useState } from 'react'
 import { translate } from '@/i18n/i18n'
 import { resolveClientEnvironmentFooter } from '@/lib/client-environment-info'
+import { Button } from '@/components/ui/button'
 import { hasClientEnvironmentFooter } from '../../../../shared/client-environment-info'
 
 const SSH_PREFIX = 'SSH connection is not active'
@@ -78,6 +79,11 @@ export function isExplainedTerminalError(error: string): boolean {
     )
 }
 
+export function isPaneOwnerUnverifiedError(error: string): boolean {
+  const lines = error.split('\n').filter((line) => line.length > 0)
+  return lines.length > 0 && lines.every((line) => line.includes(PANE_OWNER_UNVERIFIED_MARKER))
+}
+
 function humanizeUnreattachableSession(error: string): string {
   const explanation = translate(
     'auto.components.terminal.pane.TerminalErrorToast.sessionUnavailable',
@@ -94,13 +100,16 @@ function humanizeUnreattachableSession(error: string): string {
 export function humanizeTerminalError(error: string): string {
   let humanized = error
   if (humanized.includes(PANE_OWNER_UNVERIFIED_MARKER)) {
-    humanized = humanized.replace(
-      PANE_OWNER_UNVERIFIED_MARKER,
-      translate(
-        'auto.components.terminal.pane.TerminalErrorToast.7ee11bc0db',
-        "Orca couldn't confirm whether this terminal's previous session is still running, so it left the session untouched. Reopen this pane to retry."
-      )
-    )
+    const explanation = isPaneOwnerUnverifiedError(humanized)
+      ? translate(
+          'auto.components.terminal.pane.TerminalErrorToast.42b283ecfc',
+          "Orca couldn't safely reconnect this terminal because the host couldn't verify its saved session. Orca left the saved session unchanged. Click Retry to try reconnecting now. If it still cannot reconnect, open a new terminal."
+        )
+      : translate(
+          'auto.components.terminal.pane.TerminalErrorToast.ownerUnknown',
+          "Orca couldn't verify this terminal's owner."
+        )
+    humanized = humanized.replaceAll(PANE_OWNER_UNVERIFIED_MARKER, () => explanation)
   }
   humanized = humanizeUnreattachableSession(humanized)
   if (!isExplainedTerminalError(humanized)) {
@@ -127,17 +136,23 @@ export function humanizeTerminalError(error: string): string {
 export function TerminalErrorToast({
   error,
   onDismiss,
-  onRestartDaemon
+  onRestartDaemon,
+  onRetry
 }: {
   error: string
   onDismiss: () => void
   onRestartDaemon?: () => void
+  onRetry?: () => Promise<boolean>
 }): React.JSX.Element {
   const ssh = isSshError(error)
+  const paneOwnerUnverified = isPaneOwnerUnverifiedError(error)
   const showDaemonRestart = !ssh && onRestartDaemon && shouldOfferDaemonRestart(error)
   // Restart cannot recover a session after its owning daemon exits.
-  const showIssueLink = !ssh && !showDaemonRestart && !isExplainedTerminalError(error)
+  const showIssueLink =
+    !ssh && !paneOwnerUnverified && !showDaemonRestart && !isExplainedTerminalError(error)
   const displayError = humanizeTerminalError(error)
+  const [retrying, setRetrying] = useState(false)
+  const [retryFailed, setRetryFailed] = useState(false)
   const [environmentFooter, setEnvironmentFooter] = useState<{
     error: string
     footer: string
@@ -160,10 +175,26 @@ export function TerminalErrorToast({
   }, [displayError, ssh])
 
   const footer = environmentFooter?.error === displayError ? environmentFooter.footer : ''
+  const handleRetry = async (): Promise<void> => {
+    if (!onRetry || retrying) {
+      return
+    }
+    setRetrying(true)
+    setRetryFailed(false)
+    try {
+      setRetryFailed(!(await onRetry()))
+    } catch {
+      // Keep the safety warning available when a best-effort remount cannot start.
+      setRetryFailed(true)
+    } finally {
+      setRetrying(false)
+    }
+  }
 
   return (
     <div
       data-terminal-error-toast
+      data-terminal-error-kind={paneOwnerUnverified ? 'owner-unverified' : ssh ? 'ssh' : 'error'}
       style={{
         position: 'absolute',
         bottom: 12,
@@ -172,9 +203,17 @@ export function TerminalErrorToast({
         zIndex: 50,
         padding: '10px 14px',
         borderRadius: 6,
-        background: ssh ? 'rgba(234, 179, 8, 0.12)' : 'rgba(220, 38, 38, 0.15)',
-        border: ssh ? '1px solid rgba(234, 179, 8, 0.35)' : '1px solid rgba(220, 38, 38, 0.4)',
-        color: ssh ? '#fde68a' : '#fca5a5',
+        background: paneOwnerUnverified
+          ? 'var(--popover)'
+          : ssh
+            ? 'rgba(234, 179, 8, 0.12)'
+            : 'rgba(220, 38, 38, 0.15)',
+        border: paneOwnerUnverified
+          ? '1px solid var(--color-amber-500)'
+          : ssh
+            ? '1px solid rgba(234, 179, 8, 0.35)'
+            : '1px solid rgba(220, 38, 38, 0.4)',
+        color: paneOwnerUnverified ? 'var(--popover-foreground)' : ssh ? '#fde68a' : '#fca5a5',
         fontSize: 12,
         fontFamily: 'monospace',
         whiteSpace: 'pre-wrap',
@@ -212,6 +251,12 @@ export function TerminalErrorToast({
             </>
           ) : null}
           {!ssh && footer ? `\n\n${footer}` : null}
+          {paneOwnerUnverified && retryFailed
+            ? `\n${translate(
+                'auto.components.terminal.pane.TerminalErrorToast.retryUnavailable',
+                'Retry could not reconnect yet. Try again shortly.'
+              )}`
+            : null}
         </span>
         {showDaemonRestart ? (
           <button
@@ -235,12 +280,25 @@ export function TerminalErrorToast({
             )}
           </button>
         ) : null}
+        {paneOwnerUnverified && onRetry ? (
+          <Button
+            variant="outline"
+            size="xs"
+            onClick={() => void handleRetry()}
+            disabled={retrying}
+            className="ml-3 border-amber-500/50 bg-popover text-popover-foreground hover:bg-amber-500/20"
+          >
+            {retrying
+              ? translate('auto.components.terminal.pane.TerminalErrorToast.retrying', 'Retrying…')
+              : translate('auto.components.terminal.pane.TerminalErrorToast.retry', 'Retry')}
+          </Button>
+        ) : null}
         <button
           onClick={onDismiss}
           style={{
             background: 'none',
             border: 'none',
-            color: ssh ? '#fde68a' : '#fca5a5',
+            color: paneOwnerUnverified ? 'var(--popover-foreground)' : ssh ? '#fde68a' : '#fca5a5',
             cursor: 'pointer',
             fontSize: 14,
             padding: '0 0 0 8px',
diff --git a/src/renderer/src/components/terminal-pane/TerminalPaneSurface.tsx b/src/renderer/src/components/terminal-pane/TerminalPaneSurface.tsx
index 972cbe9c3fc..fff316dabce 100644
--- a/src/renderer/src/components/terminal-pane/TerminalPaneSurface.tsx
+++ b/src/renderer/src/components/terminal-pane/TerminalPaneSurface.tsx
@@ -6,7 +6,8 @@ import { WORKSPACE_FILE_PATH_MIME, WORKSPACE_FILE_PATHS_MIME } from '@/lib/works
 import CloseTerminalDialog from './CloseTerminalDialog'
 import TerminalContextMenu from './TerminalContextMenu'
 import TerminalPaneHeaderOverlay from './TerminalPaneHeaderOverlay'
-import { TerminalErrorToast } from './TerminalErrorToast'
+import { isPaneOwnerUnverifiedError, TerminalErrorToast } from './TerminalErrorToast'
+import { requestTerminalPaneRecovery } from './terminal-pane-recovery'
 import { TerminalSessionStateSaveFailureDialog } from './TerminalSessionStateSaveFailureDialog'
 import { TerminalLinkActionPopover } from './TerminalLinkActionPopover'
 import { TerminalAgentSessionForkDialog } from './TerminalAgentSessionForkDialog'
@@ -157,6 +158,25 @@ export function TerminalPaneSurface({
               error={visibleTerminalError}
               onDismiss={dismissTerminalError}
               onRestartDaemon={() => daemonActions.setPending('restart')}
+              onRetry={
+                isPaneOwnerUnverifiedError(visibleTerminalError)
+                  ? () => {
+                      const ptyId = activePane
+                        ? (paneTransportsRef.current.get(activePane.id)?.getPtyId() ?? null)
+                        : null
+                      return requestTerminalPaneRecovery({
+                        tabId,
+                        ptyId,
+                        reason: 'reattach-unverifiable'
+                      }).then((recovered) => {
+                        if (recovered) {
+                          dismissTerminalError()
+                        }
+                        return recovered
+                      })
+                    }
+                  : undefined
+              }
             />,
             activePane.container,
             `terminal-error-${activePane.id}`
diff --git a/src/renderer/src/components/terminal-pane/pty-connection-direct-ssh-spawn-retry.test.ts b/src/renderer/src/components/terminal-pane/pty-connection-direct-ssh-spawn-retry.test.ts
index 410f8afac54..298d15d3eeb 100644
--- a/src/renderer/src/components/terminal-pane/pty-connection-direct-ssh-spawn-retry.test.ts
+++ b/src/renderer/src/components/terminal-pane/pty-connection-direct-ssh-spawn-retry.test.ts
@@ -2,7 +2,14 @@ import type * as React from 'react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { toAppSshPtyId } from '../../../../shared/ssh-pty-id'
 import { flushAsyncTicks, createDeferred } from './pty-connection-test-async'
-import { createMockTransport, createPane, createManager } from './pty-connection-test-pane-fixtures'
+import {
+  createMockTransport,
+  createPane,
+  createManager,
+  LEAF_2,
+  type ConnectCallbacks,
+  type MockTransport
+} from './pty-connection-test-pane-fixtures'
 import { buildPaneConnectionDeps, buildDirectSshSplitRetryCommit } from './pty-connection-test-deps'
 import { createInitialStoreState } from './pty-connection-test-store-fixtures'
 import type { StoreState } from './pty-connection-test-store-state'
@@ -10,7 +17,6 @@ import {
   pendingSpawnByPaneKey,
   pendingSpawnGenerationByPaneKey
 } from './pty-connection/pty-connect-limits'
-import type { MockTransport } from './pty-connection-test-pane-fixtures'
 import {
   installTerminalTestGlobals,
   restoreTerminalTestGlobals
@@ -665,6 +671,88 @@ describe('connectPanePty', () => {
     await flushAsyncTicks(12)
   })
 
+  it('rejects an owner-unverified reattach after direct SSH authority rotates', async () => {
+    const { connectPanePty } = await import('./pty-connection')
+    const restoredPtyId = toAppSshPtyId('target-a', 'pty-live')
+    const delayedReattach = createDeferred<void>()
+    const capturedCallbacks: { current: ConnectCallbacks | null } = { current: null }
+    const transport = createMockTransport(restoredPtyId)
+    transport.detach = vi.fn()
+    transport.connect.mockImplementation(({ callbacks }) => {
+      capturedCallbacks.current = callbacks ?? null
+      return delayedReattach.promise
+    })
+    transportFactoryQueue.push(transport)
+    const liveRetry = {
+      attemptId: 'attempt-live-owner-unverified',
+      authority: {
+        targetId: 'target-a',
+        providerEpoch: 'epoch-old',
+        connectionGeneration: 3
+      },
+      tabGeneration: 7,
+      ptyId: restoredPtyId
+    }
+    const settleDirectSshPaneRetry = vi.fn()
+    mockStoreState = {
+      ...mockStoreState,
+      tabsByWorktree: { 'wt-1': [{ id: 'tab-1', ptyId: restoredPtyId, generation: 7 }] },
+      ptyIdsByTabId: { 'tab-1': [restoredPtyId] },
+      terminalLayoutsByTabId: {
+        'tab-1': {
+          root: { type: 'leaf', leafId: LEAF_2 },
+          activeLeafId: LEAF_2,
+          expandedLeafId: null,
+          ptyIdsByLeafId: { [LEAF_2]: restoredPtyId }
+        }
+      },
+      repos: [{ id: 'repo1', connectionId: 'target-a', displayName: 'orca' }],
+      sshConnectionStates: new Map([
+        [
+          'target-a',
+          {
+            targetId: 'target-a',
+            status: 'connected',
+            providerEpoch: 'epoch-old',
+            connectionGeneration: 3
+          }
+        ]
+      ]),
+      directSshPaneRetryByTabId: {},
+      directSshLivePtyBindingByTabId: { 'tab-1': liveRetry },
+      settleDirectSshPaneRetry
+    }
+    const deps = createDeps({
+      restoredLeafId: LEAF_2,
+      restoredPtyIdByLeafId: { [LEAF_2]: restoredPtyId }
+    })
+
+    connectPanePty(createPane(2) as never, createManager(2) as never, deps as never)
+    await flushAsyncTicks()
+    mockStoreState.sshConnectionStates = new Map([
+      [
+        'target-a',
+        {
+          targetId: 'target-a',
+          status: 'connected',
+          providerEpoch: 'epoch-new',
+          connectionGeneration: 4
+        }
+      ]
+    ])
+
+    capturedCallbacks.current?.onError?.('terminal_pane_owner_unverified')
+    delayedReattach.resolve()
+    await flushAsyncTicks(12)
+
+    expect(deps.onPtyErrorRef.current).not.toHaveBeenCalled()
+    expect(transport.detach).toHaveBeenCalledExactlyOnceWith({ preserveExitObserver: false })
+    expect(settleDirectSshPaneRetry).not.toHaveBeenCalled()
+    expect(mockStoreState.terminalLayoutsByTabId?.['tab-1']?.ptyIdsByLeafId).toEqual({
+      [LEAF_2]: restoredPtyId
+    })
+  })
+
   it('starts a new spawn and rejects a late callback after direct SSH authority rotates', async () => {
     const { connectPanePty } = await import('./pty-connection')
     const oldPendingSpawn = createDeferred<string>()
diff --git a/src/renderer/src/components/terminal-pane/pty-connection-session-liveness.test.ts b/src/renderer/src/components/terminal-pane/pty-connection-session-liveness.test.ts
index becdb891be2..e86da5509c8 100644
--- a/src/renderer/src/components/terminal-pane/pty-connection-session-liveness.test.ts
+++ b/src/renderer/src/components/terminal-pane/pty-connection-session-liveness.test.ts
@@ -132,6 +132,26 @@ function createDeps(overrides: Record<string, unknown> = {}) {
   return buildPaneConnectionDeps(() => mockStoreState, overrides)
 }
 
+function seedUnverifiableRestoredPane() {
+  mockStoreState = {
+    ...mockStoreState,
+    tabsByWorktree: { 'wt-1': [{ id: 'tab-1', ptyId: 'unverifiable-pty' }] },
+    ptyIdsByTabId: { 'tab-1': ['unverifiable-pty'] },
+    terminalLayoutsByTabId: {
+      'tab-1': {
+        root: { type: 'leaf', leafId: LEAF_2 },
+        activeLeafId: LEAF_2,
+        expandedLeafId: null,
+        ptyIdsByLeafId: { [LEAF_2]: 'unverifiable-pty' }
+      }
+    }
+  } as StoreState
+  return createDeps({
+    restoredLeafId: LEAF_2,
+    restoredPtyIdByLeafId: { [LEAF_2]: 'unverifiable-pty' }
+  })
+}
+
 // Why: activeRuntimeEnvironmentId exercises the remote-runtime path where the renderer still owns OSC 9999 status.
 function enableActiveRuntimeEnvironment(environmentId = 'env-1'): void {
   mockStoreState = buildActiveRuntimeEnvironmentState(mockStoreState, environmentId)
@@ -548,6 +568,51 @@ describe('connectPanePty', () => {
     })
   })
 
+  it('preserves an owner-unverified restored pane after an empty reattach result', async () => {
+    const { connectPanePty } = await import('./pty-connection')
+    const transport = createMockTransport()
+    transport.connect.mockImplementation(async (opts: { callbacks?: ConnectCallbacks }) => {
+      opts.callbacks?.onError?.('terminal_pane_owner_unverified')
+      return undefined
+    })
+    transportFactoryQueue.push(transport)
+    const deps = seedUnverifiableRestoredPane()
+
+    connectPanePty(createPane(2) as never, createManager(2) as never, deps as never)
+    await flushAsyncTicks()
+
+    expect(transport.connect).toHaveBeenCalledTimes(1)
+    expect(deps.onPtyErrorRef.current).toHaveBeenCalledWith(2, 'terminal_pane_owner_unverified')
+    expect(deps.clearExitedPanePtyLayoutBinding).not.toHaveBeenCalled()
+    expect(deps.clearTabPtyId).not.toHaveBeenCalled()
+    expect(mockStoreState.tabsByWorktree['wt-1'][0]?.ptyId).toBe('unverifiable-pty')
+    expect(mockStoreState.ptyIdsByTabId?.['tab-1']).toEqual(['unverifiable-pty'])
+    expect(mockStoreState.terminalLayoutsByTabId?.['tab-1']?.ptyIdsByLeafId).toEqual({
+      [LEAF_2]: 'unverifiable-pty'
+    })
+    expect(window.api.pty.clearPendingPaneSerializer).toHaveBeenCalledWith(expect.any(String), 1)
+  })
+
+  it('preserves an owner-unverified restored pane after a rejected reattach', async () => {
+    const { connectPanePty } = await import('./pty-connection')
+    const transport = createMockTransport()
+    transport.connect.mockRejectedValueOnce(new Error('terminal_pane_owner_unverified'))
+    transportFactoryQueue.push(transport)
+    const deps = seedUnverifiableRestoredPane()
+
+    connectPanePty(createPane(2) as never, createManager(2) as never, deps as never)
+    await flushAsyncTicks()
+
+    expect(transport.connect).toHaveBeenCalledTimes(1)
+    expect(deps.onPtyErrorRef.current).toHaveBeenCalledWith(2, 'terminal_pane_owner_unverified')
+    expect(deps.clearExitedPanePtyLayoutBinding).not.toHaveBeenCalled()
+    expect(deps.clearTabPtyId).not.toHaveBeenCalled()
+    expect(mockStoreState.terminalLayoutsByTabId?.['tab-1']?.ptyIdsByLeafId).toEqual({
+      [LEAF_2]: 'unverifiable-pty'
+    })
+    expect(window.api.pty.clearPendingPaneSerializer).toHaveBeenCalledWith(expect.any(String), 1)
+  })
+
   describe('terminal input liveness IPC gating (perf)', () => {
     // Why (perf regression guard): listSessions() is a renderer→main→daemon round-trip; terminal input must never trigger it.
     async function connectActivePaneWithInput(): Promise<{
diff --git a/src/renderer/src/components/terminal-pane/pty-connection/deferred-session-reattach-connect.ts b/src/renderer/src/components/terminal-pane/pty-connection/deferred-session-reattach-connect.ts
index 91753d3f5f7..da71fe10962 100644
--- a/src/renderer/src/components/terminal-pane/pty-connection/deferred-session-reattach-connect.ts
+++ b/src/renderer/src/components/terminal-pane/pty-connection/deferred-session-reattach-connect.ts
@@ -6,6 +6,8 @@ import { toProcessExitStartup } from './process-exit-startup'
 import { recoverUnverifiableDirectSshReattach } from './direct-ssh-reattach-recovery'
 import type { ConnectPanePtySession } from './connect-pane-pty-session'
 
+const PANE_OWNER_UNVERIFIED_ERROR = 'terminal_pane_owner_unverified'
+
 export function startDeferredSessionReattach(
   session: ConnectPanePtySession,
   deferredReattachSessionId: string
@@ -22,6 +24,7 @@ export function startDeferredSessionReattach(
       : window.api.pty.declarePendingPaneSerializer(session.cacheKey).catch(() => null)
 
   let expiredReattachError = false
+  let paneOwnerUnverified = false
   const coldRestoreStartup = session.buildColdRestoreAgentResumeStartup()
   const outputCallbacks = session.captureTransportOutputCallbacks(
     (message) => {
@@ -29,6 +32,9 @@ export function startDeferredSessionReattach(
         expiredReattachError = true
         return
       }
+      if (message.includes(PANE_OWNER_UNVERIFIED_ERROR)) {
+        paneOwnerUnverified = true
+      }
       if (!session.isCapturedDirectSshReattachCurrent(deferredReattachSessionId)) {
         return
       }
@@ -79,6 +85,15 @@ export function startDeferredSessionReattach(
         }
         return
       }
+      if (!result && paneOwnerUnverified) {
+        session.finishReattachLiveDataDeferral(false, outputCallbacks.generation)
+        const gen = await preSignalPromise
+        if (typeof gen === 'number') {
+          void window.api.pty.clearPendingPaneSerializer(session.cacheKey, gen).catch(() => {})
+        }
+        session.settleDirectSshPaneRetryAttempt(session.directSshRetryAttempt, 'failed')
+        return
+      }
       if (!result && expiredReattachError) {
         session.finishReattachLiveDataDeferral(false, outputCallbacks.generation)
         const gen = await preSignalPromise
@@ -137,6 +152,11 @@ export function startDeferredSessionReattach(
       if (session.rejectObsoleteDirectSshReattach(deferredReattachSessionId)) {
         return
       }
+      if (message.includes(PANE_OWNER_UNVERIFIED_ERROR)) {
+        session.reportError(message)
+        session.settleDirectSshPaneRetryAttempt(session.directSshRetryAttempt, 'failed')
+        return
+      }
       warnTerminalLifecycleAnomaly('restored PTY reattach threw', {
         tabId: session.deps.tabId,
         worktreeId: session.deps.worktreeId,
diff --git a/src/renderer/src/i18n/locales/en.json b/src/renderer/src/i18n/locales/en.json
index 22b1695cc3d..8ab61e5ce21 100644
--- a/src/renderer/src/i18n/locales/en.json
+++ b/src/renderer/src/i18n/locales/en.json
@@ -3078,10 +3078,14 @@
           },
           "TerminalErrorToast": {
             "e4aa243f8c": "Restart daemon",
+            "retry": "Retry",
+            "retrying": "Retrying…",
+            "retryUnavailable": "Retry could not reconnect yet. Try again shortly.",
             "a7e2fd2699": "file an issue",
             "5c8ce20be6": "If this persists, please",
             "cc6d997c65": "Restart the terminal daemon from here to clear stale daemon state.",
-            "7ee11bc0db": "Orca couldn't confirm whether this terminal's previous session is still running, so it left the session untouched. Reopen this pane to retry.",
+            "ownerUnknown": "Orca couldn't verify this terminal's owner.",
+            "42b283ecfc": "Orca couldn't safely reconnect this terminal because the host couldn't verify its saved session. Orca left the saved session unchanged. Click Retry to try reconnecting now. If it still cannot reconnect, open a new terminal.",
             "e16012e31e": "The terminal daemon that owned this session exited, so the session and its scrollback could not be recovered. Open a new terminal to continue.",
             "sessionUnavailable": "Orca couldn't reattach to this pane's terminal session on the host. Open a new terminal to continue."
           },

From 3777070eaf0908dad9189fc6a2c7421476ddfcd3 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Tue, 1 Sep 2026 20:08:09 -0700
Subject: [PATCH 28/32] fix(worktree): restore the stale-cleanup signal after
 the module split (#18058)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(worktree): restore the stale-cleanup signal after the module split

Moving stale-preparation cleanup into its own module took
`staleCleanupInFlight` with it, but `hasPendingWorktreeCreatePreparations`
still read it directly. Both sides were green in isolation — the reference
arrived on main while the split was in review — so the break only appeared
once they merged, and it fails typecheck for every branch built on main.

Expose the predicate from the module that owns the map, and cover the
signal with a test so the idle gate's "a create is imminent" answer cannot
silently regress again.

* test(worktree): anchor the pending-signal test on the scan, not on await depth
---
 ...rktree-create-preparation-stale-cleanup.ts |  5 +++++
 src/main/worktree-create-preparation.test.ts  | 22 +++++++++++++++++++
 src/main/worktree-create-preparation.ts       |  3 ++-
 3 files changed, 29 insertions(+), 1 deletion(-)

diff --git a/src/main/worktree-create-preparation-stale-cleanup.ts b/src/main/worktree-create-preparation-stale-cleanup.ts
index 4a422f672ed..fd02b7cc0d1 100644
--- a/src/main/worktree-create-preparation-stale-cleanup.ts
+++ b/src/main/worktree-create-preparation-stale-cleanup.ts
@@ -74,6 +74,11 @@ export async function cleanupStalePreparations(
   }
 }
 
+/** True while a crash-recovery scan is running, which means a create is in flight or imminent. */
+export function hasPendingStalePreparationCleanup(): boolean {
+  return staleCleanupInFlight.size > 0
+}
+
 export function resetStalePreparationCleanupForTests(): void {
   staleCleanupInFlight.clear()
 }
diff --git a/src/main/worktree-create-preparation.test.ts b/src/main/worktree-create-preparation.test.ts
index dababbef88d..eae3b59081f 100644
--- a/src/main/worktree-create-preparation.test.ts
+++ b/src/main/worktree-create-preparation.test.ts
@@ -39,6 +39,7 @@ vi.mock('./ipc/worktree-logic', () => ({
 import {
   _resetWorktreeCreatePreparationsForTests,
   consumePreparedWorktreeCreate,
+  hasPendingWorktreeCreatePreparations,
   prepareWorktreeCreateForRepo
 } from './worktree-create-preparation'
 
@@ -477,6 +478,27 @@ describe('worktree create preparation registry', () => {
     })
   }
 
+  it('reports a pending create while a stale-cleanup scan is running', async () => {
+    let releaseListing!: () => void
+    mocks.listWorktreeGraph.mockReturnValueOnce(
+      new Promise((resolve) => {
+        releaseListing = () => resolve([])
+      })
+    )
+    const arming = prepareWorktreeCreateForRepo(store, repo, 'origin/main')
+    // Anchor on the scan actually starting, not on a fixed number of microtasks: an await added
+    // ahead of it would otherwise make this pass vacuously rather than fail.
+    while (mocks.listWorktreeGraph.mock.calls.length === 0) {
+      await Promise.resolve()
+    }
+
+    // Why: the idle gate must not start repo maintenance while crash recovery is mid-scan.
+    expect(hasPendingWorktreeCreatePreparations()).toBe(true)
+
+    releaseListing()
+    await arming
+  })
+
   it('does not re-arm after an isolated create', async () => {
     await prepareWorktreeCreateForRepo(store, repo, 'origin/main')
     await expect(consumeOnce('only')).resolves.toEqual({})
diff --git a/src/main/worktree-create-preparation.ts b/src/main/worktree-create-preparation.ts
index b4d86923490..8ddb2a5e69c 100644
--- a/src/main/worktree-create-preparation.ts
+++ b/src/main/worktree-create-preparation.ts
@@ -26,6 +26,7 @@ import {
 } from './worktree-create-preparation-burst'
 import {
   cleanupStalePreparations,
+  hasPendingStalePreparationCleanup,
   resetStalePreparationCleanupForTests
 } from './worktree-create-preparation-stale-cleanup'
 import { toHostFilesystemPath } from './host-tree-removal'
@@ -63,7 +64,7 @@ const preparations = new Map<string, PreparationEntry>()
 
 /** A prepared checkout is a create that is either in flight or imminent. */
 export function hasPendingWorktreeCreatePreparations(): boolean {
-  return preparations.size > 0 || staleCleanupInFlight.size > 0
+  return preparations.size > 0 || hasPendingStalePreparationCleanup()
 }
 
 function pathOps(path: string): Pick<typeof posix, 'dirname' | 'join' | 'normalize'> {

From 42d9ac176734b79de7ab8641e55c736a34f661b8 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Tue, 1 Sep 2026 20:17:41 -0700
Subject: [PATCH 29/32] chore(deps): resolve 81 of 83 Dependabot alerts in
 docs/site and mobile (#18061)

docs/site: bump next 16.2.1 -> 16.3.4 (with eslint-config-next) and vercel
50.37.0 -> 59.11.1, then refresh transitives. The 16.3.x jump is required:
16.2.x hard-pins the vulnerable postcss@8.4.31 and sharp@^0.34.5, while
16.3.x pins postcss@8.5.23 and sharp@^0.35.4.

Five packages are exact-pinned by vercel's own subpackages, so they get
scoped overrides. Scoped rather than blanket because a bare undici override
would drag the 6.x/7.x consumers in the tree down to 5.x.

mobile: bump browserslist 4.28.2 -> 4.28.8.

Two alerts stay open, both in mobile:

- decode-uri-component@0.2.2 (#285). An override to 0.5.0 breaks the tree:
  0.5.0 is ESM-only with a default export, but query-string@7.1.3 is CJS and
  does `require('decode-uri-component')`, so parse() throws
  "decodeComponent is not a function" and takes URL parsing in expo-router
  and @react-navigation/core with it. Both pin query-string@^7.1.3; the fix
  has to come from upstream moving to query-string 8+.
- image-size@1.2.1 (#179, #180) via metro. No patched version exists on any
  release line, so there is nothing to override to.

Verified: docs/site build, tests, lint, tsc and frozen install; mobile
typecheck, 3985 tests and frozen install.
---
 docs/site/package.json   |   15 +-
 docs/site/pnpm-lock.yaml | 1992 ++++++++++++++++++++++++--------------
 mobile/pnpm-lock.yaml    |  331 ++++---
 3 files changed, 1445 insertions(+), 893 deletions(-)

diff --git a/docs/site/package.json b/docs/site/package.json
index 9b5311fa04a..50ea76760fc 100644
--- a/docs/site/package.json
+++ b/docs/site/package.json
@@ -18,7 +18,7 @@
     "fumadocs-mdx": "^14.3.1",
     "fumadocs-ui": "^16.8.4",
     "lucide-react": "^1.6.0",
-    "next": "16.2.1",
+    "next": "16.3.4",
     "react": "19.2.4",
     "react-dom": "19.2.4",
     "tailwind-merge": "^3.5.0",
@@ -32,10 +32,10 @@
     "@types/react": "^19",
     "@types/react-dom": "^19",
     "eslint": "^9",
-    "eslint-config-next": "16.2.1",
+    "eslint-config-next": "16.3.4",
     "tailwindcss": "^4",
     "typescript": "^5",
-    "vercel": "50.37.0"
+    "vercel": "59.11.1"
   },
   "engines": {
     "node": "22.x"
@@ -46,6 +46,13 @@
       "esbuild",
       "sharp",
       "unrs-resolver"
-    ]
+    ],
+    "overrides": {
+      "@vercel/fun>tar": "7.5.22",
+      "@vercel/fun>@tootallnate/once": "2.0.1",
+      "@vercel/node>undici": "5.29.0",
+      "@vercel/python-analysis>js-yaml": "4.3.2",
+      "@vercel/python-analysis>minimatch": "10.2.6"
+    }
   }
 }
diff --git a/docs/site/pnpm-lock.yaml b/docs/site/pnpm-lock.yaml
index 7cfd0ceee6f..4320f1bd617 100644
--- a/docs/site/pnpm-lock.yaml
+++ b/docs/site/pnpm-lock.yaml
@@ -4,6 +4,13 @@ settings:
   autoInstallPeers: true
   excludeLinksFromLockfile: false
 
+overrides:
+  '@vercel/fun>tar': 7.5.22
+  '@vercel/fun>@tootallnate/once': 2.0.1
+  '@vercel/node>undici': 5.29.0
+  '@vercel/python-analysis>js-yaml': 4.3.2
+  '@vercel/python-analysis>minimatch': 10.2.6
+
 importers:
 
   .:
@@ -13,19 +20,19 @@ importers:
         version: 2.1.1
       fumadocs-core:
         specifier: ^16.8.4
-        version: 16.12.1(@mdx-js/mdx@3.1.1)(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.2.17)(lucide-react@1.26.0(react@19.2.4))(next@16.2.1(@babel/core@7.29.7)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(zod@4.4.3)
+        version: 16.12.1(@mdx-js/mdx@3.1.1)(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.2.17)(lucide-react@1.26.0(react@19.2.4))(next@16.3.4(@babel/core@7.29.7)(@types/node@20.19.43)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(zod@4.4.3)
       fumadocs-mdx:
         specifier: ^14.3.1
-        version: 14.3.2(@types/mdast@4.0.4)(@types/mdx@2.0.14)(@types/react@19.2.17)(fumadocs-core@16.12.1(@mdx-js/mdx@3.1.1)(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.2.17)(lucide-react@1.26.0(react@19.2.4))(next@16.2.1(@babel/core@7.29.7)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(zod@4.4.3))(next@16.2.1(@babel/core@7.29.7)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react@19.2.4)
+        version: 14.3.2(@types/mdast@4.0.4)(@types/mdx@2.0.14)(@types/react@19.2.17)(fumadocs-core@16.12.1(@mdx-js/mdx@3.1.1)(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.2.17)(lucide-react@1.26.0(react@19.2.4))(next@16.3.4(@babel/core@7.29.7)(@types/node@20.19.43)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(zod@4.4.3))(next@16.3.4(@babel/core@7.29.7)(@types/node@20.19.43)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react@19.2.4)
       fumadocs-ui:
         specifier: ^16.8.4
-        version: 16.12.1(@types/mdx@2.0.14)(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(fumadocs-core@16.12.1(@mdx-js/mdx@3.1.1)(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.2.17)(lucide-react@1.26.0(react@19.2.4))(next@16.2.1(@babel/core@7.29.7)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(zod@4.4.3))(next@16.2.1(@babel/core@7.29.7)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(tailwindcss@4.3.3)
+        version: 16.12.1(@types/mdx@2.0.14)(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(fumadocs-core@16.12.1(@mdx-js/mdx@3.1.1)(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.2.17)(lucide-react@1.26.0(react@19.2.4))(next@16.3.4(@babel/core@7.29.7)(@types/node@20.19.43)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(zod@4.4.3))(next@16.3.4(@babel/core@7.29.7)(@types/node@20.19.43)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(tailwindcss@4.3.3)
       lucide-react:
         specifier: ^1.6.0
         version: 1.26.0(react@19.2.4)
       next:
-        specifier: 16.2.1
-        version: 16.2.1(@babel/core@7.29.7)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+        specifier: 16.3.4
+        version: 16.3.4(@babel/core@7.29.7)(@types/node@20.19.43)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       react:
         specifier: 19.2.4
         version: 19.2.4
@@ -61,8 +68,8 @@ importers:
         specifier: ^9
         version: 9.39.5(jiti@2.7.0)
       eslint-config-next:
-        specifier: 16.2.1
-        version: 16.2.1(@typescript-eslint/parser@8.65.0(eslint@9.39.5(jiti@2.7.0))(typescript@5.9.3))(eslint@9.39.5(jiti@2.7.0))(typescript@5.9.3)
+        specifier: 16.3.4
+        version: 16.3.4(@typescript-eslint/parser@8.65.0(eslint@9.39.5(jiti@2.7.0))(typescript@5.9.3))(eslint@9.39.5(jiti@2.7.0))(typescript@5.9.3)
       tailwindcss:
         specifier: ^4
         version: 4.3.3
@@ -70,8 +77,8 @@ importers:
         specifier: ^5
         version: 5.9.3
       vercel:
-        specifier: 50.37.0
-        version: 50.37.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.2)(typescript@5.9.3)
+        specifier: 59.11.1
+        version: 59.11.1(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)
 
 packages:
 
@@ -175,8 +182,8 @@ packages:
   '@emnapi/runtime@1.10.0':
     resolution: {integrity: sha512-ewvYlk86xUoGI0zQRNq/mC+16R1QeDlKQy21Ki3oSYXNgLb45GV1P6A0M+/s6nyCuNDqe5VpaY84BzXGwVbwFA==}
 
-  '@emnapi/runtime@1.11.2':
-    resolution: {integrity: sha512-kyOl3X0DuTiT1h2ft8r2fYO8JYtU9a9Xis/zBSiGArNaagCOWx90N1k2wxp18czFDH+OgcWGb5ZP/XMt3dcyPA==}
+  '@emnapi/runtime@1.11.3':
+    resolution: {integrity: sha512-Xz4Tpyki7XyrpbUK1jR1AhdAdaXyhhY4lZ3neLodmhpuWfy2PAQN5B46sAiU4liOXGLkHypn/qU+jvfWSCYYLA==}
 
   '@emnapi/wasi-threads@1.2.1':
     resolution: {integrity: sha512-uTII7OYF+/Mes/MrcIOYp5yOtSMLBWSIoLPpcgwipoiKbli6k322tcoFsxoIIxPDqW01SQGAgko4EzZi2BNv2w==}
@@ -499,6 +506,12 @@ packages:
     peerDependencies:
       eslint: ^6.0.0 || ^7.0.0 || >=8.0.0
 
+  '@eslint-community/eslint-utils@4.9.1':
+    resolution: {integrity: sha512-phrYmNiYppR7znFEdqgfWHXR6NCkZEK7hwWDHZUjit/2/U0r6XvkDl0SYnoM51Hq7FhCGdLDT6zxCCOY1hexsQ==}
+    engines: {node: ^12.22.0 || ^14.17.0 || >=16.0.0}
+    peerDependencies:
+      eslint: ^6.0.0 || ^7.0.0 || >=8.0.0
+
   '@eslint-community/regexpp@4.12.2':
     resolution: {integrity: sha512-EriSTlt5OC9/7SXkRSCAhfSxxoSUgBm33OH+IkwbdpgoqsSsUg7y3uh+IICI/Qg4BBWr3U2i39RpmycbxMq4ew==}
     engines: {node: ^12.0.0 || ^14.0.0 || >=16.0.0}
@@ -588,154 +601,152 @@ packages:
     resolution: {integrity: sha512-bV0Tgo9K4hfPCek+aMAn81RppFKv2ySDQeMoSZuvTASywNTnVJCArCZE2FWqpvIatKu7VMRLWlR1EazvVhDyhQ==}
     engines: {node: '>=18.18'}
 
-  '@iarna/toml@2.2.5':
-    resolution: {integrity: sha512-trnsAYxU3xnS1gPHPyU961coFyLkh4gAD/0zQ5mymY4yOZ+CYvsPqUbOFSw0aDM4y0tV7tiFxL/1XfXPNC6IPg==}
-
   '@img/colour@1.1.0':
     resolution: {integrity: sha512-Td76q7j57o/tLVdgS746cYARfSyxk8iEfRxewL9h4OMzYhbW4TAcppl0mT4eyqXddh6L/jwoM75mo7ixa/pCeQ==}
     engines: {node: '>=18'}
 
-  '@img/sharp-darwin-arm64@0.34.5':
-    resolution: {integrity: sha512-imtQ3WMJXbMY4fxb/Ndp6HBTNVtWCUI0WdobyheGf5+ad6xX8VIDO8u2xE4qc/fr08CKG/7dDseFtn6M6g/r3w==}
-    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+  '@img/sharp-darwin-arm64@0.35.4':
+    resolution: {integrity: sha512-Uhfl4V4lhP2nbUVF9+hyH1+luj86f1gUFeo8ALYxFoULoU+G87D43BfeMP8XHsk9boxAnCY/bf2EHwhA7MuGsA==}
+    engines: {node: '>=20.9.0'}
     cpu: [arm64]
     os: [darwin]
 
-  '@img/sharp-darwin-x64@0.34.5':
-    resolution: {integrity: sha512-YNEFAF/4KQ/PeW0N+r+aVVsoIY0/qxxikF2SWdp+NRkmMB7y9LBZAVqQ4yhGCm/H3H270OSykqmQMKLBhBJDEw==}
-    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+  '@img/sharp-darwin-x64@0.35.4':
+    resolution: {integrity: sha512-hWniXY3bG5qKpkKrAwPe4y+VTPmf086YQAnkxWh7uA1YrlRouWGa0M0Mxj3ZjnXFkv7/TD1bTy9lGUK26vRvWw==}
+    engines: {node: '>=20.9.0'}
     cpu: [x64]
     os: [darwin]
 
-  '@img/sharp-libvips-darwin-arm64@1.2.4':
-    resolution: {integrity: sha512-zqjjo7RatFfFoP0MkQ51jfuFZBnVE2pRiaydKJ1G/rHZvnsrHAOcQALIi9sA5co5xenQdTugCvtb1cuf78Vf4g==}
+  '@img/sharp-freebsd-wasm32@0.35.4':
+    resolution: {integrity: sha512-lIsKw/BU+kjB4eZjxrYrZmwOJYi3Ajrv66iAlBmUPyKc3HpnloevB1g3wxGD9P/5BbQ1brBGl65VRRrCvQDEqA==}
+    engines: {node: '>=20.9.0'}
+    os: [freebsd]
+
+  '@img/sharp-libvips-darwin-arm64@1.3.3':
+    resolution: {integrity: sha512-suTBPTDGrI9WodccaDdwZItTSaBYASlBk1NSfElSHrUfzu3szG6lvIF58+WiFvnfzuK8ZBFS5zE00PxqxnRiPg==}
     cpu: [arm64]
     os: [darwin]
 
-  '@img/sharp-libvips-darwin-x64@1.2.4':
-    resolution: {integrity: sha512-1IOd5xfVhlGwX+zXv2N93k0yMONvUlANylbJw1eTah8K/Jtpi15KC+WSiaX/nBmbm2HxRM1gZ0nSdjSsrZbGKg==}
+  '@img/sharp-libvips-darwin-x64@1.3.3':
+    resolution: {integrity: sha512-FVJZ5mITMobmXIz/hPDTw0EintTW5H3WfrxwLqEqjiIihlu+hVRyGrFQ60xl0Lxn7Bt3zdpevPaQi0HEzqz9fw==}
     cpu: [x64]
     os: [darwin]
 
-  '@img/sharp-libvips-linux-arm64@1.2.4':
-    resolution: {integrity: sha512-excjX8DfsIcJ10x1Kzr4RcWe1edC9PquDRRPx3YVCvQv+U5p7Yin2s32ftzikXojb1PIFc/9Mt28/y+iRklkrw==}
+  '@img/sharp-libvips-linux-arm64@1.3.3':
+    resolution: {integrity: sha512-0DaL0A6Xu6sQSQFwe4iVCrKWU2cCTItnRsYsCdxAMm9NF6twAA9BKnoqy4hqz4+azQ0JHuA26qiUKsf1XJ/v5A==}
     cpu: [arm64]
     os: [linux]
 
-  '@img/sharp-libvips-linux-arm@1.2.4':
-    resolution: {integrity: sha512-bFI7xcKFELdiNCVov8e44Ia4u2byA+l3XtsAj+Q8tfCwO6BQ8iDojYdvoPMqsKDkuoOo+X6HZA0s0q11ANMQ8A==}
+  '@img/sharp-libvips-linux-arm@1.3.3':
+    resolution: {integrity: sha512-3rbU4vqXXc3hY/OiXdl52xZvT0F1yEngWfvqudtPJg/KkyiaQw2DRsFrNzpmLvfavbwOq3qXn36GP8obHRULQA==}
     cpu: [arm]
     os: [linux]
 
-  '@img/sharp-libvips-linux-ppc64@1.2.4':
-    resolution: {integrity: sha512-FMuvGijLDYG6lW+b/UvyilUWu5Ayu+3r2d1S8notiGCIyYU/76eig1UfMmkZ7vwgOrzKzlQbFSuQfgm7GYUPpA==}
+  '@img/sharp-libvips-linux-ppc64@1.3.3':
+    resolution: {integrity: sha512-cdn1OvUBwsXhbC0zSzJnNzf5MZ/mTrobawDvNXBTxe8VtqKAm0sRuEY2Evzovb/w9JMk4TvRxqt1mekSuJz64w==}
     cpu: [ppc64]
     os: [linux]
 
-  '@img/sharp-libvips-linux-riscv64@1.2.4':
-    resolution: {integrity: sha512-oVDbcR4zUC0ce82teubSm+x6ETixtKZBh/qbREIOcI3cULzDyb18Sr/Wcyx7NRQeQzOiHTNbZFF1UwPS2scyGA==}
+  '@img/sharp-libvips-linux-riscv64@1.3.3':
+    resolution: {integrity: sha512-HjPVx7yKz+0lqdhDlTw1tt90wamBoxhiXpvl1XZpJLiHH4RCJ5yDTqH+VlYPv2fwFs89JFw4c1IexYOcQUi4IQ==}
     cpu: [riscv64]
     os: [linux]
 
-  '@img/sharp-libvips-linux-s390x@1.2.4':
-    resolution: {integrity: sha512-qmp9VrzgPgMoGZyPvrQHqk02uyjA0/QrTO26Tqk6l4ZV0MPWIW6LTkqOIov+J1yEu7MbFQaDpwdwJKhbJvuRxQ==}
+  '@img/sharp-libvips-linux-s390x@1.3.3':
+    resolution: {integrity: sha512-neWLh+3yCNThxnfy3c4BbVBeGgt9aftno+XbT56iK28RgeDs3UOFWviLWlUu0bArYVYJaFDK+RRohbicUNCm8Q==}
     cpu: [s390x]
     os: [linux]
 
-  '@img/sharp-libvips-linux-x64@1.2.4':
-    resolution: {integrity: sha512-tJxiiLsmHc9Ax1bz3oaOYBURTXGIRDODBqhveVHonrHJ9/+k89qbLl0bcJns+e4t4rvaNBxaEZsFtSfAdquPrw==}
+  '@img/sharp-libvips-linux-x64@1.3.3':
+    resolution: {integrity: sha512-4vKmvAst9nrowcqquKFAyZJUDolUaIp8uRiN0mWFguJ1IplC9/pitXtlnnlU4aa/eJw3J7i67V+pwUL+wZGdsA==}
     cpu: [x64]
     os: [linux]
 
-  '@img/sharp-libvips-linuxmusl-arm64@1.2.4':
-    resolution: {integrity: sha512-FVQHuwx1IIuNow9QAbYUzJ+En8KcVm9Lk5+uGUQJHaZmMECZmOlix9HnH7n1TRkXMS0pGxIJokIVB9SuqZGGXw==}
+  '@img/sharp-libvips-linuxmusl-arm64@1.3.3':
+    resolution: {integrity: sha512-Y9kQaLMuNoB0bPYOOdcZMaseNrFpPodIWWMrx+CZyydf2xn68j9WYc6sWWRrDwNkzCQjKYfc68L7jKjGlHMibw==}
     cpu: [arm64]
     os: [linux]
 
-  '@img/sharp-libvips-linuxmusl-x64@1.2.4':
-    resolution: {integrity: sha512-+LpyBk7L44ZIXwz/VYfglaX/okxezESc6UxDSoyo2Ks6Jxc4Y7sGjpgU9s4PMgqgjj1gZCylTieNamqA1MF7Dg==}
+  '@img/sharp-libvips-linuxmusl-x64@1.3.3':
+    resolution: {integrity: sha512-fj8Mv0HHfD1Rr+4I68+3agJynxDWtBFgicTbSOb9Bke6pIwzGcJ+RX/yHjmiEGFMCavY/dxvem7MyNaJF+wDiw==}
     cpu: [x64]
     os: [linux]
 
-  '@img/sharp-linux-arm64@0.34.5':
-    resolution: {integrity: sha512-bKQzaJRY/bkPOXyKx5EVup7qkaojECG6NLYswgktOZjaXecSAeCWiZwwiFf3/Y+O1HrauiE3FVsGxFg8c24rZg==}
-    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+  '@img/sharp-linux-arm64@0.35.4':
+    resolution: {integrity: sha512-De4jpEnAU8Hd5oT0j1G3uL4ZvTuipVMn7YC6vPaJhy6/7EwEae0SVAoBrUMYQbkLGDm85taVWwuPc1a44LTzCQ==}
+    engines: {node: '>=20.9.0'}
     cpu: [arm64]
     os: [linux]
 
-  '@img/sharp-linux-arm@0.34.5':
-    resolution: {integrity: sha512-9dLqsvwtg1uuXBGZKsxem9595+ujv0sJ6Vi8wcTANSFpwV/GONat5eCkzQo/1O6zRIkh0m/8+5BjrRr7jDUSZw==}
-    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+  '@img/sharp-linux-arm@0.35.4':
+    resolution: {integrity: sha512-7OAS8gI0EReKGVN2HssHlM6umJgxF5VI3xN0p9FA91p/YO+ou5hiNghLdZ5BEHztwaaK5+bLKRf8x/o2L2nk9A==}
+    engines: {node: '>=20.9.0'}
     cpu: [arm]
     os: [linux]
 
-  '@img/sharp-linux-ppc64@0.34.5':
-    resolution: {integrity: sha512-7zznwNaqW6YtsfrGGDA6BRkISKAAE1Jo0QdpNYXNMHu2+0dTrPflTLNkpc8l7MUP5M16ZJcUvysVWWrMefZquA==}
-    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+  '@img/sharp-linux-ppc64@0.35.4':
+    resolution: {integrity: sha512-2oYZJeIl4kCcMGk4ouZVjnkCtFrpQFlNEtJ6GbxzhHQchwH0NH/qEb9ykmOl29dqwMq+JhFdZn+1ak2FKhI9fQ==}
+    engines: {node: '>=20.9.0'}
     cpu: [ppc64]
     os: [linux]
 
-  '@img/sharp-linux-riscv64@0.34.5':
-    resolution: {integrity: sha512-51gJuLPTKa7piYPaVs8GmByo7/U7/7TZOq+cnXJIHZKavIRHAP77e3N2HEl3dgiqdD/w0yUfiJnII77PuDDFdw==}
-    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+  '@img/sharp-linux-riscv64@0.35.4':
+    resolution: {integrity: sha512-cPbNChoRURAWdebDIHSenxRpgEdy7JkPydSnUxRm9VvKD7m0/xVaR/8Fzlu81pk5nHEvHH87UZUA7cTtwnbJSA==}
+    engines: {node: '>=20.9.0'}
     cpu: [riscv64]
     os: [linux]
 
-  '@img/sharp-linux-s390x@0.34.5':
-    resolution: {integrity: sha512-nQtCk0PdKfho3eC5MrbQoigJ2gd1CgddUMkabUj+rBevs8tZ2cULOx46E7oyX+04WGfABgIwmMC0VqieTiR4jg==}
-    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+  '@img/sharp-linux-s390x@0.35.4':
+    resolution: {integrity: sha512-RY0JFY8Fd6RonCBtHz+DvadaPkXDSI1AUn6yWL9TipqkZ1vY8w8evqdgyDFnkm4/K1ve1TvZiaePP5oSd4+WVQ==}
+    engines: {node: '>=20.9.0'}
     cpu: [s390x]
     os: [linux]
 
-  '@img/sharp-linux-x64@0.34.5':
-    resolution: {integrity: sha512-MEzd8HPKxVxVenwAa+JRPwEC7QFjoPWuS5NZnBt6B3pu7EG2Ge0id1oLHZpPJdn3OQK+BQDiw9zStiHBTJQQQQ==}
-    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+  '@img/sharp-linux-x64@0.35.4':
+    resolution: {integrity: sha512-9qvvEAuk8k89TfWUoX2htWjbAMX8p+NxCppjpcg5k6xMsjhBQPTsoIh36h9Qde4WRuGpJeYnOjdosDn/cnv+OA==}
+    engines: {node: '>=20.9.0'}
     cpu: [x64]
     os: [linux]
 
-  '@img/sharp-linuxmusl-arm64@0.34.5':
-    resolution: {integrity: sha512-fprJR6GtRsMt6Kyfq44IsChVZeGN97gTD331weR1ex1c1rypDEABN6Tm2xa1wE6lYb5DdEnk03NZPqA7Id21yg==}
-    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+  '@img/sharp-linuxmusl-arm64@0.35.4':
+    resolution: {integrity: sha512-KB5jxpfWQTr0nc3xdHtWChdbifHrBGsd2SM62Eyxrl8afikm+f5qGBU75SJIZBT/S1MC8XyacdlXBMSWq6OURA==}
+    engines: {node: '>=20.9.0'}
     cpu: [arm64]
     os: [linux]
 
-  '@img/sharp-linuxmusl-x64@0.34.5':
-    resolution: {integrity: sha512-Jg8wNT1MUzIvhBFxViqrEhWDGzqymo3sV7z7ZsaWbZNDLXRJZoRGrjulp60YYtV4wfY8VIKcWidjojlLcWrd8Q==}
-    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+  '@img/sharp-linuxmusl-x64@0.35.4':
+    resolution: {integrity: sha512-f+eZJZIQNEEd26RPSW+76chwOf1XtA2Y/O+5ocVyLliHkeih3e+jhLVBdNTd2rS3IbNXK8+ug93Vf5ZXtF5Lxg==}
+    engines: {node: '>=20.9.0'}
     cpu: [x64]
     os: [linux]
 
-  '@img/sharp-wasm32@0.34.5':
-    resolution: {integrity: sha512-OdWTEiVkY2PHwqkbBI8frFxQQFekHaSSkUIJkwzclWZe64O1X4UlUjqqqLaPbUpMOQk6FBu/HtlGXNblIs0huw==}
-    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+  '@img/sharp-wasm32@0.35.4':
+    resolution: {integrity: sha512-zQnl4Kwp7Q6NHsENtU2T/00Zi+w3AQNwz3+UaTyVBy2FpXrzXzGjndpK61onhZjRtRpQXxCTeqw19bVyXOh7jA==}
+    engines: {node: '>=20.9.0'}
+
+  '@img/sharp-webcontainers-wasm32@0.35.4':
+    resolution: {integrity: sha512-ESfNkywmCfPNyaZjxooddJQiQ+l/nTpGEOGthxiLnIHXC/CmcBixnfwUleX9mCz9ovrUUvKMap/pm8RYbzfwaA==}
+    engines: {node: '>=20.9.0'}
     cpu: [wasm32]
 
-  '@img/sharp-win32-arm64@0.34.5':
-    resolution: {integrity: sha512-WQ3AgWCWYSb2yt+IG8mnC6Jdk9Whs7O0gxphblsLvdhSpSTtmu69ZG1Gkb6NuvxsNACwiPV6cNSZNzt0KPsw7g==}
-    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+  '@img/sharp-win32-arm64@0.35.4':
+    resolution: {integrity: sha512-iNdlBX9gLVvqe2I3uIJSIKTq6wckP/DYxZtcqxm09x5Gi24DnFBmPAWZmr60ZyYMG0xlzo6goG3670ar+RXvRw==}
+    engines: {node: '>=20.9.0'}
     cpu: [arm64]
     os: [win32]
 
-  '@img/sharp-win32-ia32@0.34.5':
-    resolution: {integrity: sha512-FV9m/7NmeCmSHDD5j4+4pNI8Cp3aW+JvLoXcTUo0IqyjSfAZJ8dIUmijx1qaJsIiU+Hosw6xM5KijAWRJCSgNg==}
-    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+  '@img/sharp-win32-ia32@0.35.4':
+    resolution: {integrity: sha512-kqRsbaa5CS6KHlpxnN7WhE6vAAugXyZButpRdvDWetlv6Qv4N9WTcrWzF7tXfB9T7MsoadqdI8hmwLq6UlLvtw==}
+    engines: {node: ^20.9.0}
     cpu: [ia32]
     os: [win32]
 
-  '@img/sharp-win32-x64@0.34.5':
-    resolution: {integrity: sha512-+29YMsqY2/9eFEiW93eqWnuLcWcufowXewwSNIT6UwZdUUCrM3oFjMWH/Z6/TMmb4hlFenmfAVbpWeup2jryCw==}
-    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+  '@img/sharp-win32-x64@0.35.4':
+    resolution: {integrity: sha512-XtmnYhBcrORsJ4XJngyzr/EWP0hRZLAZRFaApdKuviyqF78+ylxh2y06ZmtULAMOnObJ3ucpN0AcwSWnMowTRg==}
+    engines: {node: '>=20.9.0'}
     cpu: [x64]
     os: [win32]
 
-  '@isaacs/balanced-match@4.0.1':
-    resolution: {integrity: sha512-yzMTt9lEb8Gv7zRioUilSglI0c0smZ9k5D65677DLWLtWJaXIS3CqcGyUFByYKlnUj6TkjLVs54fBl6+TiGQDQ==}
-    engines: {node: 20 || >=22}
-
-  '@isaacs/brace-expansion@5.0.1':
-    resolution: {integrity: sha512-WMz71T1JS624nWj2n2fnYAuPovhv7EUhk69R6i9dsVyzxt5eM3bjwvgk9L+APE1TRscGysAVMANkB0jh0LQZrQ==}
-    engines: {node: 20 || >=22}
-
   '@isaacs/fs-minipass@4.0.1':
     resolution: {integrity: sha512-wgm9Ehl2jpeqP3zw/7mo3kRHFp5MEDhqAdwy1fTGkHAwnkGOVsgpvQhL8B5n1qlb01jV3n/bI0ZfZp5lWA1k4w==}
     engines: {node: '>=18.0.0'}
@@ -764,62 +775,138 @@ packages:
   '@mdx-js/mdx@3.1.1':
     resolution: {integrity: sha512-f6ZO2ifpwAQIpzGWaBQT2TXxPv6z3RBzQKpVftEWN78Vl/YweF1uwussDx8ECAXVtr3Rs89fKyG9YlzUs9DyGQ==}
 
+  '@napi-rs/keyring-darwin-arm64@1.2.0':
+    resolution: {integrity: sha512-CA83rDeyONDADO25JLZsh3eHY8yTEtm/RS6ecPsY+1v+dSawzT9GywBMu2r6uOp1IEhQs/xAfxgybGAFr17lSA==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@napi-rs/keyring-darwin-x64@1.2.0':
+    resolution: {integrity: sha512-dBHjtKRCj4ByfnfqIKIJLo3wueQNJhLRyuxtX/rR4K/XtcS7VLlRD01XXizjpre54vpmObj63w+ZpHG+mGM8uA==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@napi-rs/keyring-freebsd-x64@1.2.0':
+    resolution: {integrity: sha512-DPZFr11pNJSnaoh0dzSUNF+T6ORhy3CkzUT3uGixbA71cAOPJ24iG8e8QrLOkuC/StWrAku3gBnth2XMWOcR3Q==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@napi-rs/keyring-linux-arm-gnueabihf@1.2.0':
+    resolution: {integrity: sha512-8xv6DyEMlvRdqJzp4F39RLUmmTQsLcGYYv/3eIfZNZN1O5257tHxTrFYqAsny659rJJK2EKeSa7PhrSibQqRWQ==}
+    engines: {node: '>= 10'}
+    cpu: [arm]
+    os: [linux]
+
+  '@napi-rs/keyring-linux-arm64-gnu@1.2.0':
+    resolution: {integrity: sha512-Pu2V6Py+PBt7inryEecirl+t+ti8bhZphjP+W68iVaXHUxLdWmkgL9KI1VkbRHbx5k8K5Tew9OP218YfmVguIA==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@napi-rs/keyring-linux-arm64-musl@1.2.0':
+    resolution: {integrity: sha512-8TDymrpC4P1a9iDEaegT7RnrkmrJN5eNZh3Im3UEV5PPYGtrb82CRxsuFohthCWQW81O483u1bu+25+XA4nKUw==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@napi-rs/keyring-linux-riscv64-gnu@1.2.0':
+    resolution: {integrity: sha512-awsB5XI1MYL7fwfjMDGmKOWvNgJEO7mM7iVEMS0fO39f0kVJnOSjlu7RHcXAF0LOx+0VfF3oxbWqJmZbvRCRHw==}
+    engines: {node: '>= 10'}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@napi-rs/keyring-linux-x64-gnu@1.2.0':
+    resolution: {integrity: sha512-8E+7z4tbxSJXxIBqA+vfB1CGajpCDRyTyqXkBig5NtASrv4YXcntSo96Iah2QDR5zD3dSTsmbqJudcj9rKKuHQ==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [linux]
+
+  '@napi-rs/keyring-linux-x64-musl@1.2.0':
+    resolution: {integrity: sha512-8RZ8yVEnmWr/3BxKgBSzmgntI7lNEsY7xouNfOsQkuVAiCNmxzJwETspzK3PQ2FHtDxgz5vHQDEBVGMyM4hUHA==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [linux]
+
+  '@napi-rs/keyring-win32-arm64-msvc@1.2.0':
+    resolution: {integrity: sha512-AoqaDZpQ6KPE19VBLpxyORcp+yWmHI9Xs9Oo0PJ4mfHma4nFSLVdhAubJCxdlNptHe5va7ghGCHj3L9Akiv4cQ==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@napi-rs/keyring-win32-ia32-msvc@1.2.0':
+    resolution: {integrity: sha512-EYL+EEI6bCsYi3LfwcQdnX3P/R76ENKNn+3PmpGheBsUFLuh0gQuP7aMVHM4rTw6UVe+L3vCLZSptq/oeacz0A==}
+    engines: {node: '>= 10'}
+    cpu: [ia32]
+    os: [win32]
+
+  '@napi-rs/keyring-win32-x64-msvc@1.2.0':
+    resolution: {integrity: sha512-xFlx/TsmqmCwNU9v+AVnEJgoEAlBYgzFF5Ihz1rMpPAt4qQWWkMd4sCyM1gMJ1A/GnRqRegDiQpwaxGUHFtFbA==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [win32]
+
+  '@napi-rs/keyring@1.2.0':
+    resolution: {integrity: sha512-d0d4Oyxm+v980PEq1ZH2PmS6cvpMIRc17eYpiU47KgW+lzxklMu6+HOEOPmxrpnF/XQZ0+Q78I2mgMhbIIo/dg==}
+    engines: {node: '>= 10'}
+
   '@napi-rs/wasm-runtime@1.1.6':
     resolution: {integrity: sha512-ZLv/JdUfkvOy9eCnnBaGfiO+XimbjebAeO+MRQqD/B+FR1tnRN0tpKSJHRbE8sFfS6aqsXZ67TQjfwfsxULVbg==}
     peerDependencies:
       '@emnapi/core': ^1.7.1
       '@emnapi/runtime': ^1.7.1
 
-  '@next/env@16.2.1':
-    resolution: {integrity: sha512-n8P/HCkIWW+gVal2Z8XqXJ6aB3J0tuM29OcHpCsobWlChH/SITBs1DFBk/HajgrwDkqqBXPbuUuzgDvUekREPg==}
+  '@next/env@16.3.4':
+    resolution: {integrity: sha512-cjWZnUUa6jZq2kFaNe/ZyJdZonOZ/QoN0Zka2nz/FLOrfx14pQuM9c5RaSVkWMqgdt4ksgPAMWPyHSs/CyV48Q==}
 
-  '@next/eslint-plugin-next@16.2.1':
-    resolution: {integrity: sha512-r0epZGo24eT4g08jJlg2OEryBphXqO8aL18oajoTKLzHJ6jVr6P6FI58DLMug04MwD3j8Fj0YK0slyzneKVyzA==}
+  '@next/eslint-plugin-next@16.3.4':
+    resolution: {integrity: sha512-szW9y2Aumu4z88YXfTzcFsgUAg2k64uzbtcO5L9f1AKS4w/GUKJcbFllRflROVyNPgJtGOnvNxiyp3v6b+prIA==}
 
-  '@next/swc-darwin-arm64@16.2.1':
-    resolution: {integrity: sha512-BwZ8w8YTaSEr2HIuXLMLxIdElNMPvY9fLqb20LX9A9OMGtJilhHLbCL3ggyd0TwjmMcTxi0XXt+ur1vWUoxj2Q==}
+  '@next/swc-darwin-arm64@16.3.4':
+    resolution: {integrity: sha512-iBr3I5LZNk5/bgl5//iTgD2tcym14MX0Xo7fD//u9dYAEgGzza1y9oywluPtf74YnOswVdH1908aK9xVz7zQTw==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [darwin]
 
-  '@next/swc-darwin-x64@16.2.1':
-    resolution: {integrity: sha512-/vrcE6iQSJq3uL3VGVHiXeaKbn8Es10DGTGRJnRZlkNQQk3kaNtAJg8Y6xuAlrx/6INKVjkfi5rY0iEXorZ6uA==}
+  '@next/swc-darwin-x64@16.3.4':
+    resolution: {integrity: sha512-2dpiSyl2Jw/NrBPaU2MAKGSa+2MR82pJIn4Sm5Rjr+gxAeuh0z158Su3Z2O8zn7UNNq+ej4bToed6RcRN/Lydg==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [darwin]
 
-  '@next/swc-linux-arm64-gnu@16.2.1':
-    resolution: {integrity: sha512-uLn+0BK+C31LTVbQ/QU+UaVrV0rRSJQ8RfniQAHPghDdgE+SlroYqcmFnO5iNjNfVWCyKZHYrs3Nl0mUzWxbBw==}
+  '@next/swc-linux-arm64-gnu@16.3.4':
+    resolution: {integrity: sha512-+t+U8HZT+fApePCS5h89CSH3datz29MkzyfCn+6fpsZBG/oiEOhINcb9rtkv6sdpToLGFn2e6146NzaKCXkqrA==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [linux]
 
-  '@next/swc-linux-arm64-musl@16.2.1':
-    resolution: {integrity: sha512-ssKq6iMRnHdnycGp9hCuGnXJZ0YPr4/wNwrfE5DbmvEcgl9+yv97/Kq3TPVDfYome1SW5geciLB9aiEqKXQjlQ==}
+  '@next/swc-linux-arm64-musl@16.3.4':
+    resolution: {integrity: sha512-mx03GNs1ocQA5JQ4FxDMmIsNkdrZh8cuezKCrId28e5/gIPU/l7Kcy2+vmCCzdjnnmXJy+iOAu+7K0QppO6Urg==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [linux]
 
-  '@next/swc-linux-x64-gnu@16.2.1':
-    resolution: {integrity: sha512-HQm7SrHRELJ30T1TSmT706IWovFFSRGxfgUkyWJZF/RKBMdbdRWJuFrcpDdE5vy9UXjFOx6L3mRdqH04Mmx0hg==}
+  '@next/swc-linux-x64-gnu@16.3.4':
+    resolution: {integrity: sha512-YIhGY6fSMfha52bnVxnzc9zaVBzJg+cqQTOD8tXIBSx4fuv0pVMxQTE0PaS59YhnMOiYiG09IMwxJAf/CFm/Dw==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [linux]
 
-  '@next/swc-linux-x64-musl@16.2.1':
-    resolution: {integrity: sha512-aV2iUaC/5HGEpbBkE+4B8aHIudoOy5DYekAKOMSHoIYQ66y/wIVeaRx8MS2ZMdxe/HIXlMho4ubdZs/J8441Tg==}
+  '@next/swc-linux-x64-musl@16.3.4':
+    resolution: {integrity: sha512-+eaaX6axpDb0yF1GCpiERe6njplvdC+nks/fKfcHu3XPGRrald8P3/X7yv7QLdjA51knnxwl9pxdIJsg+w1L+Q==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [linux]
 
-  '@next/swc-win32-arm64-msvc@16.2.1':
-    resolution: {integrity: sha512-IXdNgiDHaSk0ZUJ+xp0OQTdTgnpx1RCfRTalhn3cjOP+IddTMINwA7DXZrwTmGDO8SUr5q2hdP/du4DcrB1GxA==}
+  '@next/swc-win32-arm64-msvc@16.3.4':
+    resolution: {integrity: sha512-0jcXW7Xs/uzICrmgV3MhDYDeRy++1CqnpDIerlPIqYO4bhzB4WNbX/aRnQclustsAyTkFKB0z6rbcjmNg5tR8A==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [win32]
 
-  '@next/swc-win32-x64-msvc@16.2.1':
-    resolution: {integrity: sha512-qvU+3a39Hay+ieIztkGSbF7+mccbbg1Tk25hc4JDylf8IHjYmY/Zm64Qq1602yPyQqvie+vf5T/uPwNxDNIoeg==}
+  '@next/swc-win32-x64-msvc@16.3.4':
+    resolution: {integrity: sha512-vvBzwu1pYQCp92maZCFCIw/XgOTMR5tur9GjakwIo2cmwRTMKajRZZDS9+e4KsUZWKu1E007WUeAFXRRjZeuzw==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [win32]
@@ -844,9 +931,131 @@ packages:
     resolution: {integrity: sha512-a61ljmRVVyG5MC/698C8/FfFDw5a8LOIvyOLW5fztgUXqUpc1jOfQzOitSCbge657OgXXThmY3Tk8fpiDb4UcA==}
     engines: {node: '>= 20.0.0'}
 
+  '@oxc-parser/binding-android-arm-eabi@0.121.0':
+    resolution: {integrity: sha512-n07FQcySwOlzap424/PLMtOkbS7xOu8nsJduKL8P3COGHKgKoDYXwoAHCbChfgFpHnviehrLWIPX0lKGtbEk/A==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm]
+    os: [android]
+
+  '@oxc-parser/binding-android-arm64@0.121.0':
+    resolution: {integrity: sha512-/Dd1xIXboYAicw+twT2utxPD7bL8qh7d3ej0qvaYIMj3/EgIrGR+tSnjCUkiCT6g6uTC0neSS4JY8LxhdSU/sA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [android]
+
+  '@oxc-parser/binding-darwin-arm64@0.121.0':
+    resolution: {integrity: sha512-A0jNEvv7QMtCO1yk205t3DWU9sWUjQ2KNF0hSVO5W9R9r/R1BIvzG01UQAfmtC0dQm7sCrs5puixurKSfr2bRQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@oxc-parser/binding-darwin-x64@0.121.0':
+    resolution: {integrity: sha512-SsHzipdxTKUs3I9EOAPmnIimEeJOemqRlRDOp9LIj+96wtxZejF51gNibmoGq8KoqbT1ssAI5po/E3J+vEtXGA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [darwin]
+
+  '@oxc-parser/binding-freebsd-x64@0.121.0':
+    resolution: {integrity: sha512-v1APOTkCp+RWOIDAHRoaeW/UoaHF15a60E8eUL6kUQXh+i4K7PBwq2Wi7jm8p0ymID5/m/oC1w3W31Z/+r7HQw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@oxc-parser/binding-linux-arm-gnueabihf@0.121.0':
+    resolution: {integrity: sha512-PmqPQuqHZyFVWA4ycr0eu4VnTMmq9laOHZd+8R359w6kzuNZPvmmunmNJ8ybkm769A0nCoVp3TJ6dUz7B3FYIQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm]
+    os: [linux]
+
+  '@oxc-parser/binding-linux-arm-musleabihf@0.121.0':
+    resolution: {integrity: sha512-vF24htj+MOH+Q7y9A8NuC6pUZu8t/C2Fr/kDOi2OcNf28oogr2xadBPXAbml802E8wRAVfbta6YLDQTearz+jw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm]
+    os: [linux]
+
+  '@oxc-parser/binding-linux-arm64-gnu@0.121.0':
+    resolution: {integrity: sha512-wjH8cIG2Lu/3d64iZpbYr73hREMgKAfu7fqpXjgM2S16y2zhTfDIp8EQjxO8vlDtKP5Rc7waZW72lh8nZtWrpA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+
+  '@oxc-parser/binding-linux-arm64-musl@0.121.0':
+    resolution: {integrity: sha512-qT663J/W8yQFw3dtscbEi9LKJevr20V7uWs2MPGTnvNZ3rm8anhhE16gXGpxDOHeg9raySaSHKhd4IGa3YZvuw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+
+  '@oxc-parser/binding-linux-ppc64-gnu@0.121.0':
+    resolution: {integrity: sha512-mYNe4NhVvDBbPkAP8JaVS8lC1dsoJZWH5WCjpw5E+sjhk1R08wt3NnXYUzum7tIiWPfgQxbCMcoxgeemFASbRw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@oxc-parser/binding-linux-riscv64-gnu@0.121.0':
+    resolution: {integrity: sha512-+QiFoGxhAbaI/amqX567784cDyyuZIpinBrJNxUzb+/L2aBRX67mN6Jv40pqduHf15yYByI+K5gUEygCuv0z9w==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@oxc-parser/binding-linux-riscv64-musl@0.121.0':
+    resolution: {integrity: sha512-9ykEgyTa5JD/Uhv2sttbKnCfl2PieUfOjyxJC/oDL2UO0qtXOtjPLl7H8Kaj5G7p3hIvFgu3YWvAxvE0sqY+hQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@oxc-parser/binding-linux-s390x-gnu@0.121.0':
+    resolution: {integrity: sha512-DB1EW5VHZdc1lIRjOI3bW/wV6R6y0xlfvdVrqj6kKi7Ayu2U3UqUBdq9KviVkcUGd5Oq+dROqvUEEFRXGAM7EQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [s390x]
+    os: [linux]
+
+  '@oxc-parser/binding-linux-x64-gnu@0.121.0':
+    resolution: {integrity: sha512-s4lfobX9p4kPTclvMiH3gcQUd88VlnkMTF6n2MTMDAyX5FPNRhhRSFZK05Ykhf8Zy5NibV4PbGR6DnK7FGNN6A==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+
+  '@oxc-parser/binding-linux-x64-musl@0.121.0':
+    resolution: {integrity: sha512-P9KlyTpuBuMi3NRGpJO8MicuGZfOoqZVRP1WjOecwx8yk4L/+mrCRNc5egSi0byhuReblBF2oVoDSMgV9Bj4Hw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+
+  '@oxc-parser/binding-openharmony-arm64@0.121.0':
+    resolution: {integrity: sha512-R+4jrWOfF2OAPPhj3Eb3U5CaKNAH9/btMveMULIrcNW/hjfysFQlF8wE0GaVBr81dWz8JLgQlsxwctoL78JwXw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@oxc-parser/binding-wasm32-wasi@0.121.0':
+    resolution: {integrity: sha512-5TFISkPTymKvsmIlKasPVTPuWxzCcrT8pM+p77+mtQbIZDd1UC8zww4CJcRI46kolmgrEX6QpKO8AvWMVZ+ifw==}
+    engines: {node: '>=14.0.0'}
+    cpu: [wasm32]
+
+  '@oxc-parser/binding-win32-arm64-msvc@0.121.0':
+    resolution: {integrity: sha512-V0pxh4mql4XTt3aiEtRNUeBAUFOw5jzZNxPABLaOKAWrVzSr9+XUaB095lY7jqMf5t8vkfh8NManGB28zanYKw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [win32]
+
+  '@oxc-parser/binding-win32-ia32-msvc@0.121.0':
+    resolution: {integrity: sha512-4Ob1qvYMPnlF2N9rdmKdkQFdrq16QVcQwBsO8yiPZXof0fHKFF+LmQV501XFbi7lHyrKm8rlJRfQ/M8bZZPVLw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [ia32]
+    os: [win32]
+
+  '@oxc-parser/binding-win32-x64-msvc@0.121.0':
+    resolution: {integrity: sha512-BOp1KCzdboB1tPqoCPXgntgFs0jjeSyOXHzgxVFR7B/qfr3F8r4YDacHkTOUNXtDgM8YwKnkf3rE5gwALYX7NA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [win32]
+
   '@oxc-project/types@0.110.0':
     resolution: {integrity: sha512-6Ct21OIlrEnFEJk5LT4e63pk3btsI6/TusD/GStLi7wYlGJNOl1GI9qvXAnRAxQU9zqA2Oz+UwhfTOU2rPZVow==}
 
+  '@oxc-project/types@0.121.0':
+    resolution: {integrity: sha512-CGtOARQb9tyv7ECgdAlFxi0Fv7lmzvmlm2rpD/RdijOO9rfk/JvB1CjT8EnoD+tjna/IYgKKw3IV7objRb+aYw==}
+
   '@oxc-transform/binding-android-arm-eabi@0.111.0':
     resolution: {integrity: sha512-NdFLicvorfHYu0g2ftjVJaH7+Dz27AQUNJOq8t/ofRUoWmczOodgUCHx8C1M1htCN4ZmhS/FzfSy6yd/UngJGg==}
     engines: {node: ^20.19.0 || >=22.12.0}
@@ -1455,8 +1664,8 @@ packages:
   '@standard-schema/spec@1.1.0':
     resolution: {integrity: sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==}
 
-  '@swc/helpers@0.5.15':
-    resolution: {integrity: sha512-JQ5TuMi45Owi4/BIMAJBoSQoOJu12oOk/gADqlcUL9JEdHB8vyjUSsxqeNXnmXHjYKMi2WcYtezGEEhqUI/E2g==}
+  '@swc/helpers@0.5.23':
+    resolution: {integrity: sha512-5lSsMOTXURePglDfvuAQUqkGek9Hg2kksOYay2m0+XR++b2NWYL/4sWyuvVBIs8oKnJaxkdi9whaL/sqN13afw==}
 
   '@tailwindcss/node@4.3.3':
     resolution: {integrity: sha512-/T8IKEsf9VTU6tLjgC7+sv2mOPtQxzE2jMw7u4Tt40Tx+QSZxpzh95/H6cMKoja9XuW7iMdLJYBB0o9G1CaAgg==}
@@ -1546,13 +1755,10 @@ packages:
   '@tailwindcss/postcss@4.3.3':
     resolution: {integrity: sha512-JTSZZGQi1AyKirbLN3azmjVzef92tcX7h+iSqPdaeStyFpGpDlKvvpxeOE8njhbUanbRwr3z8DyzhICWnMtQeg==}
 
-  '@tootallnate/once@2.0.0':
-    resolution: {integrity: sha512-XCuKFP5PS55gnMVu3dty8KPatLqUoy/ZYzDzAGCQ8JNFCkLXzmI7vNHCR+XpbZaMWQK/vQubr7PkYq8g470J/A==}
+  '@tootallnate/once@2.0.1':
+    resolution: {integrity: sha512-HqmEUIGRJ5fSXchkVgR5F7qn48bDBzv0kWj/Kfu5e6uci4UlEeng4331LnBkWffb++Ei3FOVLxo8JJWMFBDMeQ==}
     engines: {node: '>= 10'}
 
-  '@tootallnate/quickjs-emscripten@0.23.0':
-    resolution: {integrity: sha512-C5Mc6rdnsaJDjO3UpGW/CQTHtCKaYlScZTly4JIu97Jxo/odCiH0ITnDXSJPTOrEKk/ycSZ0AOgTmkDtkOsvIA==}
-
   '@ts-morph/common@0.11.1':
     resolution: {integrity: sha512-7hWZS0NRpEsNV8vWJzg7FEz6V8MaLNeJOmwmghqUXTpzk16V1LLZhdo+4QvE/+zv4cVci0OviuJFnqhEfoV3+g==}
 
@@ -1778,105 +1984,186 @@ packages:
     cpu: [x64]
     os: [win32]
 
-  '@vercel/backends@0.0.51':
-    resolution: {integrity: sha512-rGuyw79vubB9VyXhb5eMvm3uNe7D3avDHNm4zXbF99m54346KNOvRp0jJ39rBgh6I4wQ1SUal/vUYcs+nDI3DQ==}
+  '@vercel/backends@7.0.0':
+    resolution: {integrity: sha512-he5zmmtKzzaoizZhPXHxd9bOge3pOL90uz33b9IzmGnImWBlkSOPtGQr5r+NX2ad8HS5HWBdUchwAEcnxYz66w==}
     peerDependencies:
-      typescript: ^4.0.0 || ^5.0.0
+      '@vercel/build-utils': 14.9.0
 
-  '@vercel/blob@2.3.0':
-    resolution: {integrity: sha512-oYWiJbWRQ7gz9Mj0X/NHFJ3OcLMOBzq/2b3j6zeNrQmtFo6dHwU8FAwNpxVIYddVMd+g8eqEi7iRueYx8FtM0Q==}
+  '@vercel/blob@2.8.0':
+    resolution: {integrity: sha512-Nu+HWKpkgovCh/ezlG7wCVwF7RErTzLzZMbGKFBdGBCbTKyK+s5VXPLl+0+TpNEQPH8AVaGzOpIsXUOtkqylCQ==}
     engines: {node: '>=20.0.0'}
 
-  '@vercel/build-utils@13.10.0':
-    resolution: {integrity: sha512-i+fF1EvEzZhrifP1qUYklTmrUTmndPfsvWGLsv9TaDm5WqX8VOp8irUAhOwc5gc5RHEOs4Ox0GtiPhJ7oZ59cw==}
+  '@vercel/build-utils@14.9.0':
+    resolution: {integrity: sha512-czxOQSyZgFYZoD72gRSkRSokGghDyh5pMBPiuy0bjq2I4t7vjiENF1FN0NI/em5S/ITh2hKN1kzXHFwQy9jg6g==}
 
-  '@vercel/cervel@0.0.38':
-    resolution: {integrity: sha512-1/802XtFsfOmZH7hNTQqlMv/8rSNwTOkJPY0uU1CgXk7yYMG9nq2uOTF1eumx+0TwMc8cO9X9azOi35lGP++yw==}
+  '@vercel/cervel@0.1.59':
+    resolution: {integrity: sha512-zFpD1AWHher/SYpwJAZTnw9ncf3qVdPWGG0fTUz0dTlO7nkdV67zXLej46y+PrbML1LtHXMqBQRauM9Y8uH+wg==}
     hasBin: true
-    peerDependencies:
-      typescript: ^4.0.0 || ^5.0.0
 
-  '@vercel/detect-agent@1.2.1':
-    resolution: {integrity: sha512-U/BJCltQSTFTHwaiCQQTQG3GonTbRoEewjV+OU2mMjcHLAoPOh6CP1SXA2XNmqiqI3c82nkRNJ7piZ14RqmTXw==}
+  '@vercel/cli-auth@0.3.5':
+    resolution: {integrity: sha512-DSkTWamJrhgCUrymOSCWysbiVeLsvPINhoKVTw+mypoyIJxKQxDgQaafvZ0OYGS2qg8wVUY30HgDugzaEdwo6Q==}
+
+  '@vercel/cli-config@0.2.4':
+    resolution: {integrity: sha512-kZ5SojbrV06GHoU6QIWGwDXLov+s9rWZ7QqdqKfJfBGCNUieGfgaCjeeenNy8Y+QC0bwC0dZ2B4l5Hvdmrgpdw==}
+
+  '@vercel/cli-exec@1.0.1':
+    resolution: {integrity: sha512-g9XerViJ/paZujufXYcu5XYI2vU2rtB4sgdpjUHde5RnOkdmpu0ngH46LCFGHoPXO/C+qDPSczIHIRN+8Q2YKQ==}
+    engines: {node: '>= 18'}
+
+  '@vercel/container@7.0.0':
+    resolution: {integrity: sha512-VhQAJv8j6/ufedWYAbwjJ94p3R0MfNYiJmamr68NeFVGJlv6sFNm1SJb1Rzl+6udK44BcQp3M64qKFO4ARNLFA==}
+    peerDependencies:
+      '@vercel/build-utils': 14.9.0
+
+  '@vercel/detect-agent@1.2.5':
+    resolution: {integrity: sha512-0krENrjuitlW8s6TJu0MlqCevyCU7K7JK63jZAf7xZ6n17tx+vUEwzHT3sTxawtwZxaW21hu+oFUpoOrm49FsQ==}
     engines: {node: '>=14'}
 
-  '@vercel/elysia@0.1.53':
-    resolution: {integrity: sha512-SdQP06NbODpTOBc6NRV9y/5vpV4wfBZFpWZiJ8oUj5F9POPR7tz+FempLi/YfTv5OuYiA76K3mugNFFEOtpyrg==}
+  '@vercel/elysia@7.0.0':
+    resolution: {integrity: sha512-EZgu9HXQVf1af7sElg3tws+0TTT/k1DgPyDftJnXfk1L3W8M31pqbBY3a6I1hcnWxNaNceF2VtSWMPNrmsTOVQ==}
+    peerDependencies:
+      '@vercel/build-utils': 14.9.0
 
-  '@vercel/error-utils@2.0.3':
-    resolution: {integrity: sha512-CqC01WZxbLUxoiVdh9B/poPbNpY9U+tO1N9oWHwTl5YAZxcqXmmWJ8KNMFItJCUUWdY3J3xv8LvAuQv2KZ5YdQ==}
+  '@vercel/error-utils@2.2.1':
+    resolution: {integrity: sha512-9DhP8jP7raLML4hGsBemxX5fXuQnu5xxMV+HjGygGbzEmVK/+KyJ3QP2Cw7PdF0uXdb9N0Qa4c3tRGH34ZX6vw==}
 
-  '@vercel/express@0.1.63':
-    resolution: {integrity: sha512-hUQk+rVo+26NH8DAqXrxiC9j2ajvMlz6iwY+KQYFwHxh9mI+NmeBRD8ELJdl54Z5tEeec8BQ/9giKmbu+NpzkA==}
+  '@vercel/express@7.0.0':
+    resolution: {integrity: sha512-dhGOtQk3HJXQBeFyfiDP0/nIWqwzrvN02rr/tF8zEk45Z6xqLlSkvH47lVPlvVQdoPy93MOlwKA7/gYapi1chg==}
+    peerDependencies:
+      '@vercel/build-utils': 14.9.0
 
-  '@vercel/fastify@0.1.56':
-    resolution: {integrity: sha512-4LXxtieB+UVPLeGgw0q48g4PX+uquBIJPVlgs1ABySI5X4IVJXm3KTAABuaZ0mJ/yAryIc4FXD3pYzU7hSCfQg==}
+  '@vercel/fastify@7.0.0':
+    resolution: {integrity: sha512-tcB2pd0DdQls884nS70bkZgdrYRFceST1zZO/073o1iJG0VVoFcIPuDdePGlIIetegGJ+S68Wc47gr4TU/UQcQ==}
+    peerDependencies:
+      '@vercel/build-utils': 14.9.0
 
   '@vercel/fun@1.3.0':
     resolution: {integrity: sha512-8erw9uPe0dFg45THkNxmjtvMX143SkZebmjgSVbcM3XCkXu3RIiBaJMcMNG8aaS+rnTuw8+d4De9HVT0M/r3wg==}
     engines: {node: '>= 18'}
 
-  '@vercel/gatsby-plugin-vercel-analytics@1.0.11':
-    resolution: {integrity: sha512-iTEA0vY6RBPuEzkwUTVzSHDATo1aF6bdLLspI68mQ/BTbi5UQEGjpjyzdKOVcSYApDtFU6M6vypZ1t4vIEnHvw==}
+  '@vercel/gatsby-plugin-vercel-analytics@1.0.12':
+    resolution: {integrity: sha512-Ejlhwxr7EBYJxtwYnlh6Vm6A2dPsUSPxMdYrfv0koZkgAzVwo7cG4aDQiy7iASMaGzwuI/PAnwlY2sJBF5b4OA==}
 
-  '@vercel/gatsby-plugin-vercel-builder@2.1.4':
-    resolution: {integrity: sha512-PONQs8DAc/P/tWGHGluDWE4aD0WfjDkod9sr8ksJJUpvkhanPpTQAFj8CTCbnr9Tu/9FWa1ZdwB4Q2+pXCWTEA==}
+  '@vercel/gatsby-plugin-vercel-builder@2.2.52':
+    resolution: {integrity: sha512-PYl9TBsYsP0a7qB4kgrF0a5YBUt7caiZwrxd4dl/uPdWHZlogTrnw2Cf2GS/kgij4rsew5jhc9xMnE4eHvQ1zg==}
 
-  '@vercel/go@3.4.6':
-    resolution: {integrity: sha512-ig91qRY+f4lLXWoRvnhEvu5DcT7LXtALBo/jJqxvlyOsHRBP4mdAvUgg9sygu2NOeMSV/cy249yJqQniP32HWw==}
+  '@vercel/go@10.0.0':
+    resolution: {integrity: sha512-G2tHOrb64snuckAdfq+OjMqE8fKIB4rq3FpbmaQ1vjvnyK/PqyWnvX9gCoIigThM49P0RkGQVp76DCt1RFGh4Q==}
+    peerDependencies:
+      '@vercel/build-utils': 14.9.0
 
-  '@vercel/h3@0.1.62':
-    resolution: {integrity: sha512-0gzAyyf3rZf6ZG0ZTE33TczpX5ioR3dF8p4i78wVH+xEmaQ4u1o8yvVMK49CcMoQ1qjJVdpwQfI41BAfKQk7ig==}
+  '@vercel/h3@7.0.0':
+    resolution: {integrity: sha512-GYhMAK/XgDAQmgXSaiokz2kjc8QeE4azNg9aajcAm2q16Yd+t4a+VZutHppfk4I5SaLf5sKAGhGB8hkCHkbTPA==}
+    peerDependencies:
+      '@vercel/build-utils': 14.9.0
 
-  '@vercel/hono@0.2.56':
-    resolution: {integrity: sha512-fB7zOx9B+eYzUDBmwZHqKn3kVQ2XYUjTdMQb1+FxWmSKr5T/uIRuX8ayWnD1lT5Bmrt5534nB6wVfZRljmWWzA==}
+  '@vercel/hono@7.0.0':
+    resolution: {integrity: sha512-Bn+illFuXukoI0l2z9Y75IS0c8mnLwy0zf5D0AIC2vegjPy5PnoYZ8c7mnEh88On/2ahMR3KEfocWnDssbpGHQ==}
+    peerDependencies:
+      '@vercel/build-utils': 14.9.0
 
-  '@vercel/hydrogen@1.3.6':
-    resolution: {integrity: sha512-Ec8dKEjGIM4BfThcRLtQs5zaJ4+iJbgLZwkytwi7Blk8VrK6W2F1dtLDmVQYZdVnQcnmHmTx8mxUuMkfP06Mnw==}
+  '@vercel/hydrogen@8.0.0':
+    resolution: {integrity: sha512-Z2CKkTKn2SsqD5ftXXizPJ2HCmUoWvvEL9RnSd/eup1IPpOMK42MjIGyh+aPiiwzOwcPmoANPCmMufqrUOjHzw==}
+    peerDependencies:
+      '@vercel/build-utils': 14.9.0
 
-  '@vercel/koa@0.1.36':
-    resolution: {integrity: sha512-ht1w0Qjrb9uMGbfz7aFabs1CCOG24XH5tLYN+sb4sYKHdioKusbpa4u9O76WrAwJXtnyHc48hJE4eyb6lCTndQ==}
+  '@vercel/koa@7.0.0':
+    resolution: {integrity: sha512-UgfQVMc2+hjfoMrGmAFhHmGIf1uDwNL+3Y2B+Ad9Gn4D2wz2gn2Pl5ywy23VOmfSD/aTerbLigTWKT+y9fb9Tg==}
+    peerDependencies:
+      '@vercel/build-utils': 14.9.0
 
-  '@vercel/nestjs@0.2.57':
-    resolution: {integrity: sha512-qXE4Z0BZTj4KEpDJtZp0/2x1aOWf97tUHoatCG+ovTRLIdtSLhyZUFDcoqv/T/WZ4MbO24JqX2sqLmuiTUxIow==}
+  '@vercel/nestjs@7.0.0':
+    resolution: {integrity: sha512-suD7cuigAQlLA/RLAly8234gXXgIC/XG7AGBa1h2Y4vuIwGP43EBHZ4IuojdN6YCKwbD4/2eUMRa/qBs9OpsNQ==}
+    peerDependencies:
+      '@vercel/build-utils': 14.9.0
 
-  '@vercel/next@4.16.3':
-    resolution: {integrity: sha512-yVLrMxMI+Taq47C94lWVUf981WerJ+COrJbgltHcMY8HDdXdgthYe06+na3dni31AL6BYShS8VLpE54QsAdM9Q==}
+  '@vercel/next@11.0.0':
+    resolution: {integrity: sha512-eTaJA+6iKLfhRwOl44mAuNj35jnuA5uExpDvy8vN+oWW0F5Ycjc2yoLHffbUO+9x3SWmo9CV5hpkGKfSSrJakg==}
+    peerDependencies:
+      '@vercel/build-utils': 14.9.0
 
-  '@vercel/nft@1.5.0':
-    resolution: {integrity: sha512-IWTDeIoWhQ7ZtRO/JRKH+jhmeQvZYhtGPmzw/QGDY+wDCQqfm25P9yIdoAFagu4fWsK4IwZXDFIjrmp5rRm/sA==}
+  '@vercel/nft@1.10.0':
+    resolution: {integrity: sha512-iLOW4fcsgkipfOh2Bw3wB38YDfxTlxr7+j4uFeui2OswkNT28jIitS/aMce7tS0mef1YPQ8zLIDYr3a0aahNrA==}
     engines: {node: '>=20'}
     hasBin: true
 
-  '@vercel/node@5.6.20':
-    resolution: {integrity: sha512-n9ZMFzuRauAQNhwVvmsS/prG0We7RyDP2j/tPQoxcnOq5vP1DK6A+r7dG46sRTytgxVBgVJtU3486RAOvhOgcg==}
+  '@vercel/node@12.0.0':
+    resolution: {integrity: sha512-F3tbqSdN1Nap1zeZcdfScatAVFUrLLYXNBsHf9wutOMyOjuW7M32NEEp1eXhjHXdrIg9SyChooqvJPmt3iepSw==}
+    peerDependencies:
+      '@vercel/build-utils': 14.9.0
 
-  '@vercel/prepare-flags-definitions@0.2.1':
-    resolution: {integrity: sha512-ouXTsqn7I9xZ1KKezgvn/w3tZeQHL/tc52j9GHiOYi6kT8xgdbT8s2x8C9BQr44iceX0hfhtZwk9q7NuI2Tqbw==}
+  '@vercel/oidc@3.2.0':
+    resolution: {integrity: sha512-UycprH3T6n3jH0k44NHMa7pnFHGu/N05MjojYr+Mc6I7obkoLIJujSWwin1pCvdy/eOxrI/l3uDLQsmcrOb4ug==}
+    engines: {node: '>= 20'}
 
-  '@vercel/python-analysis@0.11.0':
-    resolution: {integrity: sha512-gsoj+nscmNm0xDh+tRhECRhit2VlAVaD7jc9h93sN6rDEBDxPo7eLEgIJFzVDaAItxERZ9Od2IK/04fB9vFy+g==}
+  '@vercel/oidc@3.8.5':
+    resolution: {integrity: sha512-RwXYtnt6za+5UO4IaLywN/6B95AlLqynPRUWRJxeJ/qufwkcLUbZNUxYtzT0uMpuraWhlNcGqPNGkTnZr4BGBw==}
+    engines: {node: '>= 20'}
 
-  '@vercel/python@6.28.0':
-    resolution: {integrity: sha512-/Ley7HPz/AXhxO7unK5+4hEtsMUxXa02SJ8Tiaz//nEtRQMUcVREIyAUkOOfecjiCpg2hMHSVyCtABFjhzAbgA==}
+  '@vercel/prepare-flags-definitions@0.3.0':
+    resolution: {integrity: sha512-/0nuDFwYje0nqZnVKSd2VfJy2wOPQwbkas1qO1JQgtb0sLl+EeSCW4O9hrvq55pN50PNlAZ/APSeWHIAT9ZGHg==}
 
-  '@vercel/redwood@2.4.12':
-    resolution: {integrity: sha512-8kJ7eEerI4iMpKVRxQCsnxiIwRVsWtyirEbYb4erCqqsJymTu/xrjhsfAUuzeP8qkuYGP82MJVK+hpKlFtsjGw==}
+  '@vercel/python-analysis@0.14.0':
+    resolution: {integrity: sha512-qyVxbaU14gAi/AsaR8syZLukUsOp69Jkm1xn80rZPy4k9+zRUTIfqs0AOk7L8wwBxDDB6LLjcBUAmafhbJQnUQ==}
 
-  '@vercel/remix-builder@5.7.2':
-    resolution: {integrity: sha512-bfStsDBQramYbWugelfyp1szTuDOLQ+ZELvgA9cpYc4FucgCrDy/bpvMMvsjiDACB9PoDzLrG//ZBgsic9yAhg==}
+  '@vercel/python@13.0.0':
+    resolution: {integrity: sha512-KUqi9G5jx26m10kbpzgd8q2jGlijgX4aawH5aD2J8T7pu4q0dZGTw0DlczdrSFnEDYd8yM3zghGjXjtvcrKeaQ==}
+    peerDependencies:
+      '@vercel/build-utils': 14.9.0
 
-  '@vercel/ruby@2.3.2':
-    resolution: {integrity: sha512-okIgMmPEePyDR9TZYaKM4oftcxVHM5Dbdl7V/tIdh3lq8MGLi7HR5vvQglmZUwZOeovE6MVtezxl960EOzeIiQ==}
+  '@vercel/redwood@9.0.0':
+    resolution: {integrity: sha512-y4YdEsqjGVHFcLTPKZWppTvcgXbq9edxxXl+KBEJvtJpqY7s4ZjFd+BzF8YF6KTC7x18rYOiugBSrbyLyctRtQ==}
+    peerDependencies:
+      '@vercel/build-utils': 14.9.0
 
-  '@vercel/rust@1.0.5':
-    resolution: {integrity: sha512-Y03g59nv1uT6Da+PvB/50WqJSHlaFZ9MSkG00R82dUcTySslMbQdOeaXymZtabrmU8zQYhWDb1/CwBki8sWnaQ==}
+  '@vercel/remix-builder@12.0.0':
+    resolution: {integrity: sha512-SQqmOQSQn44Migiu/xglGZ2EjlE4YfEEi8GpOHfN2iVKZhGqyeA5spTzVuxWAHjxeYbaOarHW7qM/giaFc0e2A==}
+    peerDependencies:
+      '@vercel/build-utils': 14.9.0
 
-  '@vercel/static-build@2.9.4':
-    resolution: {integrity: sha512-TqObjKTlr9nGkOzAUFweshKdbqOFKj8hS1xE499A7wYqlZWcORfcn+Yqe9ifXi628KA9+K+sLPaXJN/D4krr7A==}
+  '@vercel/ruby@9.0.0':
+    resolution: {integrity: sha512-kTmJZWkZpSEcK1t0FuM1Py1PTLDTgGbmhwXt1B1Tv/ZpJU2UfLK9rxzNUZemy2jdxSRtFWL+D/Ur0j1sF1W7Hg==}
+    peerDependencies:
+      '@vercel/build-utils': 14.9.0
 
-  '@vercel/static-config@3.2.0':
-    resolution: {integrity: sha512-UpOEIgWxWx0M+mDe1IMdHS6JuWM/L5nNIJ4ixX8v9JgBAejymo88OkgnmfLCNMem0Wd+b5vcQPWLdZybCndlsA==}
+  '@vercel/rust@8.0.0':
+    resolution: {integrity: sha512-Ut16g8BZkwedJ8NN+LlPZPbiy4sC4efYYl2f440A6dg7obW5t4xjt9M1wTkooIgT0w2/j/FVfDdmQNJGfpPCgA==}
+    peerDependencies:
+      '@vercel/build-utils': 14.9.0
+
+  '@vercel/sandbox@3.1.0':
+    resolution: {integrity: sha512-z124E4rsmNpwGtTnLImiYzEXk972bWniQyhlvkEt35UtwKTdfBAFXcNG2OvqYqwzAsdQaP3B7teQ2pqA9B5Viw==}
+
+  '@vercel/static-build@9.0.0':
+    resolution: {integrity: sha512-JrYaWxWmq83vQofB669VTp9egqoJN4wn3JgduvgCj3mNsdRj7R2wvyMPdGJWNm6t5Jsq3YMikik9VVmxZpctRQ==}
+    peerDependencies:
+      '@vercel/build-utils': 14.9.0
+
+  '@vercel/static-config@3.4.3':
+    resolution: {integrity: sha512-BY1sL8rNJvIm3TK/8TQ+Q6jIx7NpO5xckQzv7s6c1ypHvRnTl+vf6rmgY5WFXmoYDeGm3tMy4jiy/5M/5jGr/g==}
+
+  '@vercel/vc-native-darwin-arm64@59.11.1':
+    resolution: {integrity: sha512-Lpxu0C2h3HThwfa7hrQXtzvy0uMAg2XAgMAyS0xwe10LQ5+OiX3nNFQCb4sGKhCBHvtiHv14iSCZRgQo1HtNFQ==}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@vercel/vc-native-darwin-x64@59.11.1':
+    resolution: {integrity: sha512-aAmQaFTC37ZNFWwf+WZ+zSzCnbKXR6UkQC77Zx2sbc/yGsjraBzf44Nza9fL1lLfVsIYs+wixmLKhvig1AQ06A==}
+    cpu: [x64]
+    os: [darwin]
+
+  '@vercel/vc-native-linux-arm64@59.11.1':
+    resolution: {integrity: sha512-npU8GcrkwqyOotX2txj5TRIC9gof7uFr1Lp5fhzlw7qLoZNTzP/uNu//erNsSi4/LjIGBAD0YAnWVv6XkvlT1Q==}
+    cpu: [arm64]
+    os: [linux]
+
+  '@vercel/vc-native-linux-x64@59.11.1':
+    resolution: {integrity: sha512-CV0nod07WyVceW9KucckRZSi4AVuQYz/T+lKjSmnNOFXz9TPi6i0X1R8ObcDfSzi0o6kgVhUGZS2+DXDiUTHqQ==}
+    cpu: [x64]
+    os: [linux]
+
+  '@workflow/serde@4.1.0-beta.2':
+    resolution: {integrity: sha512-8kkeoQKLDaKXefjV5dbhBj2aErfKp1Mc4pb6tj8144cF+Em5SPbyMbyLCHp+BVrFfFVCBluCtMx+jjvaFVZGww==}
 
   abbrev@3.0.1:
     resolution: {integrity: sha512-AO2ac6pjRB3SJmGJo+v5/aK6Omggp6fsLrs6wN9bd35ulu4cCwaAU9+7ZhXjeqHVkaHThLuzH0nZr0YpCDhygg==}
@@ -1963,10 +2250,6 @@ packages:
   ast-types-flow@0.0.8:
     resolution: {integrity: sha512-OH/2E5Fg20h2aPrbe+QL8JZQFko0YZaF+j4mnQ7BGhfavO7OpSLa8a0y9sBwomHdSbkhTS8TQNayBfnW5DwbvQ==}
 
-  ast-types@0.13.4:
-    resolution: {integrity: sha512-x1FCFnFifvYDDzTaLII71vG5uvDwgtmDTEVWAxrgeiR8VjMONcCXJx7E+USjDtHlwFmt9MysbqgF9b9Vjr6w+w==}
-    engines: {node: '>=4'}
-
   astring@1.9.0:
     resolution: {integrity: sha512-LElXdjswlqjWrPpJFg1Fx4wpkOCxj1TDHlSV4PlaRxHGWko024xICaa97ZkMfs6DRKlCguiAI+rbXv5GWwXIkg==}
     hasBin: true
@@ -1992,9 +2275,6 @@ packages:
   async-sema@3.1.1:
     resolution: {integrity: sha512-tLRNUXati5MFePdAk8dw7Qt7DpxPB60ofAgn8WRhW6a2rcimZnYBP9oxHiv0OHy+Wz7kPMG+t4LGdt31+4EmGg==}
 
-  asynckit@0.4.0:
-    resolution: {integrity: sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q==}
-
   available-typed-arrays@1.0.7:
     resolution: {integrity: sha512-wvUjBtSGN7+7SjNpq/9M2Tg350UZD3q62IFZLbRAR1bSMlCo1ZaeW+BJ+D090e4hIIZLBcTDWe4Mh4jvUDajzQ==}
     engines: {node: '>= 0.4'}
@@ -2007,6 +2287,14 @@ packages:
     resolution: {integrity: sha512-qIj0G9wZbMGNLjLmg1PT6v2mE9AH2zlnADJD/2tC6E00hgmhUOfEB6greHPAfLRSufHqROIUTkw6E+M3lH0PTQ==}
     engines: {node: '>= 0.4'}
 
+  b4a@1.8.1:
+    resolution: {integrity: sha512-aiqre1Nr0B/6DgE2N5vwTc+2/oQZ4Wh1t4NznYY4E00y8LCt6NqdRv81so00oo27D8MVKTpUa/MwUUtBLXCoDw==}
+    peerDependencies:
+      react-native-b4a: '*'
+    peerDependenciesMeta:
+      react-native-b4a:
+        optional: true
+
   bail@2.0.2:
     resolution: {integrity: sha512-0xO6mYd7JB2YesxDKplafRpsiOzPt9V02ddPCLbY1xYGPOX24NTyN50qnUxgCPcSoYMhKpAuBTjQoRZCAkUDRw==}
 
@@ -2017,15 +2305,19 @@ packages:
     resolution: {integrity: sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==}
     engines: {node: 18 || 20 || >=22}
 
+  bare-events@2.9.2:
+    resolution: {integrity: sha512-AIPKioV7/Y/8KfZ3AAhjPJxLLbY49S64Ym5DakZlUg75qQiTgUq9hEJoEwa4eUezPUlXRy/i5NpsKvo9jgKmoA==}
+    peerDependencies:
+      bare-abort-controller: '*'
+    peerDependenciesMeta:
+      bare-abort-controller:
+        optional: true
+
   baseline-browser-mapping@2.11.1:
     resolution: {integrity: sha512-HYXq73DDpCtNzOmrFsm9eSwCvWCql0RzqjpDzXN9EadiLJ4DNat0nsZ/Bzmy+Ud12mb4/zKDY0cQ805ZzN+i0A==}
     engines: {node: '>=6.0.0'}
     hasBin: true
 
-  basic-ftp@5.3.1:
-    resolution: {integrity: sha512-bopVNp6ugyA150DDuZfPFdt1KZ5a94ZDiwX4hMgZDzF+GttD80lEy8kj98kbyhLXnPvhtIo93mdnLIjpCAeeOw==}
-    engines: {node: '>=10.0.0'}
-
   bindings@1.5.0:
     resolution: {integrity: sha512-p2q/t/mhvuOj/UeLlV6566GD/guowlr0hHxClI0W9m7MWYkL1F0hLo+0Aexs9HSPCtR1SXQ0TD3MMKrXZajbiQ==}
 
@@ -2132,10 +2424,6 @@ packages:
   color-name@1.1.4:
     resolution: {integrity: sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==}
 
-  combined-stream@1.0.8:
-    resolution: {integrity: sha512-FQN4MRfuJeHf7cBbBMJFXhKSDq+2kAArBlmRBvcvFE5BB1HZKXtSFASDhdlz9zOYwxh8lDdnvmMOe/+5cdoEdg==}
-    engines: {node: '>= 0.8'}
-
   comma-separated-tokens@2.0.3:
     resolution: {integrity: sha512-Fu4hJdvzeylCfQPp9SGWidpzrMs7tTrlu6Vb8XGaRGck8QSNZJJp538Wrb60Lax4fPwR64ViY468OIUTbRlGZg==}
 
@@ -2160,9 +2448,6 @@ packages:
   convert-source-map@2.0.0:
     resolution: {integrity: sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==}
 
-  cookie-es@2.0.1:
-    resolution: {integrity: sha512-aVf4A4hI2w70LnF7GG+7xDQUkliwiXWXFvTjkip4+b64ygDQ2sJPRSKFDHbxn8o0xu9QzPkMuuiWIXyFSE2slA==}
-
   cross-spawn@7.0.6:
     resolution: {integrity: sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==}
     engines: {node: '>= 8'}
@@ -2173,10 +2458,6 @@ packages:
   damerau-levenshtein@1.0.8:
     resolution: {integrity: sha512-sdQSFB7+llfUcQHUQO3+B8ERRj0Oa4w9POWMI/puGtuf7gFywGmkaLCElnudfTiKZV+NvHqL0ifzdrI8Ro7ESA==}
 
-  data-uri-to-buffer@6.0.2:
-    resolution: {integrity: sha512-7hvf7/GW8e86rW0ptuwS3OcBGDjIi6SZva7hCyWC0yYry2cOPmLIjXAUHI6DK2HsnwJd9ifmt57i8eV2n4YNpw==}
-    engines: {node: '>= 14'}
-
   data-view-buffer@1.0.2:
     resolution: {integrity: sha512-EmKO5V3OLXh1rtK2wgXRansaK1/mtVdTUEiEI0W8RkvgT05kfxaH29PliLnpLP73yYO6142Q72QNa8Wx/A5CqQ==}
     engines: {node: '>= 0.4'}
@@ -2225,18 +2506,14 @@ packages:
     resolution: {integrity: sha512-rBMvIzlpA8v6E+SJZoo++HAYqsLrkg7MSfIinMPFhmkorw7X+dOXVJQs+QT69zGkzMyfDnIMN2Wid1+NbL3T+A==}
     engines: {node: '>= 0.4'}
 
+  define-lazy-prop@2.0.0:
+    resolution: {integrity: sha512-Ds09qNh8yw3khSjiJjiUInaGX9xlqZDY7JVryGxdxV7NPeuqQfplOpQ66yJFZut3jLa5zOwkXw1g9EI2uKh4Og==}
+    engines: {node: '>=8'}
+
   define-properties@1.2.1:
     resolution: {integrity: sha512-8QmQKqEASLd5nx0U1B1okLElbUuuttJ/AnYmRXbbbGDWh6uS208EjD4Xqq/I9wK7u0v6O08XhTWnt5XtEbR6Dg==}
     engines: {node: '>= 0.4'}
 
-  degenerator@5.0.1:
-    resolution: {integrity: sha512-TllpMR/t0M5sqCXfj85i4XaAzxmS5tVA16dqvdkMwGmzI+dXLXnw3J+3Vdv7VKw+ThlTMboK6i9rnZ6Nntj5CQ==}
-    engines: {node: '>= 14'}
-
-  delayed-stream@1.0.0:
-    resolution: {integrity: sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ==}
-    engines: {node: '>=0.4.0'}
-
   depd@1.1.2:
     resolution: {integrity: sha512-7emPTl6Dpo6JRXOXjLRxck+FlLRX5847cLKEn00PLAgc3g2hTZZgr+e4c2v6QpSmLeFP3n5yUo7ft6avBK/5jQ==}
     engines: {node: '>= 0.6'}
@@ -2311,6 +2588,9 @@ packages:
   es-module-lexer@1.4.1:
     resolution: {integrity: sha512-cXLGjP0c4T3flZJKQSuziYoq7MlT+rnvfZjfp7h+I7K9BNX54kP9nyWvdbwjQ4u1iWbOL4u96fgeZLToQlZC7w==}
 
+  es-module-lexer@1.5.0:
+    resolution: {integrity: sha512-pqrTKmwEIgafsYZAGw9kszYzmagcE/n4dbgwGWLEXg7J4QFJVQRBld8j3Q3GNez79jzxZshq0bcT962QHOghjw==}
+
   es-object-atoms@1.1.2:
     resolution: {integrity: sha512-HWcBoN6NileqtSydK2FqHbS/LoDd2pqrnQHLyJzBj4kOp/ky2MWMN694xOfkK8/SnUsW2DH7EfyVlydKCsm1Zw==}
     engines: {node: '>= 0.4'}
@@ -2355,13 +2635,8 @@ packages:
     resolution: {integrity: sha512-/veY75JbMK4j1yjvuUxuVsiS/hr/4iHs9FTT6cgTexxdE0Ly/glccBAkloH/DofkjRbZU3bnoj38mOmhkZ0lHw==}
     engines: {node: '>=12'}
 
-  escodegen@2.1.0:
-    resolution: {integrity: sha512-2NlIDTwUWJN0mRPQOdtQBzbUHvdGY2P1VXSyU83Q3xKxM7WHX2Ql8dKq782Q9TgQUNOLEzEYu9bzLNj1q88I5w==}
-    engines: {node: '>=6.0'}
-    hasBin: true
-
-  eslint-config-next@16.2.1:
-    resolution: {integrity: sha512-qhabwjQZ1Mk53XzXvmogf8KQ0tG0CQXF0CZ56+2/lVhmObgmaqj7x5A1DSrWdZd3kwI7GTPGUjFne+krRxYmFg==}
+  eslint-config-next@16.3.4:
+    resolution: {integrity: sha512-35/8RM10huEL9vlr8hUZMERMENHBrnyHN3ZZkF9efSgzGaqK34jIqry44A956//zriUhUAUW0XSkcolhrryqAA==}
     peerDependencies:
       eslint: '>=9.0.0'
       typescript: '>=3.3.1'
@@ -2464,11 +2739,6 @@ packages:
     resolution: {integrity: sha512-j6PAQ2uUr79PZhBjP5C5fhl8e39FmRnOjsD5lGnWrFU8i2G776tBK7+nP8KuQUTTyAZUwfQqXAgrVH5MbH9CYQ==}
     engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
 
-  esprima@4.0.1:
-    resolution: {integrity: sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==}
-    engines: {node: '>=4'}
-    hasBin: true
-
   esquery@1.7.0:
     resolution: {integrity: sha512-Ap6G0WQwcU/LHsvLwON1fAQX9Zp0A2Y6Y/cJBl9r/JbW90Zyg4/zbG6zzKa2OTALELarYHmKu0GhpM5EO+7T0g==}
     engines: {node: '>=0.10'}
@@ -2519,6 +2789,9 @@ packages:
   events-intercept@2.0.0:
     resolution: {integrity: sha512-blk1va0zol9QOrdZt0rFXo5KMkNPVSp92Eju/Qz8THwKWKRKeE0T8Br/1aW6+Edkyq9xHYgYxn2QtOnUKPUp+Q==}
 
+  events-universal@1.0.1:
+    resolution: {integrity: sha512-LUd5euvbMLpwOF8m6ivPCbhQeSiYVNb8Vs0fQ8QjXo0JTkEHpz8pxdQf0gStltaPpw0Cca8b39KxvK9cfKRiAw==}
+
   execa@3.2.0:
     resolution: {integrity: sha512-kJJfVbI/lZE1PZYDI5VPxp8zXPO9rtxOkhpZ0jMKha56AI9y2gGVC6bkukStQf0ka5Rh15BA5m7cCCH4jmHqkw==}
     engines: {node: ^8.12.0 || >=9.7.0}
@@ -2533,6 +2806,9 @@ packages:
   fast-deep-equal@3.1.3:
     resolution: {integrity: sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==}
 
+  fast-fifo@1.3.2:
+    resolution: {integrity: sha512-/d9sfos4yxzpwkDkuN7k2SqFKtYNmCTzgfEpz82x34IM9/zc8KGxQoXg1liNC/izpRM/MBdt44Nmx41ZWqk+FQ==}
+
   fast-glob@3.3.1:
     resolution: {integrity: sha512-kNFPyjhh5cKjrUltxs+wFx+ZkbRaxxmZ+X0ZU31SOsxCEtP9VPgtq2teZw1DebupL5GmDaNQ6yKMMVcM41iqDg==}
     engines: {node: '>=8.6.0'}
@@ -2588,10 +2864,6 @@ packages:
     resolution: {integrity: sha512-dKx12eRCVIzqCxFGplyFKJMPvLEWgmNtUrpTiJIR5u97zEhRG8ySrtboPHZXx7daLxQVrl643cTzbab2tkQjxg==}
     engines: {node: '>= 0.4'}
 
-  form-data@4.0.6:
-    resolution: {integrity: sha512-vKatAh4SlVfgbv+YtmhiRjhEMJsYpsG1Y2rMQtR+SVSbytsSD1YGzDIcrAJmdFec88u/+VoGmxnl+80gL1tRCQ==}
-    engines: {node: '>= 6'}
-
   framer-motion@12.42.2:
     resolution: {integrity: sha512-5XY9luDiu0oHfHBjpDthFMh0ES+122w6p/papSJBweMkO8Sn+PW2QaEgRblQBpWFnuvZS5qvarpt/hO2pjGmnw==}
     peerDependencies:
@@ -2756,6 +3028,10 @@ packages:
     resolution: {integrity: sha512-FJhYRoDaiatfEkUK8HKlicmu/3SGFD51q3itKDGoSTysQJBnfOcxU5GxnhE1E6soB76MbT0MBtnKJuXyAx+96Q==}
     engines: {node: '>=6'}
 
+  get-port@5.1.1:
+    resolution: {integrity: sha512-g/Q1aTSDOxFpchXC4i8ZWvxA1lnPqx/JHqcpIw0/LX9T8x/GBbi6YnlN5nhaKIFkT8oFsscUKgDJYxfwfS6QsQ==}
+    engines: {node: '>=8'}
+
   get-proto@1.0.1:
     resolution: {integrity: sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==}
     engines: {node: '>= 0.4'}
@@ -2775,10 +3051,6 @@ packages:
   get-tsconfig@4.14.0:
     resolution: {integrity: sha512-yTb+8DXzDREzgvYmh6s9vHsSVCHeC0G3PI5bEXNBHtmshPnO+S5O7qgLEOn0I5QvMy6kpZN8K1NKGyilLb93wA==}
 
-  get-uri@6.0.5:
-    resolution: {integrity: sha512-b1O07XYq8eRuVzBNgJLstU6FYc1tS6wnMtF1I1D9lE8LxZSOGZ7LhxN54yPP6mGw5f2CkXY2BQUL9Fx41qvcIg==}
-    engines: {node: '>= 14'}
-
   github-slugger@2.0.0:
     resolution: {integrity: sha512-IaOQ9puYtjrkq7Y0Ygl9KDZnrf/aiUJYUpVf89y8kyaxbRG7Y1SrX/jaumrv81vc61+kiMempujsM3Yw7w5qcw==}
 
@@ -2880,10 +3152,6 @@ packages:
     resolution: {integrity: sha512-ZTTX0MWrsQ2ZAhA1cejAwDLycFsd7I7nVtnkT3Ol0aqodaKW+0CTZDQ1uBv5whptCnc8e8HeRRJxRs0kmm/Qfw==}
     engines: {node: '>= 0.6'}
 
-  http-proxy-agent@7.0.2:
-    resolution: {integrity: sha512-T1gkAiYYDWYx3V5Bmyu7HcfcvL7mUrTWiM6yOfa3PIphViJ/gFPbvidQ+veqSOHci/PxBcDabeUNCzpOODJZig==}
-    engines: {node: '>= 14'}
-
   https-proxy-agent@7.0.6:
     resolution: {integrity: sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==}
     engines: {node: '>= 14'}
@@ -2926,10 +3194,6 @@ packages:
     resolution: {integrity: sha512-4gd7VpWNQNB4UKKCFFVcp1AVv+FMOgs9NKzjHKusc8jTMhd5eL1NqQqOpE0KzMds804/yHlglp3uxgluOqAPLw==}
     engines: {node: '>= 0.4'}
 
-  ip-address@10.2.0:
-    resolution: {integrity: sha512-/+S6j4E9AHvW9SWMSEY9Xfy66O5PWvVEJ08O0y5JGyEKQpojb0K0GKpz/v5HJ/G0vi3D2sjGK78119oXZeE0qA==}
-    engines: {node: '>= 12'}
-
   is-alphabetical@2.0.1:
     resolution: {integrity: sha512-FWyyY60MeTNyeSRpkM2Iry0G9hpr7/9kD40mD/cGQEuilcZYS4okz8SN2Q6rLCJ8gbCt6fN+rC+6tMGS99LaxQ==}
 
@@ -2978,6 +3242,11 @@ packages:
   is-decimal@2.0.1:
     resolution: {integrity: sha512-AAB9hiomQs5DXWcRB1rqsxGUstbRroFOPPVAomNk/3XHR5JyEZChOyTWe2oayKnsSsr/kcGqF+z6yuH6HHpN0A==}
 
+  is-docker@2.2.1:
+    resolution: {integrity: sha512-F+i2BKsFrH66iaUFc0woD8sLy8getkwTwtOBjvs56Cx4CgJDeKQeqfz8wAYiSb8JOprWhHH5p77PbmYCvvUuXQ==}
+    engines: {node: '>=8'}
+    hasBin: true
+
   is-document.all@1.0.0:
     resolution: {integrity: sha512-+XSoyS05OdBbhFuELhgTCpFNHkpBOJqtsZfUFFpe5QTw+9Sjbh8zitxhQkYAo6wV7e1Vb8cAPvpCk9jGam/82g==}
     engines: {node: '>= 0.4'}
@@ -3064,6 +3333,10 @@ packages:
     resolution: {integrity: sha512-mfcwb6IzQyOKTs84CQMrOwW4gQcaTOAWJ0zzJCl2WSPDrWk/OzDaImWFH3djXhb24g4eudZfLRozAvPGw4d9hQ==}
     engines: {node: '>= 0.4'}
 
+  is-wsl@2.2.0:
+    resolution: {integrity: sha512-fKzAra0rGJUUBwGBgNkHZuToZcn+TtXHpeCgmkMJMMYx1sQDYaCSyjJBSCa2nH1DGm7s3n1oBnohoVTBaN7Lww==}
+    engines: {node: '>=8'}
+
   isarray@2.0.5:
     resolution: {integrity: sha512-xHjhDr3cNBK0BzdUJSPXZntQUx/mwMS5Rw4A7lPJ90XGAO6ISP/ePDNuo0vhqOZU+UD5JoodwCAAoZQd3FeAKw==}
 
@@ -3081,15 +3354,14 @@ packages:
   jose@5.9.6:
     resolution: {integrity: sha512-AMlnetc9+CV9asI19zHmrgS/WYsWUwCn2R7RzlbJWD7F9eWYUTGyBmU9o6PxngtLGOiDGPRu+Uc4fhKzbpteZQ==}
 
+  jose@6.2.3:
+    resolution: {integrity: sha512-YYVDInQKFJfR/xa3ojUTl8c2KoTwiL1R5Wg9YCydwH0x0B9grbzlg5HC7mMjCtUJjbQ/YnGEZIhI5tCgfTb4Hw==}
+
   js-tokens@4.0.0:
     resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==}
 
-  js-yaml@4.1.1:
-    resolution: {integrity: sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==}
-    hasBin: true
-
-  js-yaml@4.3.0:
-    resolution: {integrity: sha512-1td788aAnnZ5qs7V2QIRl1owjtYpbKt749Y3xauqQgwIIGF/xXWz1wMTEBx5O3LK3lXLVuqXPdPxj2BoFHaW9Q==}
+  js-yaml@4.3.2:
+    resolution: {integrity: sha512-SFNOvSJ+Dgf/9An904Yx+CgSlIPCkIpao4qo51lpee25TIRejdH3rhR4EZMGoNx3/TP3O+wzWuiTFl4sqbltzA==}
     hasBin: true
 
   jsesc@3.1.0:
@@ -3121,9 +3393,15 @@ packages:
     engines: {node: '>=6'}
     hasBin: true
 
+  jsonc-parser@3.3.1:
+    resolution: {integrity: sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ==}
+
   jsonfile@6.2.1:
     resolution: {integrity: sha512-zwOTdL3rFQ/lRdBnntKVOX6k5cKJwEc1HdilT71BWEu7J41gXIB2MRp+vxduPSwZJPWBxEzv4yH1wYLJGUHX4Q==}
 
+  jsonlines@0.1.1:
+    resolution: {integrity: sha512-ekDrAGso79Cvf+dtm+mL8OBI2bmAOt3gssYs833De/C9NmIpWDWyUO4zPgB5x2/OhY366dkhgfPMYfwZF7yOZA==}
+
   jsx-ast-utils@3.3.5:
     resolution: {integrity: sha512-ZZow9HBI5O6EPgSJLUb8n2NKgmVWTwCvHGwFuJlMjvLFqlGG6pjirPhtdsseaLZjSibD8eegzmYpUZwoIlj2cQ==}
     engines: {node: '>=4.0'}
@@ -3226,6 +3504,9 @@ packages:
     resolution: {integrity: sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q==}
     hasBin: true
 
+  lru-cache@10.4.3:
+    resolution: {integrity: sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ==}
+
   lru-cache@11.5.2:
     resolution: {integrity: sha512-4pfM1Ff0x50o0tQwb5ucw/RzNyD0/YJME6IVcStalZuMWxdt3sR3huStTtxz4PUmvZfRguvDejasvQ2kifR11g==}
     engines: {node: 20 || >=22}
@@ -3237,10 +3518,6 @@ packages:
     resolution: {integrity: sha512-Jo6dJ04CmSjuznwJSS3pUeWmd/H0ffTlkXXgwZi+eq1UCmqQwCh+eLsYOYCwY991i2Fah4h1BEMCx4qThGbsiA==}
     engines: {node: '>=10'}
 
-  lru-cache@7.18.3:
-    resolution: {integrity: sha512-jumlc0BIUrS3qJGgIkWZsyfAM7NCWiBcCDhnd+3NNM5KbBmLTgHVfWBcg6W+rLUsIpzpERPsvwUP7CckAQSOoA==}
-    engines: {node: '>=12'}
-
   lucide-react@1.26.0:
     resolution: {integrity: sha512-raglYVR2+VkMfJL158krjVmE+rV5ST2lzA/KQm1FRSjMHT4MnWaegHxoVEpmc2So3nOEhp9oGejJwAPX8MoAjg==}
     peerDependencies:
@@ -3445,12 +3722,8 @@ packages:
     resolution: {integrity: sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg==}
     engines: {node: '>=6'}
 
-  minimatch@10.1.1:
-    resolution: {integrity: sha512-enIvLvRAFZYXJzkCYG5RKmPfrFArdLv+R+lbQ53BmIMLIry74bjKzX6iHAm8WYamJkhSSEabrWN5D97XnKObjQ==}
-    engines: {node: 20 || >=22}
-
-  minimatch@10.2.5:
-    resolution: {integrity: sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg==}
+  minimatch@10.2.6:
+    resolution: {integrity: sha512-vpLQEs+VLCr1nU0BXS07maYoFwlDAH0gngQuuttxIwutDFEMHq2blX+8vpgxDdK3J1PwjCJiep77OitTZ4Ll1A==}
     engines: {node: 18 || 20 || >=22}
 
   minimatch@3.1.5:
@@ -3505,8 +3778,8 @@ packages:
   ms@2.1.3:
     resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==}
 
-  nanoid@3.3.16:
-    resolution: {integrity: sha512-bzlKTyNJ7+LdGIIwy8ijFpIqEQIvafahV7eYykJ8Cvh42EdJeODoJ6gUJXpQJvej1BddH8OqTXZNE/KfbWAu8Q==}
+  nanoid@3.3.18:
+    resolution: {integrity: sha512-DTg4MJbGMWkfi6VZFdNt2/caMbQy4Ou+Op/hJQvGEWcnVfoA1QA+xzRKAzw9jD6+GVOOeYr/mIcuDSdug6F6+w==}
     engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
     hasBin: true
 
@@ -3518,18 +3791,14 @@ packages:
   natural-compare@1.4.0:
     resolution: {integrity: sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw==}
 
-  netmask@2.1.1:
-    resolution: {integrity: sha512-eonl3sLUha+S1GzTPxychyhnUzKyeQkZ7jLjKrBagJgPla13F+uQ71HgpFefyHgqrjEbCPkDArxYsjY8/+gLKA==}
-    engines: {node: '>= 0.4.0'}
-
   next-themes@0.4.6:
     resolution: {integrity: sha512-pZvgD5L0IEvX5/9GWyHMf3m8BKiVQwsCMHfoFosXtXBMnaS0ZnIJ9ST4b4NqLVKDEm8QBxoNNGNaBv2JNF6XNA==}
     peerDependencies:
       react: ^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc
       react-dom: ^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc
 
-  next@16.2.1:
-    resolution: {integrity: sha512-VaChzNL7o9rbfdt60HUj8tev4m6d7iC1igAy157526+cJlXOQu5LzsBXNT+xaJnTP/k+utSX5vMv7m0G+zKH+Q==}
+  next@16.3.4:
+    resolution: {integrity: sha512-/Ztf6CeRH+ejEXUrYtqI4gkS66eFIHuSwqi60RgcpWKodxFZx2/dqVCMKBwILfAHXQ+F1b1vAudgj3mnxqtoIA==}
     engines: {node: '>=20.9.0'}
     hasBin: true
     peerDependencies:
@@ -3649,6 +3918,10 @@ packages:
   oniguruma-to-es@4.3.6:
     resolution: {integrity: sha512-csuQ9x3Yr0cEIs/Zgx/OEt9iBw9vqIunAPQkx19R/fiMq2oGVTgcMqO/V3Ybqefr1TBvosI6jU539ksaBULJyA==}
 
+  open@8.4.0:
+    resolution: {integrity: sha512-XgFPPM+B28FtCCgSb9I+s9szOC1vZRSwgWsRUA5ylIxRTgKozqjOCrVOqGsYABPYK5qnfqClxZTFBa8PKt2v6Q==}
+    engines: {node: '>=12'}
+
   optionator@0.9.4:
     resolution: {integrity: sha512-6IpQ7mKUxRcZNLIObR0hz7lxsapSSIYNZJwXPGeF0mTVqGKFIXj1DQcMoT22S3ROcLyY/rz0PWaWZ9ayWmad9g==}
     engines: {node: '>= 0.8.0'}
@@ -3661,6 +3934,10 @@ packages:
     resolution: {integrity: sha512-19YVAg7T+WTrxggPukVq7DjTv6+PJ867TmhCvBsYwmbFCsZd344rq2Ld1p0wo8f8Qrrhgp82c6FJRqdXWtSEhg==}
     engines: {node: '>= 0.4'}
 
+  oxc-parser@0.121.0:
+    resolution: {integrity: sha512-ek9o58+SCv6AV7nchiAcUJy1DNE2CC5WRdBcO0mF+W4oRjNQfPO7b3pLjTHSFECpHkKGOZSQxx3hk8viIL5YCg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+
   oxc-transform@0.111.0:
     resolution: {integrity: sha512-oa5KKSDNLHZGaiqIGAbCWXeN9IJUAz9MElWcQX90epDxdKc9Hrt/BsLj3K4gDqfAYa5dwdH+ZCFJG9hR74fiGg==}
     engines: {node: ^20.19.0 || >=22.12.0}
@@ -3677,14 +3954,6 @@ packages:
     resolution: {integrity: sha512-LaNjtRWUBY++zB5nE/NwcaoMylSPk+S+ZHNB1TzdbMJMny6dynpAGt7X/tl/QYq3TIeE6nxHppbo2LGymrG5Pw==}
     engines: {node: '>=10'}
 
-  pac-proxy-agent@7.2.0:
-    resolution: {integrity: sha512-TEB8ESquiLMc0lV8vcd5Ql/JAKAoyzHFXaStwjkzpOpC5Yv+pIzLfHvjTSdf3vpa2bMiUQrg9i6276yn8666aA==}
-    engines: {node: '>= 14'}
-
-  pac-resolver@7.0.1:
-    resolution: {integrity: sha512-5NPgf87AT2STgwa2ntRMr45jTKrYBGkVU36yT0ig/n/GMAa3oPqhZfIQ2kMEimReg0+t9kZViDVZ83qfVUlckg==}
-    engines: {node: '>= 14'}
-
   parent-module@1.0.1:
     resolution: {integrity: sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g==}
     engines: {node: '>=6'}
@@ -3751,12 +4020,12 @@ packages:
     resolution: {integrity: sha512-/+5VFTchJDoVj3bhoqi6UeymcD00DAwb1nJwamzPvHEszJ4FpF6SNNbUbOS8yI56qHzdV8eK0qEfOSiodkTdxg==}
     engines: {node: '>= 0.4'}
 
-  postcss@8.4.31:
-    resolution: {integrity: sha512-PS08Iboia9mts/2ygV3eLpY5ghnUcfLV/EXTOW1E2qYxJKGGBUtNjN76FYHnMs36RmARn41bC0AZmn+rR0OVpQ==}
+  postcss@8.5.23:
+    resolution: {integrity: sha512-g50586zr4bZmwFiTlflMu8E0bDTb5I5gertgwAKmsdUlTQIhZtunzUlD1WSzwcVWPoAVpsrA6vlfCD7oXvRwgg==}
     engines: {node: ^10 || ^12 || >=14}
 
-  postcss@8.5.22:
-    resolution: {integrity: sha512-KBDEIpLrvpv16pp3K0Fw+UCoZfopFjjgeB+0tA/aaThfEE74kKDLrgg603YvOWJyg3+WYtyq3xYsQWsIyZlPqQ==}
+  postcss@8.5.26:
+    resolution: {integrity: sha512-u82N74LFzG8ca+dD8puPnplTXoGH4fTPpVGuIbt36G3qvNlkvfD0lEAZSxaly3KX8TS/L1A1gsCEmvKmBcVbkQ==}
     engines: {node: ^10 || ^12 || >=14}
 
   prelude-ls@1.2.1:
@@ -3776,13 +4045,6 @@ packages:
   property-information@7.2.0:
     resolution: {integrity: sha512-IAtzIB6sUiWaJYrX9smp3V46pBGbBeLFRGdh25kg1334VcBlD8HzhPeNIWQH9zhGmo2itIe25EHt9dQP7G5hmg==}
 
-  proxy-agent@6.4.0:
-    resolution: {integrity: sha512-u0piLU+nCOHMgGjRbimiXmA9kM/L9EHh3zL81xCdp7m+Y2pHIsnmbdDoEDoAz5geaonNR6q6+yOPQs6n4T6sBQ==}
-    engines: {node: '>= 14'}
-
-  proxy-from-env@1.1.0:
-    resolution: {integrity: sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg==}
-
   pump@3.0.4:
     resolution: {integrity: sha512-VS7sjc6KR7e1ukRFhQSY5LM2uBWAUPiOPa/A3mkKmiMwSmRFUITt0xuj+/lesgnCv+dPIEYlkzrcyXgquIHMcA==}
 
@@ -3957,6 +4219,10 @@ packages:
   safer-buffer@2.1.2:
     resolution: {integrity: sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==}
 
+  sandbox@4.1.0:
+    resolution: {integrity: sha512-kzDiAyvrGHGdrQ/7mT6Md18K9OUVgZW/KUKO/wBJ/gHouDh6oJPWcGWfOV5i7CSep2map3Pl7vV9gszm3Cvu7Q==}
+    hasBin: true
+
   scheduler@0.27.0:
     resolution: {integrity: sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q==}
 
@@ -3992,9 +4258,14 @@ packages:
   setprototypeof@1.1.1:
     resolution: {integrity: sha512-JvdAWfbXeIGaZ9cILp38HntZSFSo3mWg6xGcJJsd+d4aRMOqauag1C63dJfDw7OaMYwEbHMOxEZ1lqVRYP2OAw==}
 
-  sharp@0.34.5:
-    resolution: {integrity: sha512-Ou9I5Ft9WNcCbXrU9cMgPBcCK8LiwLqcbywW3t4oDV37n1pzpuNLsYiAV8eODnjbtQlSDwZ2cUEeQz4E54Hltg==}
-    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+  sharp@0.35.4:
+    resolution: {integrity: sha512-n++8XWcj+jCOr2IOl7h8LbKnGBDY4aPbmprMONBNFdn0ImXqpGVv5zliDs0V9HbmbCQLpbuo2ej9rAoOQTvMDA==}
+    engines: {node: '>=20.9.0'}
+    peerDependencies:
+      '@types/node': '*'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
 
   shebang-command@2.0.0:
     resolution: {integrity: sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==}
@@ -4031,30 +4302,14 @@ packages:
     resolution: {integrity: sha512-MY2/qGx4enyjprQnFaZsHib3Yadh3IXyV2C321GY0pjGfVBu4un0uDJkwgdxqO+Rdx8JMT8IfJIRwbYVz3Ob3Q==}
     engines: {node: '>=14'}
 
-  smart-buffer@4.2.0:
-    resolution: {integrity: sha512-94hK0Hh8rPqQl2xXc3HsaBoOXKV20MToPkcXvwbISWLEs+64sBq5kFgn2kJDHb1Pry9yrP0dxrCI9RRci7RXKg==}
-    engines: {node: '>= 6.0.0', npm: '>= 3.0.0'}
-
   smol-toml@1.5.2:
     resolution: {integrity: sha512-QlaZEqcAH3/RtNyet1IPIYPsEWAaYyXXv1Krsi+1L/QHppjX4Ifm8MQsBISz9vE8cHicIq3clogsheili5vhaQ==}
     engines: {node: '>= 18'}
 
-  socks-proxy-agent@8.0.5:
-    resolution: {integrity: sha512-HehCEsotFqbPW9sJ8WVYB6UbmIMv7kUUORIF2Nncq4VQvBfNBLibW9YZR5dlYCSUhwcD628pRllm7n+E+YTzJw==}
-    engines: {node: '>= 14'}
-
-  socks@2.8.9:
-    resolution: {integrity: sha512-LJhUYUvItdQ0LkJTmPeaEObWXAqFyfmP85x0tch/ez9cahmhlBBLbIqDFnvBnUJGagb0JbIQrkBs1wJ+yRYpEw==}
-    engines: {node: '>= 10.0.0', npm: '>= 3.0.0'}
-
   source-map-js@1.2.1:
     resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==}
     engines: {node: '>=0.10.0'}
 
-  source-map@0.6.1:
-    resolution: {integrity: sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==}
-    engines: {node: '>=0.10.0'}
-
   source-map@0.7.6:
     resolution: {integrity: sha512-i5uvt8C3ikiWeNZSVZNWcfZPItFQOsYTUAOkcUPGd8DqDy1uOUikjt5dG+uRlwyvR108Fb9DOd4GvXfT0N2/uQ==}
     engines: {node: '>= 12'}
@@ -4062,8 +4317,8 @@ packages:
   space-separated-tokens@2.0.2:
     resolution: {integrity: sha512-PEGlAwrG8yXGXRjW32fGbg66JAlOAwbObuqVoJpv/mRgoWDQfgH1wDPvtzWyUSNAXBGSk8h755YDbbcEy3SH2Q==}
 
-  srvx@0.8.9:
-    resolution: {integrity: sha512-wYc3VLZHRzwYrWJhkEqkhLb31TI0SOkfYZDkUhXdp3NoCnNS0FqajiQszZZjfow/VYEuc6Q5sZh9nM6kPy2NBQ==}
+  srvx@0.11.16:
+    resolution: {integrity: sha512-bp07zRuycfTY43IjAvvTFnmnJi8ikW0VFiHwOhhYcVW/L4xQ1XY4PAd4Nuum1rsA17C39zL7x+CDhrn5AL32Rw==}
     engines: {node: '>=20.16.0'}
     hasBin: true
 
@@ -4088,6 +4343,9 @@ packages:
     resolution: {integrity: sha512-HAGUASw8NT0k8JvIVutB2Y/9iBk7gpgEyAudXwNJmZERdMITGdajOa4VJfD/kNiA3TppQpTP4J+CtcHwdzKBAw==}
     deprecated: Deprecated. Use node:stream/promises and node:stream/consumers instead.
 
+  streamx@2.28.1:
+    resolution: {integrity: sha512-zEzXb0s5Cds7tqMH6rhZ05lcJydCWiQPEwiNngVqzsxCc962vLY4Uw+mW7od8kDH258k2Uz/JrOkdIAAhSh9VA==}
+
   string.prototype.includes@2.0.1:
     resolution: {integrity: sha512-o7+c9bW6zpAdJHTtujeePODAhkuicdAryFsfVKwA+wGw89wJ4GTY484WTucM9hLtDEOpOvI+aHnzqnC5lHp4Rg==}
     engines: {node: '>= 0.4'}
@@ -4163,14 +4421,15 @@ packages:
     resolution: {integrity: sha512-uxc/zpqFg6x7C8vOE7lh6Lbda8eEL9zmVm/PLeTPBRhh1xCgdWaQ+J1CUieGpIfm2HdtsUpRv+HshiasBMcc6A==}
     engines: {node: '>=6'}
 
-  tar@7.5.21:
-    resolution: {integrity: sha512-XdhtCvlMywwxpCW8YEq3lOXBJpUPTR2OHHcwLPO3HwsJqOHa2Ok/oJ7ruGzp+JrKoRPVCzJwAdEjqLW/vNRPHA==}
+  tar-stream@3.1.7:
+    resolution: {integrity: sha512-qJj60CXt7IU1Ffyc3NJMjh6EkuCFej46zUqJ4J7pqYlThyd9bO0XBTmcOIhSzZJVWfsLks0+nle/j538YAW9RQ==}
+
+  tar@7.5.22:
+    resolution: {integrity: sha512-MFO/QzvtAOmJbkhOaCTvbGcFN9L9b+JunIsDwaKljSOdcLMea3NJ1k9Usz/rjdfSXTq4dfzfeS7W4p4YOAAHeA==}
     engines: {node: '>=18'}
 
-  tar@7.5.7:
-    resolution: {integrity: sha512-fov56fJiRuThVFXD6o6/Q354S7pnWMJIVlDBYijsTNx6jKSE4pvrDTs6lUnmGvNyfJwFQQwWy3owKz1ucIhveQ==}
-    engines: {node: '>=18'}
-    deprecated: Old versions of tar are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me
+  text-decoder@1.2.7:
+    resolution: {integrity: sha512-vlLytXkeP4xvEq2otHeJfSQIRyWxo/oZGEbXrtEEF9Hnmrdly59sUbzZ/QgyWuLYHctCHxFF4tRQZNQ9k60ExQ==}
 
   throttleit@2.1.0:
     resolution: {integrity: sha512-nt6AMGKW1p/70DF/hGBdJB57B8Tspmbp5gfJ8ilhLnt7kkr2ye7hzD6NVG8GGErk2HWF34igrL2CXmNIkzKqKw==}
@@ -4283,14 +4542,18 @@ packages:
   undici-types@6.21.0:
     resolution: {integrity: sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==}
 
-  undici@5.28.4:
-    resolution: {integrity: sha512-72RFADWFqKmUb2hmmvNODKL3p9hcB6Gt2DOQMis1SEBaV6a4MH8soBvzg+95CYhCKPFedut2JY9bMfrDl9D23g==}
+  undici@5.29.0:
+    resolution: {integrity: sha512-raqeBD6NQK4SkWhQzeYKd1KmIG6dllBOTt55Rmkt4HtI9mwdWtJljnrXjAFUBLTSN67HWrOIZ3EPF4kjUw80Bg==}
     engines: {node: '>=14.0'}
 
-  undici@6.27.0:
-    resolution: {integrity: sha512-YmfV3YnEDzXRC5lZ2jWtWWHKGUm1zIt8AhesR1tens+HTNv+YZlN/dp6G727LOvMJ8xjP9Be7Y2Sdr96LDm+pg==}
+  undici@6.28.0:
+    resolution: {integrity: sha512-LIY910g9TI13YS95lrMFrs8Rm/u/irgHeTWoKCoteeJ04CUJ92eEfj0rVn+7VKMPBpUPiUoBKfhNyLI23EE/KA==}
     engines: {node: '>=18.17'}
 
+  undici@7.29.0:
+    resolution: {integrity: sha512-IDxfleLmmbSskfWSUATiN1nfn2rDuvnMOqb5CWR92iIfojA0Ud+ulOAAEQ57LPr9rWmsreUyf5lwyao+7GNNVw==}
+    engines: {node: '>=20.18.1'}
+
   unified@11.0.5:
     resolution: {integrity: sha512-xKvGhPWw3k84Qjh8bI3ZeJjqnyadK+GEFtazSfZv/rKeTkTjOJho6mFqh2SM96iIcZokxiOpg78GazTSg8+KHA==}
 
@@ -4355,8 +4618,12 @@ packages:
       '@types/react':
         optional: true
 
-  vercel@50.37.0:
-    resolution: {integrity: sha512-GVeZ/5vw1dZXw2S3aEVmo05BbfspKc+gb3+h6hTz0Dm1IW3lCpAI7A/FXor8XDMHy64PhOjYCwpEu6Qnr3Cz+Q==}
+  uuid@14.0.1:
+    resolution: {integrity: sha512-6ZxzVpzDXDa3bJWaHilVayA+BH/1zmxCJoVgvmqJnid/gPoKHxUrS/aC/T6LGQtNHT+XHG9fXPJB4d+IrU30Ew==}
+    hasBin: true
+
+  vercel@59.11.1:
+    resolution: {integrity: sha512-vGmxxo6NcqfMcHMJ2rtTsOLTdYjb/Jp49eAMh/zpTvvDS7BCqQdCLpeMTxxZ+5yezQWDKvYstzueRicEuNfubg==}
     engines: {node: '>= 18'}
     hasBin: true
 
@@ -4409,6 +4676,18 @@ packages:
   wrappy@1.0.2:
     resolution: {integrity: sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==}
 
+  ws@8.21.3:
+    resolution: {integrity: sha512-201TZ/kPWxoPr/OKWjquZR1SWKXcvxdH+e1xrx89b3YbmzLMFCLfnaG1HFIgWzJOEWZ7MvpK++odZufgYR50Rw==}
+    engines: {node: '>=10.0.0'}
+    peerDependencies:
+      bufferutil: ^4.0.1
+      utf-8-validate: '>=5.0.2'
+    peerDependenciesMeta:
+      bufferutil:
+        optional: true
+      utf-8-validate:
+        optional: true
+
   xdg-app-paths@5.1.0:
     resolution: {integrity: sha512-RAQ3WkPf4KTU1A8RtFx3gWywzVKe00tfOPFfl2NDGqbIFENQO4kqAJp7mhQjNj/33W5x5hiWWUdyfPq/5SU3QA==}
     engines: {node: '>=6'}
@@ -4456,6 +4735,9 @@ packages:
   zod@3.22.4:
     resolution: {integrity: sha512-iC+8Io04lddc+mVqQ9AZ7OQ2MrUKGN+oIQyq1vemgt46jwCwLfhq7/pwnBnNXXXZb8VTVLKwp9EDkx+ryxIWmg==}
 
+  zod@4.1.11:
+    resolution: {integrity: sha512-WPsqwxITS2tzx1bzhIKsEs19ABD5vmCVa4xBo2tq/SrV4RNZtfws1EnCWQXM6yh8bD08a1idvkB5MZSBiZsjwg==}
+
   zod@4.4.3:
     resolution: {integrity: sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==}
 
@@ -4591,7 +4873,7 @@ snapshots:
       tslib: 2.8.1
     optional: true
 
-  '@emnapi/runtime@1.11.2':
+  '@emnapi/runtime@1.11.3':
     dependencies:
       tslib: 2.8.1
     optional: true
@@ -4762,6 +5044,11 @@ snapshots:
       eslint: 9.39.5(jiti@2.7.0)
       eslint-visitor-keys: 3.4.3
 
+  '@eslint-community/eslint-utils@4.9.1(eslint@9.39.5(jiti@2.7.0))':
+    dependencies:
+      eslint: 9.39.5(jiti@2.7.0)
+      eslint-visitor-keys: 3.4.3
+
   '@eslint-community/regexpp@4.12.2': {}
 
   '@eslint/config-array@0.21.2':
@@ -4788,7 +5075,7 @@ snapshots:
       globals: 14.0.0
       ignore: 5.3.2
       import-fresh: 3.3.1
-      js-yaml: 4.3.0
+      js-yaml: 4.3.2
       minimatch: 3.1.5
       strip-json-comments: 3.1.1
     transitivePeerDependencies:
@@ -4849,110 +5136,112 @@ snapshots:
 
   '@humanwhocodes/retry@0.4.3': {}
 
-  '@iarna/toml@2.2.5': {}
-
   '@img/colour@1.1.0':
     optional: true
 
-  '@img/sharp-darwin-arm64@0.34.5':
+  '@img/sharp-darwin-arm64@0.35.4':
     optionalDependencies:
-      '@img/sharp-libvips-darwin-arm64': 1.2.4
+      '@img/sharp-libvips-darwin-arm64': 1.3.3
     optional: true
 
-  '@img/sharp-darwin-x64@0.34.5':
+  '@img/sharp-darwin-x64@0.35.4':
     optionalDependencies:
-      '@img/sharp-libvips-darwin-x64': 1.2.4
+      '@img/sharp-libvips-darwin-x64': 1.3.3
     optional: true
 
-  '@img/sharp-libvips-darwin-arm64@1.2.4':
-    optional: true
-
-  '@img/sharp-libvips-darwin-x64@1.2.4':
-    optional: true
-
-  '@img/sharp-libvips-linux-arm64@1.2.4':
-    optional: true
-
-  '@img/sharp-libvips-linux-arm@1.2.4':
-    optional: true
-
-  '@img/sharp-libvips-linux-ppc64@1.2.4':
-    optional: true
-
-  '@img/sharp-libvips-linux-riscv64@1.2.4':
-    optional: true
-
-  '@img/sharp-libvips-linux-s390x@1.2.4':
-    optional: true
-
-  '@img/sharp-libvips-linux-x64@1.2.4':
-    optional: true
-
-  '@img/sharp-libvips-linuxmusl-arm64@1.2.4':
-    optional: true
-
-  '@img/sharp-libvips-linuxmusl-x64@1.2.4':
-    optional: true
-
-  '@img/sharp-linux-arm64@0.34.5':
-    optionalDependencies:
-      '@img/sharp-libvips-linux-arm64': 1.2.4
-    optional: true
-
-  '@img/sharp-linux-arm@0.34.5':
-    optionalDependencies:
-      '@img/sharp-libvips-linux-arm': 1.2.4
-    optional: true
-
-  '@img/sharp-linux-ppc64@0.34.5':
-    optionalDependencies:
-      '@img/sharp-libvips-linux-ppc64': 1.2.4
-    optional: true
-
-  '@img/sharp-linux-riscv64@0.34.5':
-    optionalDependencies:
-      '@img/sharp-libvips-linux-riscv64': 1.2.4
-    optional: true
-
-  '@img/sharp-linux-s390x@0.34.5':
-    optionalDependencies:
-      '@img/sharp-libvips-linux-s390x': 1.2.4
-    optional: true
-
-  '@img/sharp-linux-x64@0.34.5':
-    optionalDependencies:
-      '@img/sharp-libvips-linux-x64': 1.2.4
-    optional: true
-
-  '@img/sharp-linuxmusl-arm64@0.34.5':
-    optionalDependencies:
-      '@img/sharp-libvips-linuxmusl-arm64': 1.2.4
-    optional: true
-
-  '@img/sharp-linuxmusl-x64@0.34.5':
-    optionalDependencies:
-      '@img/sharp-libvips-linuxmusl-x64': 1.2.4
-    optional: true
-
-  '@img/sharp-wasm32@0.34.5':
+  '@img/sharp-freebsd-wasm32@0.35.4':
     dependencies:
-      '@emnapi/runtime': 1.11.2
+      '@img/sharp-wasm32': 0.35.4
     optional: true
 
-  '@img/sharp-win32-arm64@0.34.5':
+  '@img/sharp-libvips-darwin-arm64@1.3.3':
     optional: true
 
-  '@img/sharp-win32-ia32@0.34.5':
+  '@img/sharp-libvips-darwin-x64@1.3.3':
     optional: true
 
-  '@img/sharp-win32-x64@0.34.5':
+  '@img/sharp-libvips-linux-arm64@1.3.3':
     optional: true
 
-  '@isaacs/balanced-match@4.0.1': {}
+  '@img/sharp-libvips-linux-arm@1.3.3':
+    optional: true
 
-  '@isaacs/brace-expansion@5.0.1':
+  '@img/sharp-libvips-linux-ppc64@1.3.3':
+    optional: true
+
+  '@img/sharp-libvips-linux-riscv64@1.3.3':
+    optional: true
+
+  '@img/sharp-libvips-linux-s390x@1.3.3':
+    optional: true
+
+  '@img/sharp-libvips-linux-x64@1.3.3':
+    optional: true
+
+  '@img/sharp-libvips-linuxmusl-arm64@1.3.3':
+    optional: true
+
+  '@img/sharp-libvips-linuxmusl-x64@1.3.3':
+    optional: true
+
+  '@img/sharp-linux-arm64@0.35.4':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-arm64': 1.3.3
+    optional: true
+
+  '@img/sharp-linux-arm@0.35.4':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-arm': 1.3.3
+    optional: true
+
+  '@img/sharp-linux-ppc64@0.35.4':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-ppc64': 1.3.3
+    optional: true
+
+  '@img/sharp-linux-riscv64@0.35.4':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-riscv64': 1.3.3
+    optional: true
+
+  '@img/sharp-linux-s390x@0.35.4':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-s390x': 1.3.3
+    optional: true
+
+  '@img/sharp-linux-x64@0.35.4':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-x64': 1.3.3
+    optional: true
+
+  '@img/sharp-linuxmusl-arm64@0.35.4':
+    optionalDependencies:
+      '@img/sharp-libvips-linuxmusl-arm64': 1.3.3
+    optional: true
+
+  '@img/sharp-linuxmusl-x64@0.35.4':
+    optionalDependencies:
+      '@img/sharp-libvips-linuxmusl-x64': 1.3.3
+    optional: true
+
+  '@img/sharp-wasm32@0.35.4':
     dependencies:
-      '@isaacs/balanced-match': 4.0.1
+      '@emnapi/runtime': 1.11.3
+    optional: true
+
+  '@img/sharp-webcontainers-wasm32@0.35.4':
+    dependencies:
+      '@img/sharp-wasm32': 0.35.4
+    optional: true
+
+  '@img/sharp-win32-arm64@0.35.4':
+    optional: true
+
+  '@img/sharp-win32-ia32@0.35.4':
+    optional: true
+
+  '@img/sharp-win32-x64@0.35.4':
+    optional: true
 
   '@isaacs/fs-minipass@4.0.1':
     dependencies:
@@ -4985,7 +5274,7 @@ snapshots:
       node-fetch: 2.7.0
       nopt: 8.1.0
       semver: 7.8.5
-      tar: 7.5.21
+      tar: 7.5.22
     transitivePeerDependencies:
       - encoding
       - supports-color
@@ -5020,6 +5309,57 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  '@napi-rs/keyring-darwin-arm64@1.2.0':
+    optional: true
+
+  '@napi-rs/keyring-darwin-x64@1.2.0':
+    optional: true
+
+  '@napi-rs/keyring-freebsd-x64@1.2.0':
+    optional: true
+
+  '@napi-rs/keyring-linux-arm-gnueabihf@1.2.0':
+    optional: true
+
+  '@napi-rs/keyring-linux-arm64-gnu@1.2.0':
+    optional: true
+
+  '@napi-rs/keyring-linux-arm64-musl@1.2.0':
+    optional: true
+
+  '@napi-rs/keyring-linux-riscv64-gnu@1.2.0':
+    optional: true
+
+  '@napi-rs/keyring-linux-x64-gnu@1.2.0':
+    optional: true
+
+  '@napi-rs/keyring-linux-x64-musl@1.2.0':
+    optional: true
+
+  '@napi-rs/keyring-win32-arm64-msvc@1.2.0':
+    optional: true
+
+  '@napi-rs/keyring-win32-ia32-msvc@1.2.0':
+    optional: true
+
+  '@napi-rs/keyring-win32-x64-msvc@1.2.0':
+    optional: true
+
+  '@napi-rs/keyring@1.2.0':
+    optionalDependencies:
+      '@napi-rs/keyring-darwin-arm64': 1.2.0
+      '@napi-rs/keyring-darwin-x64': 1.2.0
+      '@napi-rs/keyring-freebsd-x64': 1.2.0
+      '@napi-rs/keyring-linux-arm-gnueabihf': 1.2.0
+      '@napi-rs/keyring-linux-arm64-gnu': 1.2.0
+      '@napi-rs/keyring-linux-arm64-musl': 1.2.0
+      '@napi-rs/keyring-linux-riscv64-gnu': 1.2.0
+      '@napi-rs/keyring-linux-x64-gnu': 1.2.0
+      '@napi-rs/keyring-linux-x64-musl': 1.2.0
+      '@napi-rs/keyring-win32-arm64-msvc': 1.2.0
+      '@napi-rs/keyring-win32-ia32-msvc': 1.2.0
+      '@napi-rs/keyring-win32-x64-msvc': 1.2.0
+
   '@napi-rs/wasm-runtime@1.1.6(@emnapi/core@1.10.0)(@emnapi/runtime@1.10.0)':
     dependencies:
       '@emnapi/core': 1.10.0
@@ -5027,41 +5367,44 @@ snapshots:
       '@tybys/wasm-util': 0.10.3
     optional: true
 
-  '@napi-rs/wasm-runtime@1.1.6(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.2)':
+  '@napi-rs/wasm-runtime@1.1.6(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)':
     dependencies:
       '@emnapi/core': 1.10.0
-      '@emnapi/runtime': 1.11.2
+      '@emnapi/runtime': 1.11.3
       '@tybys/wasm-util': 0.10.3
     optional: true
 
-  '@next/env@16.2.1': {}
+  '@next/env@16.3.4': {}
 
-  '@next/eslint-plugin-next@16.2.1':
+  '@next/eslint-plugin-next@16.3.4(eslint@9.39.5(jiti@2.7.0))':
     dependencies:
+      '@eslint-community/eslint-utils': 4.9.1(eslint@9.39.5(jiti@2.7.0))
       fast-glob: 3.3.1
+    transitivePeerDependencies:
+      - eslint
 
-  '@next/swc-darwin-arm64@16.2.1':
+  '@next/swc-darwin-arm64@16.3.4':
     optional: true
 
-  '@next/swc-darwin-x64@16.2.1':
+  '@next/swc-darwin-x64@16.3.4':
     optional: true
 
-  '@next/swc-linux-arm64-gnu@16.2.1':
+  '@next/swc-linux-arm64-gnu@16.3.4':
     optional: true
 
-  '@next/swc-linux-arm64-musl@16.2.1':
+  '@next/swc-linux-arm64-musl@16.3.4':
     optional: true
 
-  '@next/swc-linux-x64-gnu@16.2.1':
+  '@next/swc-linux-x64-gnu@16.3.4':
     optional: true
 
-  '@next/swc-linux-x64-musl@16.2.1':
+  '@next/swc-linux-x64-musl@16.3.4':
     optional: true
 
-  '@next/swc-win32-arm64-msvc@16.2.1':
+  '@next/swc-win32-arm64-msvc@16.3.4':
     optional: true
 
-  '@next/swc-win32-x64-msvc@16.2.1':
+  '@next/swc-win32-x64-msvc@16.3.4':
     optional: true
 
   '@nodelib/fs.scandir@2.1.5':
@@ -5080,8 +5423,75 @@ snapshots:
 
   '@orama/orama@3.1.18': {}
 
+  '@oxc-parser/binding-android-arm-eabi@0.121.0':
+    optional: true
+
+  '@oxc-parser/binding-android-arm64@0.121.0':
+    optional: true
+
+  '@oxc-parser/binding-darwin-arm64@0.121.0':
+    optional: true
+
+  '@oxc-parser/binding-darwin-x64@0.121.0':
+    optional: true
+
+  '@oxc-parser/binding-freebsd-x64@0.121.0':
+    optional: true
+
+  '@oxc-parser/binding-linux-arm-gnueabihf@0.121.0':
+    optional: true
+
+  '@oxc-parser/binding-linux-arm-musleabihf@0.121.0':
+    optional: true
+
+  '@oxc-parser/binding-linux-arm64-gnu@0.121.0':
+    optional: true
+
+  '@oxc-parser/binding-linux-arm64-musl@0.121.0':
+    optional: true
+
+  '@oxc-parser/binding-linux-ppc64-gnu@0.121.0':
+    optional: true
+
+  '@oxc-parser/binding-linux-riscv64-gnu@0.121.0':
+    optional: true
+
+  '@oxc-parser/binding-linux-riscv64-musl@0.121.0':
+    optional: true
+
+  '@oxc-parser/binding-linux-s390x-gnu@0.121.0':
+    optional: true
+
+  '@oxc-parser/binding-linux-x64-gnu@0.121.0':
+    optional: true
+
+  '@oxc-parser/binding-linux-x64-musl@0.121.0':
+    optional: true
+
+  '@oxc-parser/binding-openharmony-arm64@0.121.0':
+    optional: true
+
+  '@oxc-parser/binding-wasm32-wasi@0.121.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)':
+    dependencies:
+      '@napi-rs/wasm-runtime': 1.1.6(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)
+    transitivePeerDependencies:
+      - '@emnapi/core'
+      - '@emnapi/runtime'
+    optional: true
+
+  '@oxc-parser/binding-win32-arm64-msvc@0.121.0':
+    optional: true
+
+  '@oxc-parser/binding-win32-ia32-msvc@0.121.0':
+    optional: true
+
+  '@oxc-parser/binding-win32-x64-msvc@0.121.0':
+    optional: true
+
   '@oxc-project/types@0.110.0': {}
 
+  '@oxc-project/types@0.121.0': {}
+
   '@oxc-transform/binding-android-arm-eabi@0.111.0':
     optional: true
 
@@ -5130,9 +5540,9 @@ snapshots:
   '@oxc-transform/binding-openharmony-arm64@0.111.0':
     optional: true
 
-  '@oxc-transform/binding-wasm32-wasi@0.111.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.2)':
+  '@oxc-transform/binding-wasm32-wasi@0.111.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)':
     dependencies:
-      '@napi-rs/wasm-runtime': 1.1.6(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.2)
+      '@napi-rs/wasm-runtime': 1.1.6(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)
     transitivePeerDependencies:
       - '@emnapi/core'
       - '@emnapi/runtime'
@@ -5532,9 +5942,9 @@ snapshots:
   '@rolldown/binding-openharmony-arm64@1.0.0-rc.1':
     optional: true
 
-  '@rolldown/binding-wasm32-wasi@1.0.0-rc.1(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.2)':
+  '@rolldown/binding-wasm32-wasi@1.0.0-rc.1(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)':
     dependencies:
-      '@napi-rs/wasm-runtime': 1.1.6(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.2)
+      '@napi-rs/wasm-runtime': 1.1.6(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)
     transitivePeerDependencies:
       - '@emnapi/core'
       - '@emnapi/runtime'
@@ -5600,7 +6010,7 @@ snapshots:
 
   '@standard-schema/spec@1.1.0': {}
 
-  '@swc/helpers@0.5.15':
+  '@swc/helpers@0.5.23':
     dependencies:
       tslib: 2.8.1
 
@@ -5670,12 +6080,10 @@ snapshots:
       '@alloc/quick-lru': 5.2.0
       '@tailwindcss/node': 4.3.3
       '@tailwindcss/oxide': 4.3.3
-      postcss: 8.5.22
+      postcss: 8.5.26
       tailwindcss: 4.3.3
 
-  '@tootallnate/once@2.0.0': {}
-
-  '@tootallnate/quickjs-emscripten@0.23.0': {}
+  '@tootallnate/once@2.0.1': {}
 
   '@ts-morph/common@0.11.1':
     dependencies:
@@ -5802,7 +6210,7 @@ snapshots:
       '@typescript-eslint/types': 8.65.0
       '@typescript-eslint/visitor-keys': 8.65.0
       debug: 4.4.3
-      minimatch: 10.2.5
+      minimatch: 10.2.6
       semver: 7.8.5
       tinyglobby: 0.2.17
       ts-api-utils: 2.5.0(typescript@5.9.3)
@@ -5898,19 +6306,21 @@ snapshots:
   '@unrs/resolver-binding-win32-x64-msvc@1.12.2':
     optional: true
 
-  '@vercel/backends@0.0.51(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.2)(typescript@5.9.3)':
+  '@vercel/backends@7.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)':
     dependencies:
-      '@vercel/build-utils': 13.10.0
-      '@vercel/nft': 1.5.0
+      '@vercel/build-utils': 14.9.0
+      '@vercel/nft': 1.10.0
+      '@vercel/static-config': 3.4.3(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)
       execa: 3.2.0
       fs-extra: 11.1.0
-      oxc-transform: 0.111.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.2)
+      get-port: 5.1.1
+      oxc-transform: 0.111.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)
       path-to-regexp: 8.3.0
       resolve.exports: 2.0.3
-      rolldown: 1.0.0-rc.1(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.2)
-      srvx: 0.8.9
+      rolldown: 1.0.0-rc.1(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)
+      srvx: 0.11.16
+      ts-morph: 12.0.0
       tsx: 4.21.0
-      typescript: 5.9.3
       zod: 3.22.4
     transitivePeerDependencies:
       - '@emnapi/core'
@@ -5919,22 +6329,59 @@ snapshots:
       - rollup
       - supports-color
 
-  '@vercel/blob@2.3.0':
+  '@vercel/blob@2.8.0':
     dependencies:
+      '@vercel/oidc': 3.8.5
       async-retry: 1.3.3
       is-buffer: 2.0.5
       is-node-process: 1.2.0
       throttleit: 2.1.0
-      undici: 6.27.0
+      undici: 6.28.0
 
-  '@vercel/build-utils@13.10.0':
+  '@vercel/build-utils@14.9.0':
     dependencies:
-      '@vercel/python-analysis': 0.11.0
+      cjs-module-lexer: 1.2.3
+      es-module-lexer: 1.5.0
 
-  '@vercel/cervel@0.0.38(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.2)(typescript@5.9.3)':
+  '@vercel/cervel@0.1.59(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)':
     dependencies:
-      '@vercel/backends': 0.0.51(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.2)(typescript@5.9.3)
-      typescript: 5.9.3
+      '@vercel/backends': 7.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)
+    transitivePeerDependencies:
+      - '@emnapi/core'
+      - '@emnapi/runtime'
+      - '@vercel/build-utils'
+      - encoding
+      - rollup
+      - supports-color
+
+  '@vercel/cli-auth@0.3.5':
+    dependencies:
+      '@napi-rs/keyring': 1.2.0
+      '@vercel/cli-config': 0.2.4
+      async-listen: 3.0.0
+      open: 8.4.0
+      zod: 4.1.11
+
+  '@vercel/cli-config@0.2.4':
+    dependencies:
+      xdg-app-paths: 5.1.0
+      zod: 4.1.11
+
+  '@vercel/cli-exec@1.0.1':
+    dependencies:
+      execa: 5.1.1
+
+  '@vercel/container@7.0.0(@vercel/build-utils@14.9.0)':
+    dependencies:
+      '@vercel/build-utils': 14.9.0
+
+  '@vercel/detect-agent@1.2.5': {}
+
+  '@vercel/elysia@7.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)':
+    dependencies:
+      '@vercel/build-utils': 14.9.0
+      '@vercel/node': 12.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)
+      '@vercel/static-config': 3.4.3(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)
     transitivePeerDependencies:
       - '@emnapi/core'
       - '@emnapi/runtime'
@@ -5942,25 +6389,15 @@ snapshots:
       - rollup
       - supports-color
 
-  '@vercel/detect-agent@1.2.1': {}
+  '@vercel/error-utils@2.2.1': {}
 
-  '@vercel/elysia@0.1.53':
+  '@vercel/express@7.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)':
     dependencies:
-      '@vercel/node': 5.6.20
-      '@vercel/static-config': 3.2.0
-    transitivePeerDependencies:
-      - encoding
-      - rollup
-      - supports-color
-
-  '@vercel/error-utils@2.0.3': {}
-
-  '@vercel/express@0.1.63(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.2)(typescript@5.9.3)':
-    dependencies:
-      '@vercel/cervel': 0.0.38(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.2)(typescript@5.9.3)
-      '@vercel/nft': 1.5.0
-      '@vercel/node': 5.6.20
-      '@vercel/static-config': 3.2.0
+      '@vercel/build-utils': 14.9.0
+      '@vercel/cervel': 0.1.59(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)
+      '@vercel/nft': 1.10.0
+      '@vercel/node': 12.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)
+      '@vercel/static-config': 3.4.3(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)
       fs-extra: 11.1.0
       path-to-regexp: 8.3.0
       ts-morph: 12.0.0
@@ -5971,20 +6408,22 @@ snapshots:
       - encoding
       - rollup
       - supports-color
-      - typescript
 
-  '@vercel/fastify@0.1.56':
+  '@vercel/fastify@7.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)':
     dependencies:
-      '@vercel/node': 5.6.20
-      '@vercel/static-config': 3.2.0
+      '@vercel/build-utils': 14.9.0
+      '@vercel/node': 12.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)
+      '@vercel/static-config': 3.4.3(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)
     transitivePeerDependencies:
+      - '@emnapi/core'
+      - '@emnapi/runtime'
       - encoding
       - rollup
       - supports-color
 
   '@vercel/fun@1.3.0':
     dependencies:
-      '@tootallnate/once': 2.0.0
+      '@tootallnate/once': 2.0.1
       async-listen: 1.2.0
       debug: 4.3.4
       generic-pool: 3.4.2
@@ -5996,7 +6435,7 @@ snapshots:
       semver: 7.5.4
       stat-mode: 0.3.0
       stream-to-promise: 2.2.0
-      tar: 7.5.7
+      tar: 7.5.22
       tinyexec: 0.3.2
       tree-kill: 1.2.2
       uid-promise: 1.0.0
@@ -6006,75 +6445,94 @@ snapshots:
       - encoding
       - supports-color
 
-  '@vercel/gatsby-plugin-vercel-analytics@1.0.11':
+  '@vercel/gatsby-plugin-vercel-analytics@1.0.12':
     dependencies:
       web-vitals: 0.2.4
 
-  '@vercel/gatsby-plugin-vercel-builder@2.1.4':
+  '@vercel/gatsby-plugin-vercel-builder@2.2.52':
     dependencies:
       '@sinclair/typebox': 0.25.24
-      '@vercel/build-utils': 13.10.0
+      '@vercel/build-utils': 14.9.0
       esbuild: 0.27.0
       etag: 1.8.1
       fs-extra: 11.1.0
 
-  '@vercel/go@3.4.6': {}
-
-  '@vercel/h3@0.1.62':
+  '@vercel/go@10.0.0(@vercel/build-utils@14.9.0)':
     dependencies:
-      '@vercel/node': 5.6.20
-      '@vercel/static-config': 3.2.0
+      '@vercel/build-utils': 14.9.0
+
+  '@vercel/h3@7.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)':
+    dependencies:
+      '@vercel/build-utils': 14.9.0
+      '@vercel/node': 12.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)
+      '@vercel/static-config': 3.4.3(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)
     transitivePeerDependencies:
+      - '@emnapi/core'
+      - '@emnapi/runtime'
       - encoding
       - rollup
       - supports-color
 
-  '@vercel/hono@0.2.56':
+  '@vercel/hono@7.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)':
     dependencies:
-      '@vercel/nft': 1.5.0
-      '@vercel/node': 5.6.20
-      '@vercel/static-config': 3.2.0
+      '@vercel/build-utils': 14.9.0
+      '@vercel/nft': 1.10.0
+      '@vercel/node': 12.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)
+      '@vercel/static-config': 3.4.3(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)
       fs-extra: 11.1.0
       path-to-regexp: 8.3.0
       ts-morph: 12.0.0
       zod: 3.22.4
     transitivePeerDependencies:
+      - '@emnapi/core'
+      - '@emnapi/runtime'
       - encoding
       - rollup
       - supports-color
 
-  '@vercel/hydrogen@1.3.6':
+  '@vercel/hydrogen@8.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)':
     dependencies:
-      '@vercel/static-config': 3.2.0
+      '@vercel/build-utils': 14.9.0
+      '@vercel/static-config': 3.4.3(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)
       ts-morph: 12.0.0
+    transitivePeerDependencies:
+      - '@emnapi/core'
+      - '@emnapi/runtime'
 
-  '@vercel/koa@0.1.36':
+  '@vercel/koa@7.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)':
     dependencies:
-      '@vercel/node': 5.6.20
-      '@vercel/static-config': 3.2.0
+      '@vercel/build-utils': 14.9.0
+      '@vercel/node': 12.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)
+      '@vercel/static-config': 3.4.3(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)
+    transitivePeerDependencies:
+      - '@emnapi/core'
+      - '@emnapi/runtime'
+      - encoding
+      - rollup
+      - supports-color
+
+  '@vercel/nestjs@7.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)':
+    dependencies:
+      '@vercel/build-utils': 14.9.0
+      '@vercel/node': 12.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)
+      '@vercel/static-config': 3.4.3(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)
+    transitivePeerDependencies:
+      - '@emnapi/core'
+      - '@emnapi/runtime'
+      - encoding
+      - rollup
+      - supports-color
+
+  '@vercel/next@11.0.0(@vercel/build-utils@14.9.0)':
+    dependencies:
+      '@vercel/build-utils': 14.9.0
+      '@vercel/nft': 1.10.0
     transitivePeerDependencies:
       - encoding
       - rollup
       - supports-color
 
-  '@vercel/nestjs@0.2.57':
-    dependencies:
-      '@vercel/node': 5.6.20
-      '@vercel/static-config': 3.2.0
-    transitivePeerDependencies:
-      - encoding
-      - rollup
-      - supports-color
-
-  '@vercel/next@4.16.3':
-    dependencies:
-      '@vercel/nft': 1.5.0
-    transitivePeerDependencies:
-      - encoding
-      - rollup
-      - supports-color
-
-  '@vercel/nft@1.5.0':
+  '@vercel/nft@1.10.0':
     dependencies:
       '@mapbox/node-pre-gyp': 2.0.3
       '@rollup/pluginutils': 5.4.0
@@ -6093,16 +6551,16 @@ snapshots:
       - rollup
       - supports-color
 
-  '@vercel/node@5.6.20':
+  '@vercel/node@12.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)':
     dependencies:
       '@edge-runtime/node-utils': 2.3.0
       '@edge-runtime/primitives': 4.1.0
       '@edge-runtime/vm': 3.2.0
       '@types/node': 20.11.0
-      '@vercel/build-utils': 13.10.0
-      '@vercel/error-utils': 2.0.3
-      '@vercel/nft': 1.5.0
-      '@vercel/static-config': 3.2.0
+      '@vercel/build-utils': 14.9.0
+      '@vercel/error-utils': 2.2.1
+      '@vercel/nft': 1.10.0
+      '@vercel/static-config': 3.4.3(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)
       async-listen: 3.0.0
       cjs-module-lexer: 1.2.3
       edge-runtime: 2.5.9
@@ -6116,71 +6574,132 @@ snapshots:
       ts-morph: 12.0.0
       tsx: 4.21.0
       typescript: 5.9.3
-      undici: 5.28.4
+      undici: 5.29.0
     transitivePeerDependencies:
+      - '@emnapi/core'
+      - '@emnapi/runtime'
       - encoding
       - rollup
       - supports-color
 
-  '@vercel/prepare-flags-definitions@0.2.1': {}
+  '@vercel/oidc@3.2.0': {}
 
-  '@vercel/python-analysis@0.11.0':
+  '@vercel/oidc@3.8.5':
+    dependencies:
+      '@vercel/cli-config': 0.2.4
+      '@vercel/cli-exec': 1.0.1
+      jose: 5.9.6
+
+  '@vercel/prepare-flags-definitions@0.3.0': {}
+
+  '@vercel/python-analysis@0.14.0':
     dependencies:
       '@bytecodealliance/preview2-shim': 0.17.6
       '@renovatebot/pep440': 4.2.1
       fs-extra: 11.1.1
-      js-yaml: 4.1.1
-      minimatch: 10.1.1
+      js-yaml: 4.3.2
+      minimatch: 10.2.6
       smol-toml: 1.5.2
       zod: 3.22.4
 
-  '@vercel/python@6.28.0':
+  '@vercel/python@13.0.0(@vercel/build-utils@14.9.0)':
     dependencies:
-      '@vercel/python-analysis': 0.11.0
+      '@vercel/build-utils': 14.9.0
+      '@vercel/python-analysis': 0.14.0
 
-  '@vercel/redwood@2.4.12':
+  '@vercel/redwood@9.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)':
     dependencies:
-      '@vercel/nft': 1.5.0
-      '@vercel/static-config': 3.2.0
+      '@vercel/build-utils': 14.9.0
+      '@vercel/nft': 1.10.0
+      '@vercel/static-config': 3.4.3(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)
       semver: 6.3.1
       ts-morph: 12.0.0
     transitivePeerDependencies:
+      - '@emnapi/core'
+      - '@emnapi/runtime'
       - encoding
       - rollup
       - supports-color
 
-  '@vercel/remix-builder@5.7.2':
+  '@vercel/remix-builder@12.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)':
     dependencies:
-      '@vercel/error-utils': 2.0.3
-      '@vercel/nft': 1.5.0
-      '@vercel/static-config': 3.2.0
+      '@vercel/build-utils': 14.9.0
+      '@vercel/error-utils': 2.2.1
+      '@vercel/nft': 1.10.0
+      '@vercel/static-config': 3.4.3(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)
       path-to-regexp: 6.1.0
       path-to-regexp-updated: path-to-regexp@6.3.0
       ts-morph: 12.0.0
     transitivePeerDependencies:
+      - '@emnapi/core'
+      - '@emnapi/runtime'
       - encoding
       - rollup
       - supports-color
 
-  '@vercel/ruby@2.3.2': {}
-
-  '@vercel/rust@1.0.5':
+  '@vercel/ruby@9.0.0(@vercel/build-utils@14.9.0)':
     dependencies:
-      '@iarna/toml': 2.2.5
+      '@vercel/build-utils': 14.9.0
+
+  '@vercel/rust@8.0.0(@vercel/build-utils@14.9.0)':
+    dependencies:
+      '@vercel/build-utils': 14.9.0
       execa: 5.1.1
+      get-port: 5.1.1
+      smol-toml: 1.5.2
 
-  '@vercel/static-build@2.9.4':
+  '@vercel/sandbox@3.1.0':
     dependencies:
-      '@vercel/gatsby-plugin-vercel-analytics': 1.0.11
-      '@vercel/gatsby-plugin-vercel-builder': 2.1.4
-      '@vercel/static-config': 3.2.0
-      ts-morph: 12.0.0
+      '@vercel/oidc': 3.2.0
+      '@workflow/serde': 4.1.0-beta.2
+      async-retry: 1.3.3
+      jose: 6.2.3
+      jsonlines: 0.1.1
+      lru-cache: 10.4.3
+      ms: 2.1.3
+      picocolors: 1.1.1
+      tar-stream: 3.1.7
+      undici: 7.29.0
+      xdg-app-paths: 5.1.0
+      zod: 4.4.3
+    transitivePeerDependencies:
+      - bare-abort-controller
+      - react-native-b4a
 
-  '@vercel/static-config@3.2.0':
+  '@vercel/static-build@9.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)':
+    dependencies:
+      '@vercel/build-utils': 14.9.0
+      '@vercel/gatsby-plugin-vercel-analytics': 1.0.12
+      '@vercel/gatsby-plugin-vercel-builder': 2.2.52
+      '@vercel/static-config': 3.4.3(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)
+      ts-morph: 12.0.0
+    transitivePeerDependencies:
+      - '@emnapi/core'
+      - '@emnapi/runtime'
+
+  '@vercel/static-config@3.4.3(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)':
     dependencies:
       ajv: 8.6.3
       json-schema-to-ts: 1.6.4
+      oxc-parser: 0.121.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)
       ts-morph: 12.0.0
+    transitivePeerDependencies:
+      - '@emnapi/core'
+      - '@emnapi/runtime'
+
+  '@vercel/vc-native-darwin-arm64@59.11.1':
+    optional: true
+
+  '@vercel/vc-native-darwin-x64@59.11.1':
+    optional: true
+
+  '@vercel/vc-native-linux-arm64@59.11.1':
+    optional: true
+
+  '@vercel/vc-native-linux-x64@59.11.1':
+    optional: true
+
+  '@workflow/serde@4.1.0-beta.2': {}
 
   abbrev@3.0.1: {}
 
@@ -6295,10 +6814,6 @@ snapshots:
 
   ast-types-flow@0.0.8: {}
 
-  ast-types@0.13.4:
-    dependencies:
-      tslib: 2.8.1
-
   astring@1.9.0: {}
 
   async-function@1.0.0: {}
@@ -6315,8 +6830,6 @@ snapshots:
 
   async-sema@3.1.1: {}
 
-  asynckit@0.4.0: {}
-
   available-typed-arrays@1.0.7:
     dependencies:
       possible-typed-array-names: 1.1.0
@@ -6325,15 +6838,17 @@ snapshots:
 
   axobject-query@4.1.0: {}
 
+  b4a@1.8.1: {}
+
   bail@2.0.2: {}
 
   balanced-match@1.0.2: {}
 
   balanced-match@4.0.4: {}
 
-  baseline-browser-mapping@2.11.1: {}
+  bare-events@2.9.2: {}
 
-  basic-ftp@5.3.1: {}
+  baseline-browser-mapping@2.11.1: {}
 
   bindings@1.5.0:
     dependencies:
@@ -6432,10 +6947,6 @@ snapshots:
 
   color-name@1.1.4: {}
 
-  combined-stream@1.0.8:
-    dependencies:
-      delayed-stream: 1.0.0
-
   comma-separated-tokens@2.0.3: {}
 
   compute-scroll-into-view@3.1.1: {}
@@ -6450,8 +6961,6 @@ snapshots:
 
   convert-source-map@2.0.0: {}
 
-  cookie-es@2.0.1: {}
-
   cross-spawn@7.0.6:
     dependencies:
       path-key: 3.1.1
@@ -6462,8 +6971,6 @@ snapshots:
 
   damerau-levenshtein@1.0.8: {}
 
-  data-uri-to-buffer@6.0.2: {}
-
   data-view-buffer@1.0.2:
     dependencies:
       call-bound: 1.0.4
@@ -6506,20 +7013,14 @@ snapshots:
       es-errors: 1.3.0
       gopd: 1.2.0
 
+  define-lazy-prop@2.0.0: {}
+
   define-properties@1.2.1:
     dependencies:
       define-data-property: 1.1.4
       has-property-descriptors: 1.0.2
       object-keys: 1.1.1
 
-  degenerator@5.0.1:
-    dependencies:
-      ast-types: 0.13.4
-      escodegen: 2.1.0
-      esprima: 4.0.1
-
-  delayed-stream@1.0.0: {}
-
   depd@1.1.2: {}
 
   dequal@2.0.3: {}
@@ -6662,6 +7163,8 @@ snapshots:
 
   es-module-lexer@1.4.1: {}
 
+  es-module-lexer@1.5.0: {}
+
   es-object-atoms@1.1.2:
     dependencies:
       es-errors: 1.3.0
@@ -6764,17 +7267,9 @@ snapshots:
 
   escape-string-regexp@5.0.0: {}
 
-  escodegen@2.1.0:
+  eslint-config-next@16.3.4(@typescript-eslint/parser@8.65.0(eslint@9.39.5(jiti@2.7.0))(typescript@5.9.3))(eslint@9.39.5(jiti@2.7.0))(typescript@5.9.3):
     dependencies:
-      esprima: 4.0.1
-      estraverse: 5.3.0
-      esutils: 2.0.3
-    optionalDependencies:
-      source-map: 0.6.1
-
-  eslint-config-next@16.2.1(@typescript-eslint/parser@8.65.0(eslint@9.39.5(jiti@2.7.0))(typescript@5.9.3))(eslint@9.39.5(jiti@2.7.0))(typescript@5.9.3):
-    dependencies:
-      '@next/eslint-plugin-next': 16.2.1
+      '@next/eslint-plugin-next': 16.3.4(eslint@9.39.5(jiti@2.7.0))
       eslint: 9.39.5(jiti@2.7.0)
       eslint-import-resolver-node: 0.3.10
       eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0)(eslint@9.39.5(jiti@2.7.0))
@@ -6965,8 +7460,6 @@ snapshots:
       acorn-jsx: 5.3.2(acorn@8.17.0)
       eslint-visitor-keys: 4.2.1
 
-  esprima@4.0.1: {}
-
   esquery@1.7.0:
     dependencies:
       estraverse: 5.3.0
@@ -7022,6 +7515,12 @@ snapshots:
 
   events-intercept@2.0.0: {}
 
+  events-universal@1.0.1:
+    dependencies:
+      bare-events: 2.9.2
+    transitivePeerDependencies:
+      - bare-abort-controller
+
   execa@3.2.0:
     dependencies:
       cross-spawn: 7.0.6
@@ -7051,6 +7550,8 @@ snapshots:
 
   fast-deep-equal@3.1.3: {}
 
+  fast-fifo@1.3.2: {}
+
   fast-glob@3.3.1:
     dependencies:
       '@nodelib/fs.stat': 2.0.5
@@ -7109,14 +7610,6 @@ snapshots:
     dependencies:
       is-callable: 1.2.7
 
-  form-data@4.0.6:
-    dependencies:
-      asynckit: 0.4.0
-      combined-stream: 1.0.8
-      es-set-tostringtag: 2.1.0
-      hasown: 2.0.4
-      mime-types: 2.1.35
-
   framer-motion@12.42.2(react-dom@19.2.4(react@19.2.4))(react@19.2.4):
     dependencies:
       motion-dom: 12.42.2
@@ -7141,7 +7634,7 @@ snapshots:
   fsevents@2.3.3:
     optional: true
 
-  fumadocs-core@16.12.1(@mdx-js/mdx@3.1.1)(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.2.17)(lucide-react@1.26.0(react@19.2.4))(next@16.2.1(@babel/core@7.29.7)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(zod@4.4.3):
+  fumadocs-core@16.12.1(@mdx-js/mdx@3.1.1)(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.2.17)(lucide-react@1.26.0(react@19.2.4))(next@16.3.4(@babel/core@7.29.7)(@types/node@20.19.43)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(zod@4.4.3):
     dependencies:
       '@orama/orama': 3.1.18
       estree-util-value-to-estree: 3.5.0
@@ -7168,22 +7661,22 @@ snapshots:
       '@types/mdast': 4.0.4
       '@types/react': 19.2.17
       lucide-react: 1.26.0(react@19.2.4)
-      next: 16.2.1(@babel/core@7.29.7)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      next: 16.3.4(@babel/core@7.29.7)(@types/node@20.19.43)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       react: 19.2.4
       react-dom: 19.2.4(react@19.2.4)
       zod: 4.4.3
     transitivePeerDependencies:
       - supports-color
 
-  fumadocs-mdx@14.3.2(@types/mdast@4.0.4)(@types/mdx@2.0.14)(@types/react@19.2.17)(fumadocs-core@16.12.1(@mdx-js/mdx@3.1.1)(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.2.17)(lucide-react@1.26.0(react@19.2.4))(next@16.2.1(@babel/core@7.29.7)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(zod@4.4.3))(next@16.2.1(@babel/core@7.29.7)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react@19.2.4):
+  fumadocs-mdx@14.3.2(@types/mdast@4.0.4)(@types/mdx@2.0.14)(@types/react@19.2.17)(fumadocs-core@16.12.1(@mdx-js/mdx@3.1.1)(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.2.17)(lucide-react@1.26.0(react@19.2.4))(next@16.3.4(@babel/core@7.29.7)(@types/node@20.19.43)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(zod@4.4.3))(next@16.3.4(@babel/core@7.29.7)(@types/node@20.19.43)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react@19.2.4):
     dependencies:
       '@mdx-js/mdx': 3.1.1
       '@standard-schema/spec': 1.1.0
       chokidar: 5.0.0
       esbuild: 0.28.1
       estree-util-value-to-estree: 3.5.0
-      fumadocs-core: 16.12.1(@mdx-js/mdx@3.1.1)(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.2.17)(lucide-react@1.26.0(react@19.2.4))(next@16.2.1(@babel/core@7.29.7)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(zod@4.4.3)
-      js-yaml: 4.3.0
+      fumadocs-core: 16.12.1(@mdx-js/mdx@3.1.1)(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.2.17)(lucide-react@1.26.0(react@19.2.4))(next@16.3.4(@babel/core@7.29.7)(@types/node@20.19.43)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(zod@4.4.3)
+      js-yaml: 4.3.2
       mdast-util-mdx: 3.0.0
       mdast-util-to-markdown: 2.1.2
       picocolors: 1.1.1
@@ -7199,12 +7692,12 @@ snapshots:
       '@types/mdast': 4.0.4
       '@types/mdx': 2.0.14
       '@types/react': 19.2.17
-      next: 16.2.1(@babel/core@7.29.7)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      next: 16.3.4(@babel/core@7.29.7)(@types/node@20.19.43)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       react: 19.2.4
     transitivePeerDependencies:
       - supports-color
 
-  fumadocs-ui@16.12.1(@types/mdx@2.0.14)(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(fumadocs-core@16.12.1(@mdx-js/mdx@3.1.1)(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.2.17)(lucide-react@1.26.0(react@19.2.4))(next@16.2.1(@babel/core@7.29.7)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(zod@4.4.3))(next@16.2.1(@babel/core@7.29.7)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(tailwindcss@4.3.3):
+  fumadocs-ui@16.12.1(@types/mdx@2.0.14)(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(fumadocs-core@16.12.1(@mdx-js/mdx@3.1.1)(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.2.17)(lucide-react@1.26.0(react@19.2.4))(next@16.3.4(@babel/core@7.29.7)(@types/node@20.19.43)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(zod@4.4.3))(next@16.3.4(@babel/core@7.29.7)(@types/node@20.19.43)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(tailwindcss@4.3.3):
     dependencies:
       '@fuma-translate/react': 1.0.2(@types/react@19.2.17)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@fumadocs/tailwind': 0.1.1(tailwindcss@4.3.3)
@@ -7220,7 +7713,7 @@ snapshots:
       '@radix-ui/react-tabs': 1.1.19(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       class-variance-authority: 0.7.1
       cnfast: 0.0.8
-      fumadocs-core: 16.12.1(@mdx-js/mdx@3.1.1)(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.2.17)(lucide-react@1.26.0(react@19.2.4))(next@16.2.1(@babel/core@7.29.7)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(zod@4.4.3)
+      fumadocs-core: 16.12.1(@mdx-js/mdx@3.1.1)(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.2.17)(lucide-react@1.26.0(react@19.2.4))(next@16.3.4(@babel/core@7.29.7)(@types/node@20.19.43)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(zod@4.4.3)
       lucide-react: 1.26.0(react@19.2.4)
       motion: 12.42.2(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       next-themes: 0.4.6(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
@@ -7234,7 +7727,7 @@ snapshots:
     optionalDependencies:
       '@types/mdx': 2.0.14
       '@types/react': 19.2.17
-      next: 16.2.1(@babel/core@7.29.7)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      next: 16.3.4(@babel/core@7.29.7)(@types/node@20.19.43)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
     transitivePeerDependencies:
       - '@emotion/is-prop-valid'
       - '@types/react-dom'
@@ -7277,6 +7770,8 @@ snapshots:
 
   get-nonce@1.0.1: {}
 
+  get-port@5.1.1: {}
+
   get-proto@1.0.1:
     dependencies:
       dunder-proto: 1.0.1
@@ -7298,14 +7793,6 @@ snapshots:
     dependencies:
       resolve-pkg-maps: 1.0.0
 
-  get-uri@6.0.5:
-    dependencies:
-      basic-ftp: 5.3.1
-      data-uri-to-buffer: 6.0.2
-      debug: 4.4.3
-    transitivePeerDependencies:
-      - supports-color
-
   github-slugger@2.0.0: {}
 
   glob-parent@5.1.2:
@@ -7318,7 +7805,7 @@ snapshots:
 
   glob@13.0.6:
     dependencies:
-      minimatch: 10.2.5
+      minimatch: 10.2.6
       minipass: 7.1.3
       path-scurry: 2.0.2
 
@@ -7481,13 +7968,6 @@ snapshots:
       statuses: 1.5.0
       toidentifier: 1.0.0
 
-  http-proxy-agent@7.0.2:
-    dependencies:
-      agent-base: 7.1.4
-      debug: 4.4.3
-    transitivePeerDependencies:
-      - supports-color
-
   https-proxy-agent@7.0.6:
     dependencies:
       agent-base: 7.1.4
@@ -7524,8 +8004,6 @@ snapshots:
       hasown: 2.0.4
       side-channel: 1.1.1
 
-  ip-address@10.2.0: {}
-
   is-alphabetical@2.0.1: {}
 
   is-alphanumerical@2.0.1:
@@ -7581,6 +8059,8 @@ snapshots:
 
   is-decimal@2.0.1: {}
 
+  is-docker@2.2.1: {}
+
   is-document.all@1.0.0:
     dependencies:
       call-bound: 1.0.4
@@ -7661,6 +8141,10 @@ snapshots:
       call-bound: 1.0.4
       get-intrinsic: 1.3.0
 
+  is-wsl@2.2.0:
+    dependencies:
+      is-docker: 2.2.1
+
   isarray@2.0.5: {}
 
   isexe@2.0.0: {}
@@ -7678,13 +8162,11 @@ snapshots:
 
   jose@5.9.6: {}
 
+  jose@6.2.3: {}
+
   js-tokens@4.0.0: {}
 
-  js-yaml@4.1.1:
-    dependencies:
-      argparse: 2.0.1
-
-  js-yaml@4.3.0:
+  js-yaml@4.3.2:
     dependencies:
       argparse: 2.0.1
 
@@ -7709,12 +8191,16 @@ snapshots:
 
   json5@2.2.3: {}
 
+  jsonc-parser@3.3.1: {}
+
   jsonfile@6.2.1:
     dependencies:
       universalify: 2.0.1
     optionalDependencies:
       graceful-fs: 4.2.11
 
+  jsonlines@0.1.1: {}
+
   jsx-ast-utils@3.3.5:
     dependencies:
       array-includes: 3.1.9
@@ -7798,6 +8284,8 @@ snapshots:
     dependencies:
       js-tokens: 4.0.0
 
+  lru-cache@10.4.3: {}
+
   lru-cache@11.5.2: {}
 
   lru-cache@5.1.1:
@@ -7808,8 +8296,6 @@ snapshots:
     dependencies:
       yallist: 4.0.0
 
-  lru-cache@7.18.3: {}
-
   lucide-react@1.26.0(react@19.2.4):
     dependencies:
       react: 19.2.4
@@ -8276,11 +8762,7 @@ snapshots:
 
   mimic-fn@2.1.0: {}
 
-  minimatch@10.1.1:
-    dependencies:
-      '@isaacs/brace-expansion': 5.0.1
-
-  minimatch@10.2.5:
+  minimatch@10.2.6:
     dependencies:
       brace-expansion: 5.0.8
 
@@ -8320,41 +8802,40 @@ snapshots:
 
   ms@2.1.3: {}
 
-  nanoid@3.3.16: {}
+  nanoid@3.3.18: {}
 
   napi-postinstall@0.3.4: {}
 
   natural-compare@1.4.0: {}
 
-  netmask@2.1.1: {}
-
   next-themes@0.4.6(react-dom@19.2.4(react@19.2.4))(react@19.2.4):
     dependencies:
       react: 19.2.4
       react-dom: 19.2.4(react@19.2.4)
 
-  next@16.2.1(@babel/core@7.29.7)(react-dom@19.2.4(react@19.2.4))(react@19.2.4):
+  next@16.3.4(@babel/core@7.29.7)(@types/node@20.19.43)(react-dom@19.2.4(react@19.2.4))(react@19.2.4):
     dependencies:
-      '@next/env': 16.2.1
-      '@swc/helpers': 0.5.15
+      '@next/env': 16.3.4
+      '@swc/helpers': 0.5.23
       baseline-browser-mapping: 2.11.1
       caniuse-lite: 1.0.30001806
-      postcss: 8.4.31
+      postcss: 8.5.23
       react: 19.2.4
       react-dom: 19.2.4(react@19.2.4)
       styled-jsx: 5.1.6(@babel/core@7.29.7)(react@19.2.4)
     optionalDependencies:
-      '@next/swc-darwin-arm64': 16.2.1
-      '@next/swc-darwin-x64': 16.2.1
-      '@next/swc-linux-arm64-gnu': 16.2.1
-      '@next/swc-linux-arm64-musl': 16.2.1
-      '@next/swc-linux-x64-gnu': 16.2.1
-      '@next/swc-linux-x64-musl': 16.2.1
-      '@next/swc-win32-arm64-msvc': 16.2.1
-      '@next/swc-win32-x64-msvc': 16.2.1
-      sharp: 0.34.5
+      '@next/swc-darwin-arm64': 16.3.4
+      '@next/swc-darwin-x64': 16.3.4
+      '@next/swc-linux-arm64-gnu': 16.3.4
+      '@next/swc-linux-arm64-musl': 16.3.4
+      '@next/swc-linux-x64-gnu': 16.3.4
+      '@next/swc-linux-x64-musl': 16.3.4
+      '@next/swc-win32-arm64-msvc': 16.3.4
+      '@next/swc-win32-x64-msvc': 16.3.4
+      sharp: 0.35.4(@types/node@20.19.43)
     transitivePeerDependencies:
       - '@babel/core'
+      - '@types/node'
       - babel-plugin-macros
 
   node-exports-info@1.6.2:
@@ -8452,6 +8933,12 @@ snapshots:
       regex: 6.1.0
       regex-recursion: 6.0.2
 
+  open@8.4.0:
+    dependencies:
+      define-lazy-prop: 2.0.0
+      is-docker: 2.2.1
+      is-wsl: 2.2.0
+
   optionator@0.9.4:
     dependencies:
       deep-is: 0.1.4
@@ -8470,7 +8957,35 @@ snapshots:
       object-keys: 1.1.1
       safe-push-apply: 1.0.0
 
-  oxc-transform@0.111.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.2):
+  oxc-parser@0.121.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3):
+    dependencies:
+      '@oxc-project/types': 0.121.0
+    optionalDependencies:
+      '@oxc-parser/binding-android-arm-eabi': 0.121.0
+      '@oxc-parser/binding-android-arm64': 0.121.0
+      '@oxc-parser/binding-darwin-arm64': 0.121.0
+      '@oxc-parser/binding-darwin-x64': 0.121.0
+      '@oxc-parser/binding-freebsd-x64': 0.121.0
+      '@oxc-parser/binding-linux-arm-gnueabihf': 0.121.0
+      '@oxc-parser/binding-linux-arm-musleabihf': 0.121.0
+      '@oxc-parser/binding-linux-arm64-gnu': 0.121.0
+      '@oxc-parser/binding-linux-arm64-musl': 0.121.0
+      '@oxc-parser/binding-linux-ppc64-gnu': 0.121.0
+      '@oxc-parser/binding-linux-riscv64-gnu': 0.121.0
+      '@oxc-parser/binding-linux-riscv64-musl': 0.121.0
+      '@oxc-parser/binding-linux-s390x-gnu': 0.121.0
+      '@oxc-parser/binding-linux-x64-gnu': 0.121.0
+      '@oxc-parser/binding-linux-x64-musl': 0.121.0
+      '@oxc-parser/binding-openharmony-arm64': 0.121.0
+      '@oxc-parser/binding-wasm32-wasi': 0.121.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)
+      '@oxc-parser/binding-win32-arm64-msvc': 0.121.0
+      '@oxc-parser/binding-win32-ia32-msvc': 0.121.0
+      '@oxc-parser/binding-win32-x64-msvc': 0.121.0
+    transitivePeerDependencies:
+      - '@emnapi/core'
+      - '@emnapi/runtime'
+
+  oxc-transform@0.111.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3):
     optionalDependencies:
       '@oxc-transform/binding-android-arm-eabi': 0.111.0
       '@oxc-transform/binding-android-arm64': 0.111.0
@@ -8488,7 +9003,7 @@ snapshots:
       '@oxc-transform/binding-linux-x64-gnu': 0.111.0
       '@oxc-transform/binding-linux-x64-musl': 0.111.0
       '@oxc-transform/binding-openharmony-arm64': 0.111.0
-      '@oxc-transform/binding-wasm32-wasi': 0.111.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.2)
+      '@oxc-transform/binding-wasm32-wasi': 0.111.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)
       '@oxc-transform/binding-win32-arm64-msvc': 0.111.0
       '@oxc-transform/binding-win32-ia32-msvc': 0.111.0
       '@oxc-transform/binding-win32-x64-msvc': 0.111.0
@@ -8506,24 +9021,6 @@ snapshots:
     dependencies:
       p-limit: 3.1.0
 
-  pac-proxy-agent@7.2.0:
-    dependencies:
-      '@tootallnate/quickjs-emscripten': 0.23.0
-      agent-base: 7.1.4
-      debug: 4.4.3
-      get-uri: 6.0.5
-      http-proxy-agent: 7.0.2
-      https-proxy-agent: 7.0.6
-      pac-resolver: 7.0.1
-      socks-proxy-agent: 8.0.5
-    transitivePeerDependencies:
-      - supports-color
-
-  pac-resolver@7.0.1:
-    dependencies:
-      degenerator: 5.0.1
-      netmask: 2.1.1
-
   parent-module@1.0.1:
     dependencies:
       callsites: 3.1.0
@@ -8577,15 +9074,15 @@ snapshots:
 
   possible-typed-array-names@1.1.0: {}
 
-  postcss@8.4.31:
+  postcss@8.5.23:
     dependencies:
-      nanoid: 3.3.16
+      nanoid: 3.3.18
       picocolors: 1.1.1
       source-map-js: 1.2.1
 
-  postcss@8.5.22:
+  postcss@8.5.26:
     dependencies:
-      nanoid: 3.3.16
+      nanoid: 3.3.18
       picocolors: 1.1.1
       source-map-js: 1.2.1
 
@@ -8605,21 +9102,6 @@ snapshots:
 
   property-information@7.2.0: {}
 
-  proxy-agent@6.4.0:
-    dependencies:
-      agent-base: 7.1.4
-      debug: 4.4.3
-      http-proxy-agent: 7.0.2
-      https-proxy-agent: 7.0.6
-      lru-cache: 7.18.3
-      pac-proxy-agent: 7.2.0
-      proxy-from-env: 1.1.0
-      socks-proxy-agent: 8.0.5
-    transitivePeerDependencies:
-      - supports-color
-
-  proxy-from-env@1.1.0: {}
-
   pump@3.0.4:
     dependencies:
       end-of-stream: 1.4.5
@@ -8822,7 +9304,7 @@ snapshots:
 
   reusify@1.1.0: {}
 
-  rolldown@1.0.0-rc.1(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.2):
+  rolldown@1.0.0-rc.1(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3):
     dependencies:
       '@oxc-project/types': 0.110.0
       '@rolldown/pluginutils': 1.0.0-rc.1
@@ -8837,7 +9319,7 @@ snapshots:
       '@rolldown/binding-linux-x64-gnu': 1.0.0-rc.1
       '@rolldown/binding-linux-x64-musl': 1.0.0-rc.1
       '@rolldown/binding-openharmony-arm64': 1.0.0-rc.1
-      '@rolldown/binding-wasm32-wasi': 1.0.0-rc.1(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.2)
+      '@rolldown/binding-wasm32-wasi': 1.0.0-rc.1(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)
       '@rolldown/binding-win32-arm64-msvc': 1.0.0-rc.1
       '@rolldown/binding-win32-x64-msvc': 1.0.0-rc.1
     transitivePeerDependencies:
@@ -8869,6 +9351,20 @@ snapshots:
 
   safer-buffer@2.1.2: {}
 
+  sandbox@4.1.0:
+    dependencies:
+      '@vercel/sandbox': 3.1.0
+      async-retry: 1.3.3
+      debug: 4.4.3
+      ws: 8.21.3
+      zod: 4.4.3
+    transitivePeerDependencies:
+      - bare-abort-controller
+      - bufferutil
+      - react-native-b4a
+      - supports-color
+      - utf-8-validate
+
   scheduler@0.27.0: {}
 
   scroll-into-view-if-needed@3.1.0:
@@ -8907,36 +9403,38 @@ snapshots:
 
   setprototypeof@1.1.1: {}
 
-  sharp@0.34.5:
+  sharp@0.35.4(@types/node@20.19.43):
     dependencies:
       '@img/colour': 1.1.0
       detect-libc: 2.1.2
       semver: 7.8.5
     optionalDependencies:
-      '@img/sharp-darwin-arm64': 0.34.5
-      '@img/sharp-darwin-x64': 0.34.5
-      '@img/sharp-libvips-darwin-arm64': 1.2.4
-      '@img/sharp-libvips-darwin-x64': 1.2.4
-      '@img/sharp-libvips-linux-arm': 1.2.4
-      '@img/sharp-libvips-linux-arm64': 1.2.4
-      '@img/sharp-libvips-linux-ppc64': 1.2.4
-      '@img/sharp-libvips-linux-riscv64': 1.2.4
-      '@img/sharp-libvips-linux-s390x': 1.2.4
-      '@img/sharp-libvips-linux-x64': 1.2.4
-      '@img/sharp-libvips-linuxmusl-arm64': 1.2.4
-      '@img/sharp-libvips-linuxmusl-x64': 1.2.4
-      '@img/sharp-linux-arm': 0.34.5
-      '@img/sharp-linux-arm64': 0.34.5
-      '@img/sharp-linux-ppc64': 0.34.5
-      '@img/sharp-linux-riscv64': 0.34.5
-      '@img/sharp-linux-s390x': 0.34.5
-      '@img/sharp-linux-x64': 0.34.5
-      '@img/sharp-linuxmusl-arm64': 0.34.5
-      '@img/sharp-linuxmusl-x64': 0.34.5
-      '@img/sharp-wasm32': 0.34.5
-      '@img/sharp-win32-arm64': 0.34.5
-      '@img/sharp-win32-ia32': 0.34.5
-      '@img/sharp-win32-x64': 0.34.5
+      '@img/sharp-darwin-arm64': 0.35.4
+      '@img/sharp-darwin-x64': 0.35.4
+      '@img/sharp-freebsd-wasm32': 0.35.4
+      '@img/sharp-libvips-darwin-arm64': 1.3.3
+      '@img/sharp-libvips-darwin-x64': 1.3.3
+      '@img/sharp-libvips-linux-arm': 1.3.3
+      '@img/sharp-libvips-linux-arm64': 1.3.3
+      '@img/sharp-libvips-linux-ppc64': 1.3.3
+      '@img/sharp-libvips-linux-riscv64': 1.3.3
+      '@img/sharp-libvips-linux-s390x': 1.3.3
+      '@img/sharp-libvips-linux-x64': 1.3.3
+      '@img/sharp-libvips-linuxmusl-arm64': 1.3.3
+      '@img/sharp-libvips-linuxmusl-x64': 1.3.3
+      '@img/sharp-linux-arm': 0.35.4
+      '@img/sharp-linux-arm64': 0.35.4
+      '@img/sharp-linux-ppc64': 0.35.4
+      '@img/sharp-linux-riscv64': 0.35.4
+      '@img/sharp-linux-s390x': 0.35.4
+      '@img/sharp-linux-x64': 0.35.4
+      '@img/sharp-linuxmusl-arm64': 0.35.4
+      '@img/sharp-linuxmusl-x64': 0.35.4
+      '@img/sharp-webcontainers-wasm32': 0.35.4
+      '@img/sharp-win32-arm64': 0.35.4
+      '@img/sharp-win32-ia32': 0.35.4
+      '@img/sharp-win32-x64': 0.35.4
+      '@types/node': 20.19.43
     optional: true
 
   shebang-command@2.0.0:
@@ -8988,35 +9486,15 @@ snapshots:
 
   signal-exit@4.0.2: {}
 
-  smart-buffer@4.2.0: {}
-
   smol-toml@1.5.2: {}
 
-  socks-proxy-agent@8.0.5:
-    dependencies:
-      agent-base: 7.1.4
-      debug: 4.4.3
-      socks: 2.8.9
-    transitivePeerDependencies:
-      - supports-color
-
-  socks@2.8.9:
-    dependencies:
-      ip-address: 10.2.0
-      smart-buffer: 4.2.0
-
   source-map-js@1.2.1: {}
 
-  source-map@0.6.1:
-    optional: true
-
   source-map@0.7.6: {}
 
   space-separated-tokens@2.0.2: {}
 
-  srvx@0.8.9:
-    dependencies:
-      cookie-es: 2.0.1
+  srvx@0.11.16: {}
 
   stable-hash@0.0.5: {}
 
@@ -9039,6 +9517,15 @@ snapshots:
       end-of-stream: 1.1.0
       stream-to-array: 2.3.0
 
+  streamx@2.28.1:
+    dependencies:
+      events-universal: 1.0.1
+      fast-fifo: 1.3.2
+      text-decoder: 1.2.7
+    transitivePeerDependencies:
+      - bare-abort-controller
+      - react-native-b4a
+
   string.prototype.includes@2.0.1:
     dependencies:
       call-bind: 1.0.9
@@ -9128,7 +9615,16 @@ snapshots:
 
   tapable@2.3.3: {}
 
-  tar@7.5.21:
+  tar-stream@3.1.7:
+    dependencies:
+      b4a: 1.8.1
+      fast-fifo: 1.3.2
+      streamx: 2.28.1
+    transitivePeerDependencies:
+      - bare-abort-controller
+      - react-native-b4a
+
+  tar@7.5.22:
     dependencies:
       '@isaacs/fs-minipass': 4.0.1
       chownr: 3.0.0
@@ -9136,13 +9632,11 @@ snapshots:
       minizlib: 3.1.0
       yallist: 5.0.0
 
-  tar@7.5.7:
+  text-decoder@1.2.7:
     dependencies:
-      '@isaacs/fs-minipass': 4.0.1
-      chownr: 3.0.0
-      minipass: 7.1.3
-      minizlib: 3.1.0
-      yallist: 5.0.0
+      b4a: 1.8.1
+    transitivePeerDependencies:
+      - react-native-b4a
 
   throttleit@2.1.0: {}
 
@@ -9265,11 +9759,13 @@ snapshots:
 
   undici-types@6.21.0: {}
 
-  undici@5.28.4:
+  undici@5.29.0:
     dependencies:
       '@fastify/busboy': 2.1.1
 
-  undici@6.27.0: {}
+  undici@6.28.0: {}
+
+  undici@7.29.0: {}
 
   unified@11.0.5:
     dependencies:
@@ -9369,44 +9865,62 @@ snapshots:
     optionalDependencies:
       '@types/react': 19.2.17
 
-  vercel@50.37.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.2)(typescript@5.9.3):
+  uuid@14.0.1: {}
+
+  vercel@59.11.1(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3):
     dependencies:
-      '@vercel/backends': 0.0.51(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.2)(typescript@5.9.3)
-      '@vercel/blob': 2.3.0
-      '@vercel/build-utils': 13.10.0
-      '@vercel/detect-agent': 1.2.1
-      '@vercel/elysia': 0.1.53
-      '@vercel/express': 0.1.63(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.2)(typescript@5.9.3)
-      '@vercel/fastify': 0.1.56
+      '@vercel/backends': 7.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)
+      '@vercel/blob': 2.8.0
+      '@vercel/build-utils': 14.9.0
+      '@vercel/cli-auth': 0.3.5
+      '@vercel/cli-config': 0.2.4
+      '@vercel/container': 7.0.0(@vercel/build-utils@14.9.0)
+      '@vercel/detect-agent': 1.2.5
+      '@vercel/elysia': 7.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)
+      '@vercel/express': 7.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)
+      '@vercel/fastify': 7.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)
       '@vercel/fun': 1.3.0
-      '@vercel/go': 3.4.6
-      '@vercel/h3': 0.1.62
-      '@vercel/hono': 0.2.56
-      '@vercel/hydrogen': 1.3.6
-      '@vercel/koa': 0.1.36
-      '@vercel/nestjs': 0.2.57
-      '@vercel/next': 4.16.3
-      '@vercel/node': 5.6.20
-      '@vercel/prepare-flags-definitions': 0.2.1
-      '@vercel/python': 6.28.0
-      '@vercel/redwood': 2.4.12
-      '@vercel/remix-builder': 5.7.2
-      '@vercel/ruby': 2.3.2
-      '@vercel/rust': 1.0.5
-      '@vercel/static-build': 2.9.4
+      '@vercel/go': 10.0.0(@vercel/build-utils@14.9.0)
+      '@vercel/h3': 7.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)
+      '@vercel/hono': 7.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)
+      '@vercel/hydrogen': 8.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)
+      '@vercel/koa': 7.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)
+      '@vercel/nestjs': 7.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)
+      '@vercel/next': 11.0.0(@vercel/build-utils@14.9.0)
+      '@vercel/node': 12.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)
+      '@vercel/prepare-flags-definitions': 0.3.0
+      '@vercel/python': 13.0.0(@vercel/build-utils@14.9.0)
+      '@vercel/python-analysis': 0.14.0
+      '@vercel/redwood': 9.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)
+      '@vercel/remix-builder': 12.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)
+      '@vercel/ruby': 9.0.0(@vercel/build-utils@14.9.0)
+      '@vercel/rust': 8.0.0(@vercel/build-utils@14.9.0)
+      '@vercel/static-build': 9.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@vercel/build-utils@14.9.0)
       chokidar: 4.0.0
       esbuild: 0.27.0
-      form-data: 4.0.6
       jose: 5.9.6
+      jsonc-parser: 3.3.1
       luxon: 3.7.2
-      proxy-agent: 6.4.0
+      sandbox: 4.1.0
+      smol-toml: 1.5.2
+      undici: 5.29.0
+      uuid: 14.0.1
+      zod: 4.1.11
+    optionalDependencies:
+      '@vercel/vc-native-darwin-arm64': 59.11.1
+      '@vercel/vc-native-darwin-x64': 59.11.1
+      '@vercel/vc-native-linux-arm64': 59.11.1
+      '@vercel/vc-native-linux-x64': 59.11.1
     transitivePeerDependencies:
       - '@emnapi/core'
       - '@emnapi/runtime'
+      - bare-abort-controller
+      - bufferutil
       - encoding
+      - react-native-b4a
       - rollup
       - supports-color
-      - typescript
+      - utf-8-validate
 
   vfile-location@5.0.3:
     dependencies:
@@ -9483,6 +9997,8 @@ snapshots:
 
   wrappy@1.0.2: {}
 
+  ws@8.21.3: {}
+
   xdg-app-paths@5.1.0:
     dependencies:
       xdg-portable: 7.3.0
@@ -9521,6 +10037,8 @@ snapshots:
 
   zod@3.22.4: {}
 
+  zod@4.1.11: {}
+
   zod@4.4.3: {}
 
   zwitch@2.0.4: {}
diff --git a/mobile/pnpm-lock.yaml b/mobile/pnpm-lock.yaml
index 6473659419d..60ccee97d2f 100644
--- a/mobile/pnpm-lock.yaml
+++ b/mobile/pnpm-lock.yaml
@@ -93,7 +93,7 @@ importers:
         version: 55.0.27(expo@55.0.30)(react-native@0.83.10(patch_hash=44876634a8efbb0f2c3f66cd4332be170ec821d1cbfc0264ac80680983e8513d)(@babel/core@7.29.7)(@react-native/metro-config@0.85.2(@babel/core@7.29.7))(@types/react@19.2.14)(react@19.2.8))(react@19.2.8)(typescript@6.0.3)
       expo-router:
         specifier: ^55.0.18
-        version: 55.0.18(2f99795f9796def5cdb1516a493dc117)
+        version: 55.0.18(4a60a26fd685ffdcc7f556016ae4bc5e)
       expo-secure-store:
         specifier: ^55.0.18
         version: 55.0.18(expo@55.0.30)
@@ -178,7 +178,7 @@ importers:
         version: 0.25.4
       expo-module-scripts:
         specifier: ^55.0.2
-        version: 55.0.2(@babel/core@7.29.7)(@babel/runtime@7.29.7)(@jest/types@29.6.3)(babel-jest@29.7.0(@babel/core@7.29.7))(esbuild@0.25.4)(eslint@9.39.4)(expo@55.0.30)(jest@29.7.0(@types/node@26.1.2))(prettier@2.8.8)(react-native@0.83.10(patch_hash=44876634a8efbb0f2c3f66cd4332be170ec821d1cbfc0264ac80680983e8513d)(@babel/core@7.29.7)(@react-native/metro-config@0.85.2(@babel/core@7.29.7))(@types/react@19.2.14)(react@19.2.8))(react-refresh@0.14.2)(react-test-renderer@19.2.8(react@19.2.8))(react@19.2.8)
+        version: 55.0.2(@babel/core@7.29.7)(@babel/runtime@7.29.7)(@jest/types@29.6.3)(babel-jest@29.7.0(@babel/core@7.29.7))(esbuild@0.25.4)(eslint@9.39.4)(expo@55.0.30)(jest@29.7.0(@types/node@26.4.0))(prettier@2.8.8)(react-native@0.83.10(patch_hash=44876634a8efbb0f2c3f66cd4332be170ec821d1cbfc0264ac80680983e8513d)(@babel/core@7.29.7)(@react-native/metro-config@0.85.2(@babel/core@7.29.7))(@types/react@19.2.14)(react@19.2.8))(react-refresh@0.14.2)(react-test-renderer@19.2.8(react@19.2.8))(react@19.2.8)
       happy-dom:
         specifier: ^20.11.8
         version: 20.11.8
@@ -199,10 +199,10 @@ importers:
         version: 6.0.3
       vite:
         specifier: ^8.0.16
-        version: 8.1.0(@types/node@26.1.2)(esbuild@0.25.4)(terser@5.49.1)(tsx@4.22.4)(yaml@2.9.0)
+        version: 8.1.0(@types/node@26.4.0)(esbuild@0.25.4)(terser@5.51.2)(tsx@4.22.4)(yaml@2.9.0)
       vitest:
         specifier: ^4.1.11
-        version: 4.1.11(@types/node@26.1.2)(happy-dom@20.11.8)(jsdom@20.0.3)(vite@8.1.0(@types/node@26.1.2)(esbuild@0.25.4)(terser@5.49.1)(tsx@4.22.4)(yaml@2.9.0))
+        version: 4.1.11(@types/node@26.4.0)(happy-dom@20.11.8)(jsdom@20.0.3)(vite@8.1.0(@types/node@26.4.0)(esbuild@0.25.4)(terser@5.51.2)(tsx@4.22.4)(yaml@2.9.0))
 
 packages:
 
@@ -2897,6 +2897,9 @@ packages:
   '@types/node@26.1.2':
     resolution: {integrity: sha512-Vu4a5UFA9rIIFJ7rB/Vaafh9lrCQszopTCx6KjFboXTGQbPNasehVR5TEiithSDGyd1DEiUByggTZsg8jukeIg==}
 
+  '@types/node@26.4.0':
+    resolution: {integrity: sha512-faiGnoIrLH/V8cibOMEAZ8pMw6oXqSukl29ra4mN8GdaB2ZewzeaLj+INpV5N+Z1eKWzY+IzaIZH2EIR6YZRNQ==}
+
   '@types/react-native@0.73.0':
     resolution: {integrity: sha512-6ZRPQrYM72qYKGWidEttRe6M5DZBEV5F+MHMHqd4TTYx0tfkcdrUFGdef6CCxY0jXU7wldvd/zA/b0A/kTeJmA==}
     deprecated: This is a stub types definition. react-native provides its own type definitions, so you do not need this installed.
@@ -3356,8 +3359,8 @@ packages:
   base64-js@1.5.1:
     resolution: {integrity: sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==}
 
-  baseline-browser-mapping@2.10.27:
-    resolution: {integrity: sha512-zEs/ufmZoUd7WftKpKyXaT6RFxpQ5Qm9xytKRHvJfxFV9DFJkZph9RvJ1LcOUi0Z1ZVijMte65JbILeV+8QQEA==}
+  baseline-browser-mapping@2.11.20:
+    resolution: {integrity: sha512-H0ulySigv6icDJ1F7SjtdCD6PrhTpdYCmP0CactWy1+ekh0AFd0o1Wn5T8b+hnTmdBx19u9yhL6wvCylXMY7zw==}
     engines: {node: '>=6.0.0'}
     hasBin: true
 
@@ -3398,8 +3401,8 @@ packages:
     resolution: {integrity: sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==}
     engines: {node: '>=8'}
 
-  browserslist@4.28.2:
-    resolution: {integrity: sha512-48xSriZYYg+8qXna9kwqjIVzuQxi+KYWp2+5nCYnYKPTr0LvD89Jqk2Or5ogxz0NUMfIjhh2lIUX/LyX9B4oIg==}
+  browserslist@4.28.8:
+    resolution: {integrity: sha512-V2NpofLblG64mfOtSgDhOJESZEGogzDMBv/q+W6oc4LXWP/q75eOXoOaaOu1EOadB9U4Bwx/e0yzbvwKH8zalA==}
     engines: {node: ^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7}
     hasBin: true
 
@@ -3448,8 +3451,8 @@ packages:
     resolution: {integrity: sha512-Gmy6FhYlCY7uOElZUSbxo2UCDH8owEk996gkbrpsgGtrJLM3J7jGxl9Ic7Qwwj4ivOE5AWZWRMecDdF7hqGjFA==}
     engines: {node: '>=10'}
 
-  caniuse-lite@1.0.30001792:
-    resolution: {integrity: sha512-hVLMUZFgR4JJ6ACt1uEESvQN1/dBVqPAKY0hgrV70eN3391K6juAfTjKZLKvOMsx8PxA7gsY1/tLMMTcfFLLpw==}
+  caniuse-lite@1.0.30001810:
+    resolution: {integrity: sha512-TITQPUkaz+aVk5GL6NhOdwk1aEaNTSDPsGFWrTuhKGtjTF70jL/Oht2W4c6rXUe5fu7Ie19VIahAXHIIiWWNeg==}
 
   chai@6.2.2:
     resolution: {integrity: sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==}
@@ -3941,8 +3944,8 @@ packages:
   ee-first@1.1.1:
     resolution: {integrity: sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==}
 
-  electron-to-chromium@1.5.352:
-    resolution: {integrity: sha512-9wHk8x6dyuimoe18EdiDPWKExNdxYqo4fn4FwOVVper6RxT3cmpBwBkWWfSOCYJjQdIco/nPhJhNLmn4Ufg1Yg==}
+  electron-to-chromium@1.5.416:
+    resolution: {integrity: sha512-K6bvB2BjnNrugtIih6ewlbBI9DXa976jIdiIlRLHhBoEI9a4JaQjjHyF+A1IQI543aQYR4LnmOrT/K5fZj0aPA==}
 
   emittery@0.13.1:
     resolution: {integrity: sha512-DeWwawk6r5yR9jFgnDKYt4sLS0LmHJJi3ZOnb5/JdbYwj3nW+FxQnHIjhBKz8YLC7oRNPVM9NQ47I3CVx34eqQ==}
@@ -5228,6 +5231,10 @@ packages:
     resolution: {integrity: sha512-CY6crGq313MX8GkwvB7tzgp99vjQxY1++5y10/BKN/GUfHqWaOGQMNZkBvqSzsZKWk/ijwHlWzzkLulsGHhjWQ==}
     hasBin: true
 
+  js-yaml@4.3.2:
+    resolution: {integrity: sha512-SFNOvSJ+Dgf/9An904Yx+CgSlIPCkIpao4qo51lpee25TIRejdH3rhR4EZMGoNx3/TP3O+wzWuiTFl4sqbltzA==}
+    hasBin: true
+
   jsc-safe-url@0.2.4:
     resolution: {integrity: sha512-0wM3YBWtYePOjfyXQH5MWQ8H7sdk5EXSwZvmSLKk2RboVQ2Bu239jycHDz5J/8Blf3K0Qnoy2b6xD+z10MFB+Q==}
 
@@ -5492,8 +5499,8 @@ packages:
     resolution: {integrity: sha512-tnn0J5wzgTgTx2OJy3Cwr1y79bJz4eNgFQd+2HENOs5Vz6QOMnt05z7J+BedIo9wIbpEa0iN9U1nerxyvMRE9g==}
     engines: {node: '>=20.19.4'}
 
-  metro-babel-transformer@0.84.4:
-    resolution: {integrity: sha512-rvCfz8snl9h20VcvpOHxZuHP1SlAkv4HXbzw7nyyVwu6Eqo5PRerbakQ9XmUCOsRy70spJ37O+G1TK8oMzo48g==}
+  metro-babel-transformer@0.84.5:
+    resolution: {integrity: sha512-2WbHILKMiJUzfdjmGOQOqU1bWi9//gqiclc/tkk/AIsrrVw3efhZ1uhkOwMTxUEPOzqoo091H0olLmVZH5FHGQ==}
     engines: {node: ^20.19.4 || ^22.13.0 || ^24.3.0 || >= 25.0.0}
 
   metro-cache-key@0.83.7:
@@ -5504,8 +5511,8 @@ packages:
     resolution: {integrity: sha512-I38PtcjT4crS5HY9UQ8i6z8S7tJ2WewtPGr/OwS6FcLKfy5T/1hlTaFw+wozUZkEtNpR6Gc0oJuvuKCbSoSN5A==}
     engines: {node: '>=20.19.4'}
 
-  metro-cache-key@0.84.4:
-    resolution: {integrity: sha512-wVO79aGrkYImpnaVS4+d5RrRBRPX31QtvKB3wKGBuiNSznduZTQHzsrJZRroFJSwnygrzdsGUtDQPuqqFjFdvw==}
+  metro-cache-key@0.84.5:
+    resolution: {integrity: sha512-3dPB2TnvGjjf0/9O7AXVQURKXuQNauTZE7WpTGTlR017Gh/B5y0m/2wcqxfveUguHSpu89KhVxCAlr2k/H7uhQ==}
     engines: {node: ^20.19.4 || ^22.13.0 || ^24.3.0 || >= 25.0.0}
 
   metro-cache@0.83.7:
@@ -5516,8 +5523,8 @@ packages:
     resolution: {integrity: sha512-aogMG5WbKzW5000otNjYrS9hIoORzkCI1faPJK+vxQLaf2BorJKBBFe/jl2Tfsi1mZUglS2EBuBt8B3JB7MYDQ==}
     engines: {node: '>=20.19.4'}
 
-  metro-cache@0.84.4:
-    resolution: {integrity: sha512-gpcFQdSLUwUCk71saKoE64jLFbx2nwTfVCcPSULMNT8QYq0p1eZZE29Jvd0HtT/UlhC3ZOutLxJME5xqD2JUZg==}
+  metro-cache@0.84.5:
+    resolution: {integrity: sha512-WHS0n2OxQqtwEjSeQFPePNrMvEFhmQcUQM9cRJMHByWoi/GMWFBEWOf7hVkAM/0KRutAXNbDlSu/cZB6CyxgQQ==}
     engines: {node: ^20.19.4 || ^22.13.0 || ^24.3.0 || >= 25.0.0}
 
   metro-config@0.83.7:
@@ -5528,8 +5535,8 @@ packages:
     resolution: {integrity: sha512-crNbNy+/B4tCne2+HjUshwvC57gNBQj+V9fFSy3lHH2RlKcLHib3Mil/SfTX8Pfh2fCY5pPuSu2OKa7YiadB+Q==}
     engines: {node: '>=20.19.4'}
 
-  metro-config@0.84.4:
-    resolution: {integrity: sha512-PMotGDjXcXLWo2TMRH+VR99phFNgYTwqh4OoieIKK3yTJa1Jmkl+fZJxDO0jfBvNF+WESHciHvpNuBtXaF3B0Q==}
+  metro-config@0.84.5:
+    resolution: {integrity: sha512-zie+uN6oohscowi2S7ByU+wUw6CrT4ZxW9uAbONOObSxx86RGmnIAmjXHLkfmcdYoY7jzOPEbqcI6oeVmqyBQA==}
     engines: {node: ^20.19.4 || ^22.13.0 || ^24.3.0 || >= 25.0.0}
 
   metro-core@0.83.7:
@@ -5540,8 +5547,8 @@ packages:
     resolution: {integrity: sha512-NTyOUOQaQKvQgJG9VI2ymN6KTM7gHEqkVFhkPc9bK4BsHSTz/EaXuFBXtC+wtwINLeH9tbusL/jfsSmdEmuU7A==}
     engines: {node: '>=20.19.4'}
 
-  metro-core@0.84.4:
-    resolution: {integrity: sha512-HONpWC5LGXZn3ffkd4Hu6AIrfE7j4Z0g0wMo/goV24WOB3lhuFZ40KgvaDiSw8iyQHloMYay5N/wPX+z8oN/PQ==}
+  metro-core@0.84.5:
+    resolution: {integrity: sha512-xwm605hCi5Y6eJTTb8ZWo6pkUcoBEIyiQOfkZh5GwtDwUrP9SNhTQZhzJHrBCwwxlf3Ptl/pxWJgQ1rsNYMnrA==}
     engines: {node: ^20.19.4 || ^22.13.0 || ^24.3.0 || >= 25.0.0}
 
   metro-file-map@0.83.7:
@@ -5552,8 +5559,8 @@ packages:
     resolution: {integrity: sha512-+W++EUuzEXIfWQEFTWQMVThzhWbnJL4gRNJ9WSHzIAM5pT7gsprUxo9+2hrfirURm/TLvrKwhq37oCECJcDSyQ==}
     engines: {node: '>=20.19.4'}
 
-  metro-file-map@0.84.4:
-    resolution: {integrity: sha512-KSVDi/u60hKPx++NLu3MTIvyjzNoJnFAF8PQFxaj1jiSka/wjw+Ua6sNuJ0TDHQv+7AAoFQxeMgaRAe8Yic5wQ==}
+  metro-file-map@0.84.5:
+    resolution: {integrity: sha512-mlm/JL8toSbSc2akpKIGmzvrVRSCgZ5vkbycI34oMLoOnLGuLyC8WTyVJ6P0hZG/usDaGwZSl/s9BCRriqjGJA==}
     engines: {node: ^20.19.4 || ^22.13.0 || ^24.3.0 || >= 25.0.0}
 
   metro-minify-terser@0.83.7:
@@ -5564,8 +5571,8 @@ packages:
     resolution: {integrity: sha512-7tU0J5/c7LZaZJwTlOb1xq0NepTFvGzRxigDhZOq4jSE6g0BRHmBqe7XvLH3WcRiJNGy+eshcZr34RpMjb6mmg==}
     engines: {node: '>=20.19.4'}
 
-  metro-minify-terser@0.84.4:
-    resolution: {integrity: sha512-5qpbaVOMC7CPitIpuewzVeGw7E+C3ykbv2mqTjQLl85Z3annSVGlSCTcsZjqXZzjupfK4Ztj3dDc4kc44NZwtQ==}
+  metro-minify-terser@0.84.5:
+    resolution: {integrity: sha512-BJoFwCEDsYnagPqarayInv2+diCDNDdLlaof/p6s9w4gh+gc9HXYM+pDvsKGKKUumpZswNF3Z/ftTMqKl/5IBg==}
     engines: {node: ^20.19.4 || ^22.13.0 || ^24.3.0 || >= 25.0.0}
 
   metro-resolver@0.83.7:
@@ -5576,8 +5583,8 @@ packages:
     resolution: {integrity: sha512-piU0NVTI9i37YztDVF5rtn9uxP3NebVT0xZM9NKJ9z0jbigrctUQksi3NoYIeJMvL6Wn2dgAehpcmmnfn+gUwA==}
     engines: {node: '>=20.19.4'}
 
-  metro-resolver@0.84.4:
-    resolution: {integrity: sha512-1qLgbxQ5ZGhhutuPot1Yp348ofDsATL2WkrHF65TobqTT9K3P9qJXw38bomk7ncp5B7OYMfWwtyBZo1lCV792A==}
+  metro-resolver@0.84.5:
+    resolution: {integrity: sha512-VSSnepg1k6LyCwtb6eirWdAWlpKwBG8Rdtsr1mU38rMelFyWgh3/QuMSiZIZAIjwg/fsa8GhW5/FO54CAUPCEA==}
     engines: {node: ^20.19.4 || ^22.13.0 || ^24.3.0 || >= 25.0.0}
 
   metro-runtime@0.83.7:
@@ -5588,8 +5595,8 @@ packages:
     resolution: {integrity: sha512-f7FfeM0pamq8vrvs8aO9KvIUabbUKe0WkHFpLt6Q9yIIIsORqNFwlgJeHGraOFPU7Cxqj5yLXkJu5bT1uwDXvw==}
     engines: {node: '>=20.19.4'}
 
-  metro-runtime@0.84.4:
-    resolution: {integrity: sha512-Jibypds4g7AhzdRKY+kDoj51s5EXMwgyp5ddtlreDAsWefMdOx+agWqgm0H2XSZ/ueanHHVM89fnf5OJnlxa8Q==}
+  metro-runtime@0.84.5:
+    resolution: {integrity: sha512-U1m2+d1Pr+JO2/iVXBB2OfXXityz7tqwIorxfrT15IEgaHvpJBq/OHiqnOWPKJbUl3JcxjcdviZZOKk85oK4Qg==}
     engines: {node: ^20.19.4 || ^22.13.0 || ^24.3.0 || >= 25.0.0}
 
   metro-source-map@0.83.7:
@@ -5600,8 +5607,8 @@ packages:
     resolution: {integrity: sha512-60Uor7bM+KsVewLkLCcZfkPFCbqjPDdoSmeBuT3+ye+ac80BuLWbbR8DpyxWpUqQeZPdaAT5ZqFgDIs8BNEcVA==}
     engines: {node: '>=20.19.4'}
 
-  metro-source-map@0.84.4:
-    resolution: {integrity: sha512-jbWkPxIesVuo1IWkvezmMJld6iu8nD62GsrZiV6jP37AOdbo4OBq1FJ+qkOg8sV05wAHB//jAbziuW0SlJfW4g==}
+  metro-source-map@0.84.5:
+    resolution: {integrity: sha512-2BtV5L9uPc49F13Gn5wiP6bX/EncqzqTIk2VL/0F/96Vo0YEOjluT/qktQjFODfqGFsucwnh5mPEAl/2jVEfeg==}
     engines: {node: ^20.19.4 || ^22.13.0 || ^24.3.0 || >= 25.0.0}
 
   metro-symbolicate@0.83.7:
@@ -5614,8 +5621,8 @@ packages:
     engines: {node: '>=20.19.4'}
     hasBin: true
 
-  metro-symbolicate@0.84.4:
-    resolution: {integrity: sha512-OnfpacxUqGPZQ27t8qK9mFa7uqHIlVWeqRqkCbvMvreEBiamEeOn8krKtcwgP5M4cYDPwuSmCTopHMVthqG4zA==}
+  metro-symbolicate@0.84.5:
+    resolution: {integrity: sha512-rQ40zYDAkaWBN9yvjUuAD0ZpzBMZSoKyGYXnb5JrfbKjun7fTvfoLHL3KXFYenBTYZkQtlp4cKSCv/1utxFyOw==}
     engines: {node: ^20.19.4 || ^22.13.0 || ^24.3.0 || >= 25.0.0}
     hasBin: true
 
@@ -5627,8 +5634,8 @@ packages:
     resolution: {integrity: sha512-9JRPkvi+m0QH2Y/w5RjCF9mHqOUNFpMFLDDLhKUjhcKESh8Wm3HKDdHXHVldTN1lTToCIabv81nF0zyJzKEJ5g==}
     engines: {node: '>=20.19.4'}
 
-  metro-transform-plugins@0.84.4:
-    resolution: {integrity: sha512-kehr6HbAecqD0/a3xLXobELdPaAmRAl8bel0qagPF4vhZtux93nS8S4eq2kgKt6J2GnQpVjSoW1PXdst04mwow==}
+  metro-transform-plugins@0.84.5:
+    resolution: {integrity: sha512-+InaSVGaOyt0DyRo4Y/zIdPI6CZwnbNho5LAL23tgmuGwv7fyfkF7kKfPjZcfxXBcoYdTLLFnCfCH/dHSiCqNg==}
     engines: {node: ^20.19.4 || ^22.13.0 || ^24.3.0 || >= 25.0.0}
 
   metro-transform-worker@0.83.7:
@@ -5639,8 +5646,8 @@ packages:
     resolution: {integrity: sha512-Pa2hOfhUmWpI/dmkhsLq8uGyFHK2opoEK7j/YCiRtqNSe0YzzxYguXTNgg8AMiuZfc9LPcB1AhGENS10O5wcIw==}
     engines: {node: '>=20.19.4'}
 
-  metro-transform-worker@0.84.4:
-    resolution: {integrity: sha512-W1IYMvvXTu4MxYr7d9h7CeG2vpIr3bmLLIavkPY4O1ilzDrvS8z/NEe6y+pC44Ff7raMXQgYSfdqDUwN/i39gg==}
+  metro-transform-worker@0.84.5:
+    resolution: {integrity: sha512-ui1Z8x4s5RL36gMmKLaMMO7O9NNDHNdthEZSCDQHAau3JcAsTaFOK6I+2q4I/kW5u8hSEjJk9L45TXSVJw6g1A==}
     engines: {node: ^20.19.4 || ^22.13.0 || ^24.3.0 || >= 25.0.0}
 
   metro@0.83.7:
@@ -5653,8 +5660,8 @@ packages:
     engines: {node: '>=20.19.4'}
     hasBin: true
 
-  metro@0.84.4:
-    resolution: {integrity: sha512-8ETTubqfD6ornDy2zYDvRcKnVDOXdFJsjetYDBsY4oAsb6NJkiwFR+FaMESyGppFmQUyBQA4H4sFGxzcQSGtFA==}
+  metro@0.84.5:
+    resolution: {integrity: sha512-r1liLkyFZMVSEMNjU1CJU5pRzs3NdkxHqXS60O25c0rCIqAR+cGk7rPydw/g0WAIKVXojIBIF45yYBPagJGcgw==}
     engines: {node: ^20.19.4 || ^22.13.0 || ^24.3.0 || >= 25.0.0}
     hasBin: true
 
@@ -5763,8 +5770,9 @@ packages:
   node-int64@0.4.0:
     resolution: {integrity: sha512-O5lz91xSOeoXP6DulyHfllpq+Eg00MWitZIbtPfoSEvqIHdl5gfcY6hYzDWnj0qD5tz52PI08u9qUvSVeUBeHw==}
 
-  node-releases@2.0.38:
-    resolution: {integrity: sha512-3qT/88Y3FbH/Kx4szpQQ4HzUbVrHPKTLVpVocKiLfoYvw9XSGOX2FmD2d6DrXbVYyAQTF2HeF6My8jmzx7/CRw==}
+  node-releases@2.0.54:
+    resolution: {integrity: sha512-YHs7BmmcsdAI5Ozuf8JZo6PT0mv2GIWC9vMfvUC3dp65M8hn7Ux8CPL+2oBI7juNuj9d0ndhTcznq2ODBps9cQ==}
+    engines: {node: '>=18'}
 
   normalize-path@3.0.0:
     resolution: {integrity: sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA==}
@@ -5795,8 +5803,8 @@ packages:
     resolution: {integrity: sha512-pk7el+eTOzfSKMAY4QBiiwKzegXn633JQj13y+pW5E5IdS+yV2CfDJ9Hf20K/LKy8nCrP9dAmd7XOk52OJxifA==}
     engines: {node: '>=20.19.4'}
 
-  ob1@0.84.4:
-    resolution: {integrity: sha512-eJXMpz4aQHXF/YBB9ddqZDIS+ooO91hObo9FoW/xBkr54/zCwYYCDqT/O54vNo8kOkWs5Ou/y28NgdrV0edQNA==}
+  ob1@0.84.5:
+    resolution: {integrity: sha512-aH9RkoZc7w/90HBamFxTw8ZLFr05wXS+iOnvmrgo53Ep8Pyrm5FieQSaPIVROkfFVQISeD/zo92fes26TOwe+A==}
     engines: {node: ^20.19.4 || ^22.13.0 || ^24.3.0 || >= 25.0.0}
 
   object-assign@4.1.1:
@@ -6677,6 +6685,11 @@ packages:
     engines: {node: '>=10'}
     hasBin: true
 
+  terser@5.51.2:
+    resolution: {integrity: sha512-bWnjSNscmuI+GJze6ZupnHP8G/cTcsJF+bXCeQknk2SHQsgbNJnLrqiH9jZ2W4STPVXH2mDKKRX3iwPhc9Cn/Q==}
+    engines: {node: '>=10'}
+    hasBin: true
+
   test-exclude@6.0.0:
     resolution: {integrity: sha512-cAGWPIyOHU6zlmg88jwm7VRyXnMN7iV68OGAbYDk/Mh/xC/pzVPlQtY6ngoIH/5/tciuhGfvESU8GrHrcxD56w==}
     engines: {node: '>=8'}
@@ -6862,8 +6875,8 @@ packages:
     resolution: {integrity: sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==}
     engines: {node: '>= 0.8'}
 
-  update-browserslist-db@1.2.3:
-    resolution: {integrity: sha512-Js0m9cx+qOgDxo0eMiFGEueWztz+d4+M3rGlmKPT+T4IS/jP4ylw3Nwpu6cpTTP8R1MAC1kF4VbdLt3ARf209w==}
+  update-browserslist-db@1.3.2:
+    resolution: {integrity: sha512-UQ+MSxlhRm1bzjhU+DcuXfjFO1FzNtqhK5+9Yvlp90ItDLk5vT932A0rFu619nf7RVS+Y/VeaUW1jaRDqZ8VJw==}
     hasBin: true
     peerDependencies:
       browserslist: '>= 4.21.0'
@@ -7301,7 +7314,7 @@ snapshots:
     dependencies:
       '@babel/compat-data': 7.29.3
       '@babel/helper-validator-option': 7.27.1
-      browserslist: 4.28.2
+      browserslist: 4.28.8
       lru-cache: 5.1.1
       semver: 6.3.1
 
@@ -7309,7 +7322,7 @@ snapshots:
     dependencies:
       '@babel/compat-data': 7.29.7
       '@babel/helper-validator-option': 7.29.7
-      browserslist: 4.28.2
+      browserslist: 4.28.8
       lru-cache: 5.1.1
       semver: 6.3.1
 
@@ -8694,7 +8707,7 @@ snapshots:
       globals: 14.0.0
       ignore: 5.3.2
       import-fresh: 3.3.1
-      js-yaml: 4.3.1
+      js-yaml: 4.3.2
       minimatch: 3.1.5
       strip-json-comments: 3.1.1
     transitivePeerDependencies:
@@ -8773,7 +8786,7 @@ snapshots:
       ws: 8.21.3
       zod: 3.25.76
     optionalDependencies:
-      expo-router: 55.0.18(2f99795f9796def5cdb1516a493dc117)
+      expo-router: 55.0.18(4a60a26fd685ffdcc7f556016ae4bc5e)
       react-native: 0.83.10(patch_hash=44876634a8efbb0f2c3f66cd4332be170ec821d1cbfc0264ac80680983e8513d)(@babel/core@7.29.7)(@react-native/metro-config@0.85.2(@babel/core@7.29.7))(@types/react@19.2.14)(react@19.2.8)
     transitivePeerDependencies:
       - '@expo/dom-webview'
@@ -8985,7 +8998,7 @@ snapshots:
       '@expo/json-file': 10.0.16
       '@expo/metro': 55.1.2
       '@expo/spawn-async': 1.8.0
-      browserslist: 4.28.2
+      browserslist: 4.28.8
       chalk: 4.1.2
       debug: 4.4.3
       getenv: 2.0.0
@@ -9116,7 +9129,7 @@ snapshots:
       react: 19.2.8
     optionalDependencies:
       '@expo/metro-runtime': 55.0.10(@expo/dom-webview@55.0.5)(expo@55.0.30)(react-dom@19.2.8(react@19.2.8))(react-native@0.83.10(patch_hash=44876634a8efbb0f2c3f66cd4332be170ec821d1cbfc0264ac80680983e8513d)(@babel/core@7.29.7)(@react-native/metro-config@0.85.2(@babel/core@7.29.7))(@types/react@19.2.14)(react@19.2.8))(react@19.2.8)
-      expo-router: 55.0.18(2f99795f9796def5cdb1516a493dc117)
+      expo-router: 55.0.18(4a60a26fd685ffdcc7f556016ae4bc5e)
       react-dom: 19.2.8(react@19.2.8)
     transitivePeerDependencies:
       - supports-color
@@ -9201,14 +9214,14 @@ snapshots:
       '@jest/test-result': 29.7.0
       '@jest/transform': 29.7.0
       '@jest/types': 29.6.3
-      '@types/node': 26.1.2
+      '@types/node': 26.4.0
       ansi-escapes: 4.3.2
       chalk: 4.1.2
       ci-info: 3.9.0
       exit: 0.1.2
       graceful-fs: 4.2.11
       jest-changed-files: 29.7.0
-      jest-config: 29.7.0(@types/node@26.1.2)
+      jest-config: 29.7.0(@types/node@26.4.0)
       jest-haste-map: 29.7.0
       jest-message-util: 29.7.0
       jest-regex-util: 29.6.3
@@ -9281,7 +9294,7 @@ snapshots:
       '@jest/transform': 29.7.0
       '@jest/types': 29.6.3
       '@jridgewell/trace-mapping': 0.3.31
-      '@types/node': 26.1.2
+      '@types/node': 26.4.0
       chalk: 4.1.2
       collect-v8-coverage: 1.0.3
       exit: 0.1.2
@@ -9975,8 +9988,8 @@ snapshots:
     dependencies:
       '@react-native/js-polyfills': 0.85.2
       '@react-native/metro-babel-transformer': 0.85.2(@babel/core@7.29.7)
-      metro-config: 0.84.4
-      metro-runtime: 0.84.4
+      metro-config: 0.84.5
+      metro-runtime: 0.84.5
     transitivePeerDependencies:
       - '@babel/core'
       - bufferutil
@@ -10126,7 +10139,7 @@ snapshots:
 
   '@standard-schema/spec@1.1.0': {}
 
-  '@testing-library/react-native@13.3.3(jest@29.7.0(@types/node@26.1.2))(react-native@0.83.10(patch_hash=44876634a8efbb0f2c3f66cd4332be170ec821d1cbfc0264ac80680983e8513d)(@babel/core@7.29.7)(@react-native/metro-config@0.85.2(@babel/core@7.29.7))(@types/react@19.2.14)(react@19.2.8))(react-test-renderer@19.2.8(react@19.2.8))(react@19.2.8)':
+  '@testing-library/react-native@13.3.3(jest@29.7.0(@types/node@26.4.0))(react-native@0.83.10(patch_hash=44876634a8efbb0f2c3f66cd4332be170ec821d1cbfc0264ac80680983e8513d)(@babel/core@7.29.7)(@react-native/metro-config@0.85.2(@babel/core@7.29.7))(@types/react@19.2.14)(react@19.2.8))(react-test-renderer@19.2.8(react@19.2.8))(react@19.2.8)':
     dependencies:
       jest-matcher-utils: 30.3.0
       picocolors: 1.1.1
@@ -10136,7 +10149,7 @@ snapshots:
       react-test-renderer: 19.2.8(react@19.2.8)
       redent: 3.0.0
     optionalDependencies:
-      jest: 29.7.0(@types/node@26.1.2)
+      jest: 29.7.0(@types/node@26.4.0)
 
   '@tootallnate/once@2.0.1': {}
 
@@ -10345,6 +10358,10 @@ snapshots:
     dependencies:
       undici-types: 8.3.0
 
+  '@types/node@26.4.0':
+    dependencies:
+      undici-types: 8.3.0
+
   '@types/react-native@0.73.0(@babel/core@7.29.7)(@react-native/metro-config@0.85.2(@babel/core@7.29.7))(@types/react@19.2.14)(react@19.2.8)':
     dependencies:
       react-native: 0.83.10(patch_hash=44876634a8efbb0f2c3f66cd4332be170ec821d1cbfc0264ac80680983e8513d)(@babel/core@7.29.7)(@react-native/metro-config@0.85.2(@babel/core@7.29.7))(@types/react@19.2.14)(react@19.2.8)
@@ -10525,13 +10542,13 @@ snapshots:
       chai: 6.2.2
       tinyrainbow: 3.1.0
 
-  '@vitest/mocker@4.1.11(vite@8.1.0(@types/node@26.1.2)(esbuild@0.25.4)(terser@5.49.1)(tsx@4.22.4)(yaml@2.9.0))':
+  '@vitest/mocker@4.1.11(vite@8.1.0(@types/node@26.4.0)(esbuild@0.25.4)(terser@5.51.2)(tsx@4.22.4)(yaml@2.9.0))':
     dependencies:
       '@vitest/spy': 4.1.11
       estree-walker: 3.0.3
       magic-string: 0.30.21
     optionalDependencies:
-      vite: 8.1.0(@types/node@26.1.2)(esbuild@0.25.4)(terser@5.49.1)(tsx@4.22.4)(yaml@2.9.0)
+      vite: 8.1.0(@types/node@26.4.0)(esbuild@0.25.4)(terser@5.51.2)(tsx@4.22.4)(yaml@2.9.0)
 
   '@vitest/pretty-format@4.1.11':
     dependencies:
@@ -10934,7 +10951,7 @@ snapshots:
 
   base64-js@1.5.1: {}
 
-  baseline-browser-mapping@2.10.27: {}
+  baseline-browser-mapping@2.11.20: {}
 
   better-opn@3.0.2:
     dependencies:
@@ -10972,13 +10989,13 @@ snapshots:
     dependencies:
       fill-range: 7.1.1
 
-  browserslist@4.28.2:
+  browserslist@4.28.8:
     dependencies:
-      baseline-browser-mapping: 2.10.27
-      caniuse-lite: 1.0.30001792
-      electron-to-chromium: 1.5.352
-      node-releases: 2.0.38
-      update-browserslist-db: 1.2.3(browserslist@4.28.2)
+      baseline-browser-mapping: 2.11.20
+      caniuse-lite: 1.0.30001810
+      electron-to-chromium: 1.5.416
+      node-releases: 2.0.54
+      update-browserslist-db: 1.3.2(browserslist@4.28.8)
 
   bs-logger@0.2.6:
     dependencies:
@@ -11024,7 +11041,7 @@ snapshots:
 
   camelcase@6.3.0: {}
 
-  caniuse-lite@1.0.30001792: {}
+  caniuse-lite@1.0.30001810: {}
 
   chai@6.2.2: {}
 
@@ -11174,7 +11191,7 @@ snapshots:
 
   core-js-compat@3.49.0:
     dependencies:
-      browserslist: 4.28.2
+      browserslist: 4.28.8
 
   cose-base@1.0.3:
     dependencies:
@@ -11184,13 +11201,13 @@ snapshots:
     dependencies:
       layout-base: 2.0.1
 
-  create-jest@29.7.0(@types/node@26.1.2):
+  create-jest@29.7.0(@types/node@26.4.0):
     dependencies:
       '@jest/types': 29.6.3
       chalk: 4.1.2
       exit: 0.1.2
       graceful-fs: 4.2.11
-      jest-config: 29.7.0(@types/node@26.1.2)
+      jest-config: 29.7.0(@types/node@26.4.0)
       jest-util: 29.7.0
       prompts: 2.4.2
     transitivePeerDependencies:
@@ -11554,7 +11571,7 @@ snapshots:
 
   ee-first@1.1.1: {}
 
-  electron-to-chromium@1.5.352: {}
+  electron-to-chromium@1.5.416: {}
 
   emittery@0.13.1: {}
 
@@ -12169,7 +12186,7 @@ snapshots:
       expo: 55.0.30(10e8e71dd92768dd7f344108f3edbbe3)
       expo-json-utils: 55.0.2
 
-  expo-module-scripts@55.0.2(@babel/core@7.29.7)(@babel/runtime@7.29.7)(@jest/types@29.6.3)(babel-jest@29.7.0(@babel/core@7.29.7))(esbuild@0.25.4)(eslint@9.39.4)(expo@55.0.30)(jest@29.7.0(@types/node@26.1.2))(prettier@2.8.8)(react-native@0.83.10(patch_hash=44876634a8efbb0f2c3f66cd4332be170ec821d1cbfc0264ac80680983e8513d)(@babel/core@7.29.7)(@react-native/metro-config@0.85.2(@babel/core@7.29.7))(@types/react@19.2.14)(react@19.2.8))(react-refresh@0.14.2)(react-test-renderer@19.2.8(react@19.2.8))(react@19.2.8):
+  expo-module-scripts@55.0.2(@babel/core@7.29.7)(@babel/runtime@7.29.7)(@jest/types@29.6.3)(babel-jest@29.7.0(@babel/core@7.29.7))(esbuild@0.25.4)(eslint@9.39.4)(expo@55.0.30)(jest@29.7.0(@types/node@26.4.0))(prettier@2.8.8)(react-native@0.83.10(patch_hash=44876634a8efbb0f2c3f66cd4332be170ec821d1cbfc0264ac80680983e8513d)(@babel/core@7.29.7)(@react-native/metro-config@0.85.2(@babel/core@7.29.7))(@types/react@19.2.14)(react@19.2.8))(react-refresh@0.14.2)(react-test-renderer@19.2.8(react@19.2.8))(react@19.2.8):
     dependencies:
       '@babel/cli': 7.28.6(@babel/core@7.29.7)
       '@babel/plugin-transform-export-namespace-from': 7.27.1(@babel/core@7.29.7)
@@ -12177,7 +12194,7 @@ snapshots:
       '@babel/preset-typescript': 7.28.5(@babel/core@7.29.7)
       '@expo/npm-proofread': 1.0.1
       '@expo/spawn-async': 1.7.2
-      '@testing-library/react-native': 13.3.3(jest@29.7.0(@types/node@26.1.2))(react-native@0.83.10(patch_hash=44876634a8efbb0f2c3f66cd4332be170ec821d1cbfc0264ac80680983e8513d)(@babel/core@7.29.7)(@react-native/metro-config@0.85.2(@babel/core@7.29.7))(@types/react@19.2.14)(react@19.2.8))(react-test-renderer@19.2.8(react@19.2.8))(react@19.2.8)
+      '@testing-library/react-native': 13.3.3(jest@29.7.0(@types/node@26.4.0))(react-native@0.83.10(patch_hash=44876634a8efbb0f2c3f66cd4332be170ec821d1cbfc0264ac80680983e8513d)(@babel/core@7.29.7)(@react-native/metro-config@0.85.2(@babel/core@7.29.7))(@types/react@19.2.14)(react@19.2.8))(react-test-renderer@19.2.8(react@19.2.8))(react@19.2.8)
       '@tsconfig/node18': 18.2.6
       '@types/jest': 29.5.14
       babel-plugin-dynamic-import-node: 2.3.3
@@ -12185,11 +12202,11 @@ snapshots:
       commander: 12.1.0
       eslint-config-universe: 15.0.4(eslint@9.39.4)(prettier@2.8.8)(typescript@5.9.3)
       glob: 13.0.6
-      jest-expo: 55.0.17(@babel/core@7.29.7)(expo@55.0.30)(jest@29.7.0(@types/node@26.1.2))(react-native@0.83.10(patch_hash=44876634a8efbb0f2c3f66cd4332be170ec821d1cbfc0264ac80680983e8513d)(@babel/core@7.29.7)(@react-native/metro-config@0.85.2(@babel/core@7.29.7))(@types/react@19.2.14)(react@19.2.8))(react@19.2.8)(typescript@5.9.3)
+      jest-expo: 55.0.17(@babel/core@7.29.7)(expo@55.0.30)(jest@29.7.0(@types/node@26.4.0))(react-native@0.83.10(patch_hash=44876634a8efbb0f2c3f66cd4332be170ec821d1cbfc0264ac80680983e8513d)(@babel/core@7.29.7)(@react-native/metro-config@0.85.2(@babel/core@7.29.7))(@types/react@19.2.14)(react@19.2.8))(react@19.2.8)(typescript@5.9.3)
       jest-snapshot-prettier: prettier@2.8.8
-      jest-watch-typeahead: 2.2.1(jest@29.7.0(@types/node@26.1.2))
+      jest-watch-typeahead: 2.2.1(jest@29.7.0(@types/node@26.4.0))
       resolve-workspace-root: 2.0.1
-      ts-jest: 29.0.5(@babel/core@7.29.7)(@jest/types@29.6.3)(babel-jest@29.7.0(@babel/core@7.29.7))(esbuild@0.25.4)(jest@29.7.0(@types/node@26.1.2))(typescript@5.9.3)
+      ts-jest: 29.0.5(@babel/core@7.29.7)(@jest/types@29.6.3)(babel-jest@29.7.0(@babel/core@7.29.7))(esbuild@0.25.4)(jest@29.7.0(@types/node@26.4.0))(typescript@5.9.3)
       typescript: 5.9.3
     transitivePeerDependencies:
       - '@babel/core'
@@ -12252,7 +12269,7 @@ snapshots:
       - supports-color
       - typescript
 
-  expo-router@55.0.18(2f99795f9796def5cdb1516a493dc117):
+  expo-router@55.0.18(4a60a26fd685ffdcc7f556016ae4bc5e):
     dependencies:
       '@expo/log-box': 55.0.13(@expo/dom-webview@55.0.5)(expo@55.0.30)(react-native@0.83.10(patch_hash=44876634a8efbb0f2c3f66cd4332be170ec821d1cbfc0264ac80680983e8513d)(@babel/core@7.29.7)(@react-native/metro-config@0.85.2(@babel/core@7.29.7))(@types/react@19.2.14)(react@19.2.8))(react@19.2.8)
       '@expo/metro-runtime': 55.0.10(@expo/dom-webview@55.0.5)(expo@55.0.30)(react-dom@19.2.8(react@19.2.8))(react-native@0.83.10(patch_hash=44876634a8efbb0f2c3f66cd4332be170ec821d1cbfc0264ac80680983e8513d)(@babel/core@7.29.7)(@react-native/metro-config@0.85.2(@babel/core@7.29.7))(@types/react@19.2.14)(react@19.2.8))(react@19.2.8)
@@ -12289,7 +12306,7 @@ snapshots:
       use-latest-callback: 0.2.6(react@19.2.8)
       vaul: 1.1.2(@types/react@19.2.14)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
     optionalDependencies:
-      '@testing-library/react-native': 13.3.3(jest@29.7.0(@types/node@26.1.2))(react-native@0.83.10(patch_hash=44876634a8efbb0f2c3f66cd4332be170ec821d1cbfc0264ac80680983e8513d)(@babel/core@7.29.7)(@react-native/metro-config@0.85.2(@babel/core@7.29.7))(@types/react@19.2.14)(react@19.2.8))(react-test-renderer@19.2.8(react@19.2.8))(react@19.2.8)
+      '@testing-library/react-native': 13.3.3(jest@29.7.0(@types/node@26.4.0))(react-native@0.83.10(patch_hash=44876634a8efbb0f2c3f66cd4332be170ec821d1cbfc0264ac80680983e8513d)(@babel/core@7.29.7)(@react-native/metro-config@0.85.2(@babel/core@7.29.7))(@types/react@19.2.14)(react@19.2.8))(react-test-renderer@19.2.8(react@19.2.8))(react@19.2.8)
       react-dom: 19.2.8(react@19.2.8)
       react-native-gesture-handler: 2.31.2(react-native@0.83.10(patch_hash=44876634a8efbb0f2c3f66cd4332be170ec821d1cbfc0264ac80680983e8513d)(@babel/core@7.29.7)(@react-native/metro-config@0.85.2(@babel/core@7.29.7))(@types/react@19.2.14)(react@19.2.8))(react@19.2.8)
       react-native-reanimated: 4.3.4(react-native-worklets@0.8.3(@babel/core@7.29.7)(@react-native/metro-config@0.85.2(@babel/core@7.29.7))(react-native@0.83.10(patch_hash=44876634a8efbb0f2c3f66cd4332be170ec821d1cbfc0264ac80680983e8513d)(@babel/core@7.29.7)(@react-native/metro-config@0.85.2(@babel/core@7.29.7))(@types/react@19.2.14)(react@19.2.8))(react@19.2.8))(react-native@0.83.10(patch_hash=44876634a8efbb0f2c3f66cd4332be170ec821d1cbfc0264ac80680983e8513d)(@babel/core@7.29.7)(@react-native/metro-config@0.85.2(@babel/core@7.29.7))(@types/react@19.2.14)(react@19.2.8))(react@19.2.8)
@@ -12950,7 +12967,7 @@ snapshots:
       '@jest/expect': 29.7.0
       '@jest/test-result': 29.7.0
       '@jest/types': 29.6.3
-      '@types/node': 26.1.2
+      '@types/node': 26.4.0
       chalk: 4.1.2
       co: 4.6.0
       dedent: 1.7.2
@@ -12970,16 +12987,16 @@ snapshots:
       - babel-plugin-macros
       - supports-color
 
-  jest-cli@29.7.0(@types/node@26.1.2):
+  jest-cli@29.7.0(@types/node@26.4.0):
     dependencies:
       '@jest/core': 29.7.0
       '@jest/test-result': 29.7.0
       '@jest/types': 29.6.3
       chalk: 4.1.2
-      create-jest: 29.7.0(@types/node@26.1.2)
+      create-jest: 29.7.0(@types/node@26.4.0)
       exit: 0.1.2
       import-local: 3.2.0
-      jest-config: 29.7.0(@types/node@26.1.2)
+      jest-config: 29.7.0(@types/node@26.4.0)
       jest-util: 29.7.0
       jest-validate: 29.7.0
       yargs: 17.7.3
@@ -12989,7 +13006,7 @@ snapshots:
       - supports-color
       - ts-node
 
-  jest-config@29.7.0(@types/node@26.1.2):
+  jest-config@29.7.0(@types/node@26.4.0):
     dependencies:
       '@babel/core': 7.29.7
       '@jest/test-sequencer': 29.7.0
@@ -13014,7 +13031,7 @@ snapshots:
       slash: 3.0.0
       strip-json-comments: 3.1.1
     optionalDependencies:
-      '@types/node': 26.1.2
+      '@types/node': 26.4.0
     transitivePeerDependencies:
       - babel-plugin-macros
       - supports-color
@@ -13069,7 +13086,7 @@ snapshots:
       jest-mock: 29.7.0
       jest-util: 29.7.0
 
-  jest-expo@55.0.17(@babel/core@7.29.7)(expo@55.0.30)(jest@29.7.0(@types/node@26.1.2))(react-native@0.83.10(patch_hash=44876634a8efbb0f2c3f66cd4332be170ec821d1cbfc0264ac80680983e8513d)(@babel/core@7.29.7)(@react-native/metro-config@0.85.2(@babel/core@7.29.7))(@types/react@19.2.14)(react@19.2.8))(react@19.2.8)(typescript@5.9.3):
+  jest-expo@55.0.17(@babel/core@7.29.7)(expo@55.0.30)(jest@29.7.0(@types/node@26.4.0))(react-native@0.83.10(patch_hash=44876634a8efbb0f2c3f66cd4332be170ec821d1cbfc0264ac80680983e8513d)(@babel/core@7.29.7)(@react-native/metro-config@0.85.2(@babel/core@7.29.7))(@types/react@19.2.14)(react@19.2.8))(react@19.2.8)(typescript@5.9.3):
     dependencies:
       '@expo/config': 55.0.16(typescript@5.9.3)
       '@expo/json-file': 10.0.14
@@ -13080,7 +13097,7 @@ snapshots:
       jest-environment-jsdom: 29.7.0
       jest-snapshot: 29.7.0
       jest-watch-select-projects: 2.0.0
-      jest-watch-typeahead: 2.2.1(jest@29.7.0(@types/node@26.1.2))
+      jest-watch-typeahead: 2.2.1(jest@29.7.0(@types/node@26.4.0))
       json5: 2.2.3
       lodash: 4.18.1
       react-native: 0.83.10(patch_hash=44876634a8efbb0f2c3f66cd4332be170ec821d1cbfc0264ac80680983e8513d)(@babel/core@7.29.7)(@react-native/metro-config@0.85.2(@babel/core@7.29.7))(@types/react@19.2.14)(react@19.2.8)
@@ -13184,7 +13201,7 @@ snapshots:
       '@jest/test-result': 29.7.0
       '@jest/transform': 29.7.0
       '@jest/types': 29.6.3
-      '@types/node': 26.1.2
+      '@types/node': 26.4.0
       chalk: 4.1.2
       emittery: 0.13.1
       graceful-fs: 4.2.11
@@ -13212,7 +13229,7 @@ snapshots:
       '@jest/test-result': 29.7.0
       '@jest/transform': 29.7.0
       '@jest/types': 29.6.3
-      '@types/node': 26.1.2
+      '@types/node': 26.4.0
       chalk: 4.1.2
       cjs-module-lexer: 1.4.3
       collect-v8-coverage: 1.0.3
@@ -13279,11 +13296,11 @@ snapshots:
       chalk: 3.0.0
       prompts: 2.4.2
 
-  jest-watch-typeahead@2.2.1(jest@29.7.0(@types/node@26.1.2)):
+  jest-watch-typeahead@2.2.1(jest@29.7.0(@types/node@26.4.0)):
     dependencies:
       ansi-escapes: 6.2.1
       chalk: 4.1.2
-      jest: 29.7.0(@types/node@26.1.2)
+      jest: 29.7.0(@types/node@26.4.0)
       jest-regex-util: 29.6.3
       jest-watcher: 29.7.0
       slash: 5.1.0
@@ -13308,12 +13325,12 @@ snapshots:
       merge-stream: 2.0.0
       supports-color: 8.1.1
 
-  jest@29.7.0(@types/node@26.1.2):
+  jest@29.7.0(@types/node@26.4.0):
     dependencies:
       '@jest/core': 29.7.0
       '@jest/types': 29.6.3
       import-local: 3.2.0
-      jest-cli: 29.7.0(@types/node@26.1.2)
+      jest-cli: 29.7.0(@types/node@26.4.0)
     transitivePeerDependencies:
       - '@types/node'
       - babel-plugin-macros
@@ -13333,6 +13350,10 @@ snapshots:
     dependencies:
       argparse: 2.0.1
 
+  js-yaml@4.3.2:
+    dependencies:
+      argparse: 2.0.1
+
   jsc-safe-url@0.2.4: {}
 
   jsdom@20.0.3:
@@ -13604,12 +13625,12 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  metro-babel-transformer@0.84.4:
+  metro-babel-transformer@0.84.5:
     dependencies:
       '@babel/core': 7.29.7
       flow-enums-runtime: 0.0.6
       hermes-parser: 0.35.0
-      metro-cache-key: 0.84.4
+      metro-cache-key: 0.84.5
       nullthrows: 1.1.1
     transitivePeerDependencies:
       - supports-color
@@ -13622,7 +13643,7 @@ snapshots:
     dependencies:
       flow-enums-runtime: 0.0.6
 
-  metro-cache-key@0.84.4:
+  metro-cache-key@0.84.5:
     dependencies:
       flow-enums-runtime: 0.0.6
 
@@ -13644,12 +13665,12 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  metro-cache@0.84.4:
+  metro-cache@0.84.5:
     dependencies:
       exponential-backoff: 3.1.3
       flow-enums-runtime: 0.0.6
       https-proxy-agent: 7.0.6
-      metro-core: 0.84.4
+      metro-core: 0.84.5
     transitivePeerDependencies:
       - supports-color
 
@@ -13683,15 +13704,15 @@ snapshots:
       - supports-color
       - utf-8-validate
 
-  metro-config@0.84.4:
+  metro-config@0.84.5:
     dependencies:
       connect: 3.7.0
       flow-enums-runtime: 0.0.6
       jest-validate: 29.7.0
-      metro: 0.84.4
-      metro-cache: 0.84.4
-      metro-core: 0.84.4
-      metro-runtime: 0.84.4
+      metro: 0.84.5
+      metro-cache: 0.84.5
+      metro-core: 0.84.5
+      metro-runtime: 0.84.5
       yaml: 2.9.0
     transitivePeerDependencies:
       - bufferutil
@@ -13710,11 +13731,11 @@ snapshots:
       lodash.throttle: 4.1.1
       metro-resolver: 0.83.8
 
-  metro-core@0.84.4:
+  metro-core@0.84.5:
     dependencies:
       flow-enums-runtime: 0.0.6
       lodash.throttle: 4.1.1
-      metro-resolver: 0.84.4
+      metro-resolver: 0.84.5
 
   metro-file-map@0.83.7:
     dependencies:
@@ -13744,7 +13765,7 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  metro-file-map@0.84.4:
+  metro-file-map@0.84.5:
     dependencies:
       debug: 4.4.3
       fb-watchman: 2.0.2
@@ -13768,10 +13789,10 @@ snapshots:
       flow-enums-runtime: 0.0.6
       terser: 5.49.1
 
-  metro-minify-terser@0.84.4:
+  metro-minify-terser@0.84.5:
     dependencies:
       flow-enums-runtime: 0.0.6
-      terser: 5.49.1
+      terser: 5.51.2
 
   metro-resolver@0.83.7:
     dependencies:
@@ -13781,7 +13802,7 @@ snapshots:
     dependencies:
       flow-enums-runtime: 0.0.6
 
-  metro-resolver@0.84.4:
+  metro-resolver@0.84.5:
     dependencies:
       flow-enums-runtime: 0.0.6
 
@@ -13795,7 +13816,7 @@ snapshots:
       '@babel/runtime': 7.29.7
       flow-enums-runtime: 0.0.6
 
-  metro-runtime@0.84.4:
+  metro-runtime@0.84.5:
     dependencies:
       '@babel/runtime': 7.29.7
       flow-enums-runtime: 0.0.6
@@ -13828,15 +13849,15 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  metro-source-map@0.84.4:
+  metro-source-map@0.84.5:
     dependencies:
       '@babel/traverse': 7.29.8
       '@babel/types': 7.29.8
       flow-enums-runtime: 0.0.6
       invariant: 2.2.4
-      metro-symbolicate: 0.84.4
+      metro-symbolicate: 0.84.5
       nullthrows: 1.1.1
-      ob1: 0.84.4
+      ob1: 0.84.5
       source-map: 0.5.7
       vlq: 1.0.1
     transitivePeerDependencies:
@@ -13864,11 +13885,11 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  metro-symbolicate@0.84.4:
+  metro-symbolicate@0.84.5:
     dependencies:
       flow-enums-runtime: 0.0.6
       invariant: 2.2.4
-      metro-source-map: 0.84.4
+      metro-source-map: 0.84.5
       nullthrows: 1.1.1
       source-map: 0.5.7
       vlq: 1.0.1
@@ -13897,7 +13918,7 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  metro-transform-plugins@0.84.4:
+  metro-transform-plugins@0.84.5:
     dependencies:
       '@babel/core': 7.29.7
       '@babel/generator': 7.29.8
@@ -13948,20 +13969,20 @@ snapshots:
       - supports-color
       - utf-8-validate
 
-  metro-transform-worker@0.84.4:
+  metro-transform-worker@0.84.5:
     dependencies:
       '@babel/core': 7.29.7
       '@babel/generator': 7.29.8
       '@babel/parser': 7.29.8
       '@babel/types': 7.29.8
       flow-enums-runtime: 0.0.6
-      metro: 0.84.4
-      metro-babel-transformer: 0.84.4
-      metro-cache: 0.84.4
-      metro-cache-key: 0.84.4
-      metro-minify-terser: 0.84.4
-      metro-source-map: 0.84.4
-      metro-transform-plugins: 0.84.4
+      metro: 0.84.5
+      metro-babel-transformer: 0.84.5
+      metro-cache: 0.84.5
+      metro-cache-key: 0.84.5
+      metro-minify-terser: 0.84.5
+      metro-source-map: 0.84.5
+      metro-transform-plugins: 0.84.5
       nullthrows: 1.1.1
     transitivePeerDependencies:
       - bufferutil
@@ -14059,7 +14080,7 @@ snapshots:
       - supports-color
       - utf-8-validate
 
-  metro@0.84.4:
+  metro@0.84.5:
     dependencies:
       '@babel/code-frame': 7.29.7
       '@babel/core': 7.29.7
@@ -14076,23 +14097,22 @@ snapshots:
       flow-enums-runtime: 0.0.6
       graceful-fs: 4.2.11
       hermes-parser: 0.35.0
-      image-size: 1.2.1
       invariant: 2.2.4
       jest-worker: 29.7.0
       jsc-safe-url: 0.2.4
       lodash.throttle: 4.1.1
-      metro-babel-transformer: 0.84.4
-      metro-cache: 0.84.4
-      metro-cache-key: 0.84.4
-      metro-config: 0.84.4
-      metro-core: 0.84.4
-      metro-file-map: 0.84.4
-      metro-resolver: 0.84.4
-      metro-runtime: 0.84.4
-      metro-source-map: 0.84.4
-      metro-symbolicate: 0.84.4
-      metro-transform-plugins: 0.84.4
-      metro-transform-worker: 0.84.4
+      metro-babel-transformer: 0.84.5
+      metro-cache: 0.84.5
+      metro-cache-key: 0.84.5
+      metro-config: 0.84.5
+      metro-core: 0.84.5
+      metro-file-map: 0.84.5
+      metro-resolver: 0.84.5
+      metro-runtime: 0.84.5
+      metro-source-map: 0.84.5
+      metro-symbolicate: 0.84.5
+      metro-transform-plugins: 0.84.5
+      metro-transform-worker: 0.84.5
       mime-types: 3.0.2
       nullthrows: 1.1.1
       serialize-error: 2.1.0
@@ -14175,7 +14195,7 @@ snapshots:
 
   node-int64@0.4.0: {}
 
-  node-releases@2.0.38: {}
+  node-releases@2.0.54: {}
 
   normalize-path@3.0.0: {}
 
@@ -14206,7 +14226,7 @@ snapshots:
     dependencies:
       flow-enums-runtime: 0.0.6
 
-  ob1@0.84.4:
+  ob1@0.84.5:
     dependencies:
       flow-enums-runtime: 0.0.6
 
@@ -15212,6 +15232,13 @@ snapshots:
       commander: 2.20.3
       source-map-support: 0.5.21
 
+  terser@5.51.2:
+    dependencies:
+      '@jridgewell/source-map': 0.3.11
+      acorn: 8.15.0
+      commander: 2.20.3
+      source-map-support: 0.5.21
+
   test-exclude@6.0.0:
     dependencies:
       '@istanbuljs/schema': 0.1.6
@@ -15267,11 +15294,11 @@ snapshots:
 
   ts-dedent@2.3.0: {}
 
-  ts-jest@29.0.5(@babel/core@7.29.7)(@jest/types@29.6.3)(babel-jest@29.7.0(@babel/core@7.29.7))(esbuild@0.25.4)(jest@29.7.0(@types/node@26.1.2))(typescript@5.9.3):
+  ts-jest@29.0.5(@babel/core@7.29.7)(@jest/types@29.6.3)(babel-jest@29.7.0(@babel/core@7.29.7))(esbuild@0.25.4)(jest@29.7.0(@types/node@26.4.0))(typescript@5.9.3):
     dependencies:
       bs-logger: 0.2.6
       fast-json-stable-stringify: 2.1.0
-      jest: 29.7.0(@types/node@26.1.2)
+      jest: 29.7.0(@types/node@26.4.0)
       jest-util: 29.7.0
       json5: 2.2.3
       lodash.memoize: 4.1.2
@@ -15381,9 +15408,9 @@ snapshots:
 
   unpipe@1.0.0: {}
 
-  update-browserslist-db@1.2.3(browserslist@4.28.2):
+  update-browserslist-db@1.3.2(browserslist@4.28.8):
     dependencies:
-      browserslist: 4.28.2
+      browserslist: 4.28.8
       escalade: 3.2.0
       picocolors: 1.1.1
 
@@ -15442,7 +15469,7 @@ snapshots:
       - '@types/react'
       - '@types/react-dom'
 
-  vite@8.1.0(@types/node@26.1.2)(esbuild@0.25.4)(terser@5.49.1)(tsx@4.22.4)(yaml@2.9.0):
+  vite@8.1.0(@types/node@26.4.0)(esbuild@0.25.4)(terser@5.51.2)(tsx@4.22.4)(yaml@2.9.0):
     dependencies:
       lightningcss: 1.32.0
       picomatch: 4.0.4
@@ -15450,17 +15477,17 @@ snapshots:
       rolldown: 1.1.3
       tinyglobby: 0.2.17
     optionalDependencies:
-      '@types/node': 26.1.2
+      '@types/node': 26.4.0
       esbuild: 0.25.4
       fsevents: 2.3.3
-      terser: 5.49.1
+      terser: 5.51.2
       tsx: 4.22.4
       yaml: 2.9.0
 
-  vitest@4.1.11(@types/node@26.1.2)(happy-dom@20.11.8)(jsdom@20.0.3)(vite@8.1.0(@types/node@26.1.2)(esbuild@0.25.4)(terser@5.49.1)(tsx@4.22.4)(yaml@2.9.0)):
+  vitest@4.1.11(@types/node@26.4.0)(happy-dom@20.11.8)(jsdom@20.0.3)(vite@8.1.0(@types/node@26.4.0)(esbuild@0.25.4)(terser@5.51.2)(tsx@4.22.4)(yaml@2.9.0)):
     dependencies:
       '@vitest/expect': 4.1.11
-      '@vitest/mocker': 4.1.11(vite@8.1.0(@types/node@26.1.2)(esbuild@0.25.4)(terser@5.49.1)(tsx@4.22.4)(yaml@2.9.0))
+      '@vitest/mocker': 4.1.11(vite@8.1.0(@types/node@26.4.0)(esbuild@0.25.4)(terser@5.51.2)(tsx@4.22.4)(yaml@2.9.0))
       '@vitest/pretty-format': 4.1.11
       '@vitest/runner': 4.1.11
       '@vitest/snapshot': 4.1.11
@@ -15477,10 +15504,10 @@ snapshots:
       tinyexec: 1.1.2
       tinyglobby: 0.2.17
       tinyrainbow: 3.1.0
-      vite: 8.1.0(@types/node@26.1.2)(esbuild@0.25.4)(terser@5.49.1)(tsx@4.22.4)(yaml@2.9.0)
+      vite: 8.1.0(@types/node@26.4.0)(esbuild@0.25.4)(terser@5.51.2)(tsx@4.22.4)(yaml@2.9.0)
       why-is-node-running: 2.3.0
     optionalDependencies:
-      '@types/node': 26.1.2
+      '@types/node': 26.4.0
       happy-dom: 20.11.8
       jsdom: 20.0.3
     transitivePeerDependencies:

From a7db6c336b35a7645a00049cf4d95e69c47db9ef Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Tue, 1 Sep 2026 20:19:56 -0700
Subject: [PATCH 30/32] perf(git): skip the sparse probe for worktree listings
 that never read it (#18050)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three main-process call sites list a repo's worktrees to read `worktree.path`
and nothing else, but went through the annotated listing, so each one paid a
sparse-checkout probe per worktree and cached the result nobody consumed:

- `registered-worktree-roots-cache.ts` rebuilds the filesystem-auth authorized
  roots. `invalidateAuthorizedRootsCache()` fires on every worktree create and
  remove, plus repo add/clone/settings changes, so this reruns constantly.
- `filesystem-source-control-ai-targets.ts` checks whether a local repo owns a
  worktree path.
- `hosted-review.ts` verifies a worktree belongs to the repo before granting
  access.

The probe is an `fs.stat` of the per-worktree `info/sparse-checkout` plus, when
that file is non-empty, a git config read. On a WSL-hosted repo both cross 9p.
#17859 cached it and #17932 keyed that cache on the distro, which fixed a wrong
answer but also meant the distro-less callers above populate a second entry per
worktree — probed cold, revalidated on their own five-minute loop, and read by
nobody. Worktree create/remove clears the sparse cache and dirties the roots
cache together, so both variants go cold at once and the discarded half is
re-probed in full on the next auth check.

`listRepoWorktreeGraph` routes those callers to `listWorktreeGraph`, which
already existed as the annotation-free listing (#17655).

Doing only that would have cost a second `git worktree list`. The scan cache
keys in-flight scans on a `kind`, and graph and lenient were separate kinds, so
a roots rebuild overlapping a sidebar refresh would spawn its own subprocess
where the two previously coalesced. That is a real regression on macOS, Linux
and native Windows, where `getLocalProjectWorktreeGitOptions` returns `{}` and
both callers land on the identical key; on WSL they already differ by distro and
never shared.

So the annotated listing is now the graph listing plus annotation, rather than a
parallel scan of its own: `listWorktrees` awaits `listWorktreeGraph` and
annotates the rows it returns. Both soften a Git failure to `[]`, so they can
share one listing; strict keeps its own because it must be able to reject. The
two kinds ran Git twice before and now run it once, so the overlap case gets
strictly faster instead of paying for the opt-out.

An annotated scan holds two in-flight entries now (its own, plus the graph
listing it shares). Keeping its own entry matters: `detectSparseCheckoutCached`
dedupes revalidation but not the initial fill, so two concurrent badge readers
sharing only the graph scan would both probe.

Per-platform delta:
- macOS/Linux: fewer probes on the three call sites; one `git worktree list`
  instead of two when a graph and an annotated scan overlap.
- native Windows, no WSL: same, and the saved subprocess is the expensive half.
- Windows + WSL: the largest win. The discarded probes were 9p round-trips
  re-paid cold after every worktree create/remove.
- SSH/relay: none. `listRepoWorktreeGraph` returns through the same provider
  branch as `listRepoWorktrees` before reaching local Git.
- folder workspaces: none. Both return the same synthetic folder worktree.

Not in this change:
- The badge listing itself. It still probes, still annotates, and still keys on
  the distro exactly as #17932 left it.
- The remaining `listRepoWorktrees` callers. They read `isSparse`, or feed rows
  to something that does.
---
 src/main/git/worktree-listing.ts              |  2 +-
 ...rktree-scan-cache-annotation-reuse.test.ts | 93 +++++++++++++++++++
 .../git/worktree-scan-cache-sharing.test.ts   | 38 ++++++--
 src/main/git/worktree-scan-cache.ts           | 22 ++++-
 .../ipc/created-worktree-root-prune.test.ts   |  8 +-
 src/main/ipc/filesystem-auth.test.ts          | 26 +++---
 src/main/ipc/filesystem-test-harness.ts       |  1 +
 .../filesystem-source-control-ai-targets.ts   |  4 +-
 src/main/ipc/hosted-review.test.ts            | 16 ++--
 src/main/ipc/hosted-review.ts                 |  8 +-
 .../ipc/registered-worktree-roots-cache.ts    |  4 +-
 src/main/repo-worktrees.test.ts               | 49 +++++++++-
 src/main/repo-worktrees.ts                    | 25 ++++-
 13 files changed, 250 insertions(+), 46 deletions(-)
 create mode 100644 src/main/git/worktree-scan-cache-annotation-reuse.test.ts

diff --git a/src/main/git/worktree-listing.ts b/src/main/git/worktree-listing.ts
index 6abb5a099c6..a60819181d4 100644
--- a/src/main/git/worktree-listing.ts
+++ b/src/main/git/worktree-listing.ts
@@ -97,7 +97,7 @@ export async function listWorktreesStrict(
   return annotateSparseCheckoutStatus(repoPath, visibleWorktrees, options)
 }
 
-async function annotateSparseCheckoutStatus(
+export async function annotateSparseCheckoutStatus(
   repoPath: string,
   worktrees: GitWorktreeInfo[],
   options: GitWorktreeExecOptions = {}
diff --git a/src/main/git/worktree-scan-cache-annotation-reuse.test.ts b/src/main/git/worktree-scan-cache-annotation-reuse.test.ts
new file mode 100644
index 00000000000..0fabe5ba049
--- /dev/null
+++ b/src/main/git/worktree-scan-cache-annotation-reuse.test.ts
@@ -0,0 +1,93 @@
+// The annotated listing is the graph listing plus a sparse probe: callers that read only
+// `worktree.path` must skip the probe, without costing a second `git worktree list`.
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { GitWorktreeInfo } from '../../shared/worktree/types'
+
+const { detectSparseCheckoutMock, readWorktreeListMock, readTranslatedWorktreeGraphMock } =
+  vi.hoisted(() => ({
+    detectSparseCheckoutMock: vi.fn(),
+    readWorktreeListMock: vi.fn(),
+    readTranslatedWorktreeGraphMock: vi.fn()
+  }))
+
+vi.mock('./worktree-sparse-state', () => ({
+  detectSparseCheckout: detectSparseCheckoutMock,
+  resolveGitCommonDir: vi.fn()
+}))
+vi.mock('./worktree-list-reader', () => ({
+  readCheckedOutBranchRef: vi.fn(),
+  readRepoCommonDirFromGit: vi.fn(),
+  readRepoLocation: vi.fn(),
+  readTranslatedWorktreeGraph: readTranslatedWorktreeGraphMock,
+  readWorktreeHeadOid: vi.fn(),
+  readWorktreeList: readWorktreeListMock
+}))
+
+import { _resetWorktreeScanCacheForTests, listWorktreeGraph, listWorktrees } from './worktree'
+import { __resetSparseCheckoutStateCacheForTests } from './worktree-sparse-checkout-cache'
+
+const REPO = '\\\\wsl.localhost\\Ubuntu\\home\\me\\repo'
+const ROW: GitWorktreeInfo = {
+  path: 'C:\\wt\\x',
+  head: 'a'.repeat(40),
+  branch: 'refs/heads/feature',
+  isBare: false,
+  isMainWorktree: false
+}
+
+describe('graph and annotated worktree scans', () => {
+  beforeEach(() => {
+    detectSparseCheckoutMock.mockReset()
+    detectSparseCheckoutMock.mockResolvedValue(true)
+    readWorktreeListMock.mockReset()
+    readWorktreeListMock.mockResolvedValue([ROW])
+    readTranslatedWorktreeGraphMock.mockReset()
+    readTranslatedWorktreeGraphMock.mockResolvedValue([ROW])
+    _resetWorktreeScanCacheForTests()
+    __resetSparseCheckoutStateCacheForTests()
+  })
+
+  it('does not probe sparse state for a graph scan', async () => {
+    const rows = await listWorktreeGraph(REPO, { wslDistro: 'Ubuntu' })
+
+    expect(rows[0]?.path).toBe('C:\\wt\\x')
+    expect(rows[0]?.isSparse).toBeUndefined()
+    expect(detectSparseCheckoutMock).not.toHaveBeenCalled()
+  })
+
+  it('still probes sparse state for the annotated scan', async () => {
+    const rows = await listWorktrees(REPO, { wslDistro: 'Ubuntu' })
+
+    expect(rows[0]?.isSparse).toBe(true)
+    expect(detectSparseCheckoutMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('reads the git listing once for an overlapping graph and annotated scan', async () => {
+    const [graphRows, annotatedRows] = await Promise.all([
+      listWorktreeGraph(REPO, { wslDistro: 'Ubuntu' }),
+      listWorktrees(REPO, { wslDistro: 'Ubuntu' })
+    ])
+
+    expect(readTranslatedWorktreeGraphMock).toHaveBeenCalledTimes(1)
+    expect(graphRows[0]?.isSparse).toBeUndefined()
+    expect(annotatedRows[0]?.isSparse).toBe(true)
+  })
+
+  // Sharing the listing must not make the probe-free caller wait on the probe it opted out of.
+  it('resolves a graph scan while the annotated scan is still probing', async () => {
+    let releaseProbe!: () => void
+    detectSparseCheckoutMock.mockImplementation(
+      () =>
+        new Promise((resolve) => {
+          releaseProbe = () => resolve(true)
+        })
+    )
+
+    const annotatedScan = listWorktrees(REPO, { wslDistro: 'Ubuntu' })
+    const graphRows = await listWorktreeGraph(REPO, { wslDistro: 'Ubuntu' })
+
+    expect(graphRows[0]?.path).toBe('C:\\wt\\x')
+    releaseProbe()
+    expect((await annotatedScan)[0]?.isSparse).toBe(true)
+  })
+})
diff --git a/src/main/git/worktree-scan-cache-sharing.test.ts b/src/main/git/worktree-scan-cache-sharing.test.ts
index d64ec2d4852..2a687420cd8 100644
--- a/src/main/git/worktree-scan-cache-sharing.test.ts
+++ b/src/main/git/worktree-scan-cache-sharing.test.ts
@@ -98,7 +98,9 @@ describe('listWorktrees in-flight sharing', () => {
     expect(gitExecFileAsyncMock).toHaveBeenCalledTimes(1)
   })
 
-  it('keeps graph and annotated scans separate despite sharing the same Git listing', async () => {
+  // The annotated scan is the graph scan plus a sparse probe, so the two share one `git worktree
+  // list` and only the annotated caller pays the probe. They ran Git twice before.
+  it('runs one git listing for concurrent graph and annotated scans', async () => {
     const resolvers: ((value: { stdout: string }) => void)[] = []
     gitExecFileAsyncMock.mockImplementation(
       () =>
@@ -109,13 +111,34 @@ describe('listWorktrees in-flight sharing', () => {
 
     const graphScan = listWorktreeGraph('/repo')
     const annotatedScan = listWorktrees('/repo')
-    expect(resolvers).toHaveLength(2)
+    expect(resolvers).toHaveLength(1)
 
     for (const resolve of resolvers) {
       resolve({ stdout: 'worktree /repo\nHEAD abc123\nbranch refs/heads/main\n' })
     }
     await Promise.all([graphScan, annotatedScan])
-    expect(gitExecFileAsyncMock).toHaveBeenCalledTimes(2)
+    expect(gitExecFileAsyncMock).toHaveBeenCalledTimes(1)
+  })
+
+  // Order must not matter: whichever runs first owns the listing and the other joins it.
+  it('runs one git listing when the annotated scan starts first', async () => {
+    const resolvers: ((value: { stdout: string }) => void)[] = []
+    gitExecFileAsyncMock.mockImplementation(
+      () =>
+        new Promise((resolve) => {
+          resolvers.push(resolve)
+        })
+    )
+
+    const annotatedScan = listWorktrees('/repo')
+    const graphScan = listWorktreeGraph('/repo')
+    expect(resolvers).toHaveLength(1)
+
+    for (const resolve of resolvers) {
+      resolve({ stdout: 'worktree /repo\nHEAD abc123\nbranch refs/heads/main\n' })
+    }
+    await Promise.all([annotatedScan, graphScan])
+    expect(gitExecFileAsyncMock).toHaveBeenCalledTimes(1)
   })
 
   it('keeps graph scans with an AbortSignal isolated from shared callers', async () => {
@@ -352,14 +375,15 @@ describe('listWorktrees in-flight sharing', () => {
     expect(scanResolvers).toHaveLength(1)
 
     await moveWorktree('/repo', '/repo-old', '/repo-new')
-    expect(_getWorktreeScanCacheSizesForTests()).toEqual({ inFlight: 1, generations: 1 })
+    // Two entries per annotated scan: its own, plus the graph listing it shares with probe-free callers.
+    expect(_getWorktreeScanCacheSizesForTests()).toEqual({ inFlight: 2, generations: 1 })
 
     const freshScan = listWorktrees('/repo')
-    expect(_getWorktreeScanCacheSizesForTests()).toEqual({ inFlight: 2, generations: 1 })
+    expect(_getWorktreeScanCacheSizesForTests()).toEqual({ inFlight: 4, generations: 1 })
 
     scanResolvers[1]?.('worktree /repo-new\nHEAD fresh\nbranch refs/heads/main\n')
     expect((await freshScan)[0]?.path).toBe('/repo-new')
-    expect(_getWorktreeScanCacheSizesForTests()).toEqual({ inFlight: 1, generations: 1 })
+    expect(_getWorktreeScanCacheSizesForTests()).toEqual({ inFlight: 2, generations: 1 })
 
     scanResolvers[0]?.('worktree /repo\nHEAD stale\nbranch refs/heads/main\n')
     expect((await staleScan)[0]?.path).toBe('/repo')
@@ -396,7 +420,7 @@ describe('listWorktrees in-flight sharing', () => {
     const newestScan = listWorktrees('/repo')
 
     expect(listCalls).toBe(3)
-    expect(_getWorktreeScanCacheSizesForTests()).toEqual({ inFlight: 3, generations: 1 })
+    expect(_getWorktreeScanCacheSizesForTests()).toEqual({ inFlight: 6, generations: 1 })
 
     scanResolvers[0]?.()
     scanResolvers[2]?.()
diff --git a/src/main/git/worktree-scan-cache.ts b/src/main/git/worktree-scan-cache.ts
index 327aead5f2e..59a7691fe7f 100644
--- a/src/main/git/worktree-scan-cache.ts
+++ b/src/main/git/worktree-scan-cache.ts
@@ -1,8 +1,8 @@
 import type { GitWorktreeInfo } from '../../shared/worktree/types'
 import {
+  annotateSparseCheckoutStatus,
   listWorktreeGraph as listWorktreeGraphUnshared,
-  listWorktreesStrict as listWorktreesStrictUnshared,
-  listWorktreesUnshared
+  listWorktreesStrict as listWorktreesStrictUnshared
 } from './worktree-listing'
 import type { GitWorktreeExecOptions } from './worktree-operation-options'
 import { WORKTREE_LIST_TIMEOUT_MS } from './worktree-operation-options'
@@ -90,6 +90,22 @@ function shareWorktreeScan(
   return scan
 }
 
+/**
+ * Sparse annotation layered over the shared graph scan rather than its own `git worktree list`.
+ *
+ * Both paths soften a Git failure to `[]`, so they can share one listing; only this one pays the
+ * per-worktree sparse probe. That lets a caller which reads just `worktree.path` skip the probes
+ * without costing a second subprocess when it overlaps a badge reader — the two ran Git twice
+ * before. Strict stays on its own scan because it must be able to reject.
+ */
+async function runAnnotatedWorktreeScan(
+  repoPath: string,
+  options: GitWorktreeExecOptions
+): Promise<GitWorktreeInfo[]> {
+  const worktrees = await listWorktreeGraph(repoPath, options)
+  return annotateSparseCheckoutStatus(repoPath, worktrees, options)
+}
+
 /**
  * List all worktrees for a git repo at the given path. Concurrent calls for
  * the same repo share one scan (unless the caller passes an AbortSignal,
@@ -99,7 +115,7 @@ export function listWorktrees(
   repoPath: string,
   options: GitWorktreeExecOptions = {}
 ): Promise<GitWorktreeInfo[]> {
-  return shareWorktreeScan(repoPath, options, 'lenient', listWorktreesUnshared)
+  return shareWorktreeScan(repoPath, options, 'lenient', runAnnotatedWorktreeScan)
 }
 
 /**
diff --git a/src/main/ipc/created-worktree-root-prune.test.ts b/src/main/ipc/created-worktree-root-prune.test.ts
index 9114e34a07c..30808d7d79e 100644
--- a/src/main/ipc/created-worktree-root-prune.test.ts
+++ b/src/main/ipc/created-worktree-root-prune.test.ts
@@ -2,7 +2,7 @@ import type * as NodeFsPromises from 'node:fs/promises'
 import { resolve } from 'node:path'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import type * as RepoWorktrees from '../repo-worktrees'
-import { listRepoWorktrees } from '../repo-worktrees'
+import { listRepoWorktreeGraph } from '../repo-worktrees'
 import type { Store } from '../persistence'
 import type { Repo } from '../../shared/repo-types'
 import {
@@ -22,7 +22,7 @@ vi.mock('node:fs/promises', async () => {
 
 vi.mock('../repo-worktrees', async () => {
   const actual = await vi.importActual<typeof RepoWorktrees>('../repo-worktrees')
-  return { ...actual, listRepoWorktrees: vi.fn() }
+  return { ...actual, listRepoWorktreeGraph: vi.fn() }
 })
 
 const repo: Repo = {
@@ -56,10 +56,10 @@ describe('recovered worktree root pruning', () => {
   beforeEach(() => {
     invalidateAuthorizedRootsCache()
     __resetCreatedWorktreeRootsForTests()
-    vi.mocked(listRepoWorktrees).mockReset()
+    vi.mocked(listRepoWorktreeGraph).mockReset()
     // The #16520 outage itself: `listWorktrees` softens every Git failure to `[]`, so the rebuild
     // reports success with the recovered row missing and the probe is the only remaining evidence.
-    vi.mocked(listRepoWorktrees).mockResolvedValue([])
+    vi.mocked(listRepoWorktreeGraph).mockResolvedValue([])
     statMock.mockReset()
     statMock.mockResolvedValue({})
   })
diff --git a/src/main/ipc/filesystem-auth.test.ts b/src/main/ipc/filesystem-auth.test.ts
index 41c2c44a634..fa82b7a652c 100644
--- a/src/main/ipc/filesystem-auth.test.ts
+++ b/src/main/ipc/filesystem-auth.test.ts
@@ -5,7 +5,7 @@ import { join, resolve } from 'node:path'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import type { Store } from '../persistence'
 import type * as RepoWorktrees from '../repo-worktrees'
-import { listRepoWorktrees } from '../repo-worktrees'
+import { listRepoWorktreeGraph } from '../repo-worktrees'
 import type { FolderWorkspace } from '../../shared/folder-workspace-types'
 import type { ProjectGroup } from '../../shared/project-group-types'
 import type { Repo } from '../../shared/repo-types'
@@ -29,7 +29,7 @@ vi.mock('../repo-worktrees', async () => {
   const actual = await vi.importActual<typeof RepoWorktrees>('../repo-worktrees')
   return {
     ...actual,
-    listRepoWorktrees: vi.fn()
+    listRepoWorktreeGraph: vi.fn()
   }
 })
 
@@ -98,7 +98,7 @@ describe('filesystem auth worktree roots', () => {
   beforeEach(() => {
     invalidateAuthorizedRootsCache()
     __resetCreatedWorktreeRootsForTests()
-    vi.mocked(listRepoWorktrees).mockReset()
+    vi.mocked(listRepoWorktreeGraph).mockReset()
   })
 
   it('rebuilds the authorized roots cache for large worktree lists', async () => {
@@ -112,7 +112,7 @@ describe('filesystem auth worktree roots', () => {
         isMainWorktree: false
       })
     )
-    vi.mocked(listRepoWorktrees).mockResolvedValue(worktrees)
+    vi.mocked(listRepoWorktreeGraph).mockResolvedValue(worktrees)
     const store = makeStore()
 
     await rebuildAuthorizedRootsCache(store)
@@ -121,7 +121,7 @@ describe('filesystem auth worktree roots', () => {
     await expect(resolveRegisteredWorktreePath(lastWorktreePath, store)).resolves.toBe(
       resolve(lastWorktreePath)
     )
-    expect(listRepoWorktrees).toHaveBeenCalledTimes(1)
+    expect(listRepoWorktreeGraph).toHaveBeenCalledTimes(1)
   })
 
   it("keeps a repo's roots when its listing fails mid-rebuild", async () => {
@@ -129,7 +129,7 @@ describe('filesystem auth worktree roots', () => {
     // a worktree a create just recovered without a listing (#16520).
     const store = makeStore()
     registerCreatedWorktreeRoot(store, repo.id, '/linked/recovered')
-    vi.mocked(listRepoWorktrees).mockRejectedValue(new Error('git worktree list failed.'))
+    vi.mocked(listRepoWorktreeGraph).mockRejectedValue(new Error('git worktree list failed.'))
 
     await rebuildAuthorizedRootsCache(store)
 
@@ -146,7 +146,7 @@ describe('filesystem auth worktree roots', () => {
     await mkdir(recovered)
     const store = makeStore()
     registerCreatedWorktreeRoot(store, repo.id, recovered)
-    vi.mocked(listRepoWorktrees).mockResolvedValue([])
+    vi.mocked(listRepoWorktreeGraph).mockResolvedValue([])
 
     await rebuildAuthorizedRootsCache(store)
 
@@ -160,7 +160,7 @@ describe('filesystem auth worktree roots', () => {
     await mkdir(recovered)
     const store = makeStore()
     // Register mid-listing: the rebuild's own result was computed before this worktree existed.
-    vi.mocked(listRepoWorktrees).mockImplementation(async () => {
+    vi.mocked(listRepoWorktreeGraph).mockImplementation(async () => {
       registerCreatedWorktreeRoot(store, repo.id, recovered)
       return []
     })
@@ -174,7 +174,7 @@ describe('filesystem auth worktree roots', () => {
   it('retires a recovered root once the listing can see it again', async () => {
     const store = makeStore()
     registerCreatedWorktreeRoot(store, repo.id, '/linked/feature')
-    vi.mocked(listRepoWorktrees).mockResolvedValue([
+    vi.mocked(listRepoWorktreeGraph).mockResolvedValue([
       {
         path: '/linked/feature',
         head: '',
@@ -189,7 +189,7 @@ describe('filesystem auth worktree roots', () => {
     await expect(resolveRegisteredWorktreePath('/linked/feature', store)).resolves.toBe(
       resolve('/linked/feature')
     )
-    vi.mocked(listRepoWorktrees).mockResolvedValue([])
+    vi.mocked(listRepoWorktreeGraph).mockResolvedValue([])
     await rebuildAuthorizedRootsCache(store)
 
     await expect(resolveRegisteredWorktreePath('/linked/feature', store)).rejects.toThrow(
@@ -205,7 +205,7 @@ describe('filesystem auth worktree roots', () => {
     }))
     let active = 0
     let maxActive = 0
-    vi.mocked(listRepoWorktrees).mockImplementation(async () => {
+    vi.mocked(listRepoWorktreeGraph).mockImplementation(async () => {
       active += 1
       maxActive = Math.max(maxActive, active)
       await new Promise((resolve) => setTimeout(resolve, 1))
@@ -215,7 +215,7 @@ describe('filesystem auth worktree roots', () => {
 
     await rebuildAuthorizedRootsCache(makeStore(repos))
 
-    expect(listRepoWorktrees).toHaveBeenCalledTimes(repos.length)
+    expect(listRepoWorktreeGraph).toHaveBeenCalledTimes(repos.length)
     expect(maxActive).toBeLessThanOrEqual(8)
   })
 })
@@ -392,7 +392,7 @@ describe('filesystem-auth path containment', () => {
     vi.resetModules()
     vi.doMock('../repo-worktrees', () => ({
       isRepoRoot: vi.fn(),
-      listRepoWorktrees: vi.fn()
+      listRepoWorktreeGraph: vi.fn()
     }))
     vi.doMock('path', async () => {
       const path = await vi.importActual<typeof NodePath>('node:path')
diff --git a/src/main/ipc/filesystem-test-harness.ts b/src/main/ipc/filesystem-test-harness.ts
index 402409defa3..47efa88d6cd 100644
--- a/src/main/ipc/filesystem-test-harness.ts
+++ b/src/main/ipc/filesystem-test-harness.ts
@@ -107,6 +107,7 @@ export const gitStatusModuleMock = {
 export const gitIgnoredPathsMock = { checkIgnoredPaths: checkIgnoredPathsMock }
 
 export const gitWorktreeMock = {
+  listWorktreeGraph: listWorktreesMock,
   listWorktrees: listWorktreesMock,
   listWorktreesStrict: listWorktreesMock
 }
diff --git a/src/main/ipc/filesystem/filesystem-source-control-ai-targets.ts b/src/main/ipc/filesystem/filesystem-source-control-ai-targets.ts
index 62b86e7361a..2f9e5e92c09 100644
--- a/src/main/ipc/filesystem/filesystem-source-control-ai-targets.ts
+++ b/src/main/ipc/filesystem/filesystem-source-control-ai-targets.ts
@@ -5,7 +5,7 @@ import type { CommitMessageAgentRuntimeTarget } from '../../text-generation/comm
 import type { CommitMessageGenerationTarget } from '../../text-generation/commit-message-text-generation'
 import { resolve } from 'node:path'
 import { getSshGitProvider } from '../../providers/ssh-git-dispatch'
-import { listRepoWorktrees } from '../../repo-worktrees'
+import { listRepoWorktreeGraph } from '../../repo-worktrees'
 import { resolveAuthorizedPath } from '../filesystem-auth'
 import { resolveRegisteredWorktreePath } from '../registered-worktree-roots-cache'
 import { splitWorktreeId } from '../../../shared/worktree/id'
@@ -77,7 +77,7 @@ async function localRepoOwnsWorktree(
     return true
   }
   try {
-    const worktrees = await listRepoWorktrees(repo)
+    const worktrees = await listRepoWorktreeGraph(repo)
     return worktrees.some((worktree) => candidatePaths.has(comparableLocalPath(worktree.path)))
   } catch {
     return false
diff --git a/src/main/ipc/hosted-review.test.ts b/src/main/ipc/hosted-review.test.ts
index 7cad33211d6..3f273490d7b 100644
--- a/src/main/ipc/hosted-review.test.ts
+++ b/src/main/ipc/hosted-review.test.ts
@@ -17,7 +17,7 @@ const {
   getHostedReviewCreationEligibilityMock,
   getHostedReviewForBranchMock,
   resolveRegisteredWorktreePathMock,
-  listRepoWorktreesMock
+  listRepoWorktreeGraphMock
 } = vi.hoisted(() => ({
   handleMock: vi.fn(),
   createHostedReviewMock: vi.fn(),
@@ -25,7 +25,7 @@ const {
   getHostedReviewCreationEligibilityMock: vi.fn(),
   getHostedReviewForBranchMock: vi.fn(),
   resolveRegisteredWorktreePathMock: vi.fn(),
-  listRepoWorktreesMock: vi.fn()
+  listRepoWorktreeGraphMock: vi.fn()
 }))
 
 vi.mock('electron', () => ({
@@ -52,7 +52,7 @@ vi.mock('./registered-worktree-roots-cache', () => ({
 }))
 
 vi.mock('../repo-worktrees', () => ({
-  listRepoWorktrees: listRepoWorktreesMock
+  listRepoWorktreeGraph: listRepoWorktreeGraphMock
 }))
 
 import { registerHostedReviewHandlers } from './hosted-review'
@@ -97,7 +97,7 @@ describe('registerHostedReviewHandlers', () => {
     getHostedReviewCreationEligibilityMock.mockReset()
     getHostedReviewForBranchMock.mockReset()
     resolveRegisteredWorktreePathMock.mockReset()
-    listRepoWorktreesMock.mockReset()
+    listRepoWorktreeGraphMock.mockReset()
     store.getRepo.mockReset()
     store.getRepos.mockReset()
     store.getProjects.mockReset()
@@ -114,7 +114,7 @@ describe('registerHostedReviewHandlers', () => {
     store.getRepos.mockReturnValue([repo])
     store.getProjects.mockReturnValue([])
     store.getSettings.mockReturnValue({ localWindowsRuntimeDefault: { kind: 'windows-host' } })
-    listRepoWorktreesMock.mockResolvedValue([{ path: worktreePath }])
+    listRepoWorktreeGraphMock.mockResolvedValue([{ path: worktreePath }])
   })
 
   it('routes local WSL project review creation through main-process runtime options', async () => {
@@ -143,7 +143,7 @@ describe('registerHostedReviewHandlers', () => {
     ])
     const resolvedWorktreePath = resolve('/workspace/feature')
     resolveRegisteredWorktreePathMock.mockResolvedValue(resolvedWorktreePath)
-    listRepoWorktreesMock.mockResolvedValue([{ path: resolvedWorktreePath }])
+    listRepoWorktreeGraphMock.mockResolvedValue([{ path: resolvedWorktreePath }])
     createHostedReviewMock.mockResolvedValueOnce({
       ok: true,
       number: 42,
@@ -162,7 +162,7 @@ describe('registerHostedReviewHandlers', () => {
       title: 'Feature PR'
     })
 
-    expect(listRepoWorktreesMock).toHaveBeenCalledWith(localRepo, { wslDistro: 'Ubuntu' })
+    expect(listRepoWorktreeGraphMock).toHaveBeenCalledWith(localRepo, { wslDistro: 'Ubuntu' })
     expect(createHostedReviewMock).toHaveBeenCalledWith(
       resolvedWorktreePath,
       expect.objectContaining({
@@ -193,7 +193,7 @@ describe('registerHostedReviewHandlers', () => {
     store.getRepos.mockReturnValue([localRepo])
     const resolvedWorktreePath = resolve('/workspace/feature')
     resolveRegisteredWorktreePathMock.mockResolvedValue(resolvedWorktreePath)
-    listRepoWorktreesMock.mockResolvedValue([{ path: resolvedWorktreePath }])
+    listRepoWorktreeGraphMock.mockResolvedValue([{ path: resolvedWorktreePath }])
     createHostedReviewMock.mockResolvedValueOnce({ ok: true, number: 42, url: 'https://x/1' })
 
     registerHostedReviewHandlers(store as never, stats as never)
diff --git a/src/main/ipc/hosted-review.ts b/src/main/ipc/hosted-review.ts
index c431459f4f7..f64aeb8aa4d 100644
--- a/src/main/ipc/hosted-review.ts
+++ b/src/main/ipc/hosted-review.ts
@@ -16,7 +16,7 @@ import {
 import { createStackedHostedReview } from '../source-control/stacked-hosted-review-creation'
 import { getHostedReviewForBranch } from '../source-control/hosted-review'
 import { resolveRegisteredWorktreePath } from './registered-worktree-roots-cache'
-import { listRepoWorktrees } from '../repo-worktrees'
+import { listRepoWorktreeGraph } from '../repo-worktrees'
 import { getLocalProjectWorktreeGitOptions } from '../project-runtime-git-options'
 import { getWorktreeSharedLinkPaths } from '../git/worktree-shared-directories'
 import { getRepoExecutionHostId } from '../../shared/execution-host'
@@ -68,7 +68,7 @@ async function resolveHostedReviewWorktreePath(
   }
   if (repo.connectionId) {
     const remoteWorktreePath = normalizeRemoteHostedReviewPath(worktreePath)
-    const repoWorktrees = await listRepoWorktrees(repo)
+    const repoWorktrees = await listRepoWorktreeGraph(repo)
     if (
       !repoWorktrees.some(
         (worktree) => normalizeRemoteHostedReviewPath(worktree.path) === remoteWorktreePath
@@ -82,8 +82,8 @@ async function resolveHostedReviewWorktreePath(
   const localGitOptions = getLocalProjectWorktreeGitOptions(store, repo)
   const repoWorktrees =
     Object.keys(localGitOptions).length > 0
-      ? await listRepoWorktrees(repo, localGitOptions)
-      : await listRepoWorktrees(repo)
+      ? await listRepoWorktreeGraph(repo, localGitOptions)
+      : await listRepoWorktreeGraph(repo)
   if (!repoWorktrees.some((worktree) => resolve(worktree.path) === resolvedWorktreePath)) {
     throw new Error('Access denied: worktree does not belong to repository')
   }
diff --git a/src/main/ipc/registered-worktree-roots-cache.ts b/src/main/ipc/registered-worktree-roots-cache.ts
index 9e1d20733df..ad8c40535cf 100644
--- a/src/main/ipc/registered-worktree-roots-cache.ts
+++ b/src/main/ipc/registered-worktree-roots-cache.ts
@@ -3,7 +3,7 @@ import { resolve } from 'node:path'
 import { withTimeout } from '../../shared/promise-timeout-fallback'
 import { getErrorCode } from '../git/worktree-operation-options'
 import type { Store } from '../persistence'
-import { isRepoRoot, listRepoWorktrees } from '../repo-worktrees'
+import { isRepoRoot, listRepoWorktreeGraph } from '../repo-worktrees'
 import { getLocalRepos } from './filesystem-allowed-roots'
 import { isDescendantOrEqual, normalizeExistingPath } from './filesystem-path-containment'
 
@@ -54,7 +54,7 @@ export async function rebuildAuthorizedRootsCache(store: Store): Promise<void> {
       try {
         roots.push(resolve(repo.path))
 
-        for (const worktree of await listRepoWorktrees(repo)) {
+        for (const worktree of await listRepoWorktreeGraph(repo)) {
           roots.push(resolve(worktree.path))
         }
       } catch (error) {
diff --git a/src/main/repo-worktrees.test.ts b/src/main/repo-worktrees.test.ts
index d0c0ea5c617..d1c3935c1e1 100644
--- a/src/main/repo-worktrees.test.ts
+++ b/src/main/repo-worktrees.test.ts
@@ -1,11 +1,13 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
-const { listWorktreesMock, listWorktreesStrictMock } = vi.hoisted(() => ({
+const { listWorktreeGraphMock, listWorktreesMock, listWorktreesStrictMock } = vi.hoisted(() => ({
+  listWorktreeGraphMock: vi.fn(),
   listWorktreesMock: vi.fn(),
   listWorktreesStrictMock: vi.fn()
 }))
 
 vi.mock('./git/worktree', () => ({
+  listWorktreeGraph: listWorktreeGraphMock,
   listWorktrees: listWorktreesMock,
   listWorktreesStrict: listWorktreesStrictMock
 }))
@@ -14,11 +16,13 @@ import {
   createFolderWorktree,
   isRepoRoot,
   listLocalRepoWorktreesStrict,
+  listRepoWorktreeGraph,
   listRepoWorktrees
 } from './repo-worktrees'
 
 describe('repo-worktrees', () => {
   beforeEach(() => {
+    listWorktreeGraphMock.mockReset()
     listWorktreesMock.mockReset()
     listWorktreesStrictMock.mockReset()
   })
@@ -109,6 +113,49 @@ describe('repo-worktrees', () => {
     expect(result).toHaveLength(1)
   })
 
+  // Path-only callers must reach the probe-free listing, never the annotated one.
+  it('delegates to the graph listing without sparse annotation', async () => {
+    listWorktreeGraphMock.mockResolvedValue([
+      { path: '/workspace/repo', head: 'abc', branch: '', isBare: false, isMainWorktree: true }
+    ])
+
+    const result = await listRepoWorktreeGraph({
+      id: 'repo-1',
+      path: '/workspace/repo',
+      displayName: 'repo',
+      badgeColor: '#000',
+      addedAt: 0,
+      kind: 'git'
+    })
+
+    expect(listWorktreeGraphMock).toHaveBeenCalledWith('/workspace/repo')
+    expect(listWorktreesMock).not.toHaveBeenCalled()
+    expect(result).toHaveLength(1)
+  })
+
+  it('returns the synthetic folder worktree from the graph listing', async () => {
+    const result = await listRepoWorktreeGraph({
+      id: 'repo-1',
+      path: '/workspace/folder',
+      displayName: 'folder',
+      badgeColor: '#000',
+      addedAt: 0,
+      kind: 'folder'
+    })
+
+    expect(listWorktreeGraphMock).not.toHaveBeenCalled()
+    expect(result).toEqual([
+      createFolderWorktree({
+        id: 'repo-1',
+        path: '/workspace/folder',
+        displayName: 'folder',
+        badgeColor: '#000',
+        addedAt: 0,
+        kind: 'folder'
+      })
+    ])
+  })
+
   it('delegates strict local listing with the signal and WSL options', async () => {
     listWorktreesStrictMock.mockResolvedValue([
       { path: '/workspace/repo', head: 'abc', branch: '', isBare: false, isMainWorktree: true }
diff --git a/src/main/repo-worktrees.ts b/src/main/repo-worktrees.ts
index 14751c17861..c5e756b9310 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, listWorktreesStrict } from './git/worktree'
+import { listWorktreeGraph, listWorktrees, listWorktreesStrict } from './git/worktree'
 import { isFolderRepo } from '../shared/repo-kind'
 import { getSshGitProvider } from './providers/ssh-git-dispatch'
 import { areWorktreePathsEqual } from './ipc/worktree-logic'
@@ -52,6 +52,29 @@ export async function listRepoWorktrees(
     : await listWorktrees(repo.path)
 }
 
+/**
+ * Worktree rows for callers that read only `worktree.path`.
+ *
+ * Skips the sparse-checkout probe behind the badge, which those callers discard. On a WSL repo the
+ * probe is a 9p stat plus a config read per worktree, re-paid cold after every worktree
+ * create/remove because that invalidates both the authorized-roots cache and the sparse cache.
+ */
+export async function listRepoWorktreeGraph(
+  repo: Repo,
+  options?: LocalRepoWorktreeListOptions
+): Promise<GitWorktreeInfo[]> {
+  if (isFolderRepo(repo)) {
+    return [createFolderWorktree(repo)]
+  }
+  if (repo.connectionId) {
+    const provider = getSshGitProvider(repo.connectionId)
+    return provider ? await provider.listWorktrees(repo.path) : []
+  }
+  return hasLocalRepoWorktreeListOptions(options)
+    ? await listWorktreeGraph(repo.path, options)
+    : await listWorktreeGraph(repo.path)
+}
+
 export async function listLocalRepoWorktreesStrict(
   repo: Repo,
   options?: LocalRepoWorktreeListOptions

From 7a6935785630737ef649a372cef0af09fc0d4c19 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Tue, 1 Sep 2026 20:25:42 -0700
Subject: [PATCH 31/32] fix(worktree): widen git-common watch on event-batch
 overflow (#17916)

---
 .../worktree-base-directory-marker-poller.ts  | 289 ++++++++++++++++++
 .../ipc/worktree-base-directory-poller.ts     | 287 +----------------
 .../worktree-base-directory-watch-events.ts   |  90 ++++++
 .../worktree-base-directory-watcher.test.ts   |  40 +++
 .../ipc/worktree-base-directory-watcher.ts    |  88 +-----
 .../ipc/worktree-git-common-narrow-watch.ts   |  24 +-
 .../ipc/worktree-git-common-watch.test.ts     |  39 +++
 src/main/ipc/worktree-git-common-watch.ts     |   6 +-
 8 files changed, 508 insertions(+), 355 deletions(-)
 create mode 100644 src/main/ipc/worktree-base-directory-marker-poller.ts
 create mode 100644 src/main/ipc/worktree-base-directory-watch-events.ts

diff --git a/src/main/ipc/worktree-base-directory-marker-poller.ts b/src/main/ipc/worktree-base-directory-marker-poller.ts
new file mode 100644
index 00000000000..dba1c4df03c
--- /dev/null
+++ b/src/main/ipc/worktree-base-directory-marker-poller.ts
@@ -0,0 +1,289 @@
+import { readdir, stat } from 'node:fs/promises'
+import type { Dirent } from 'node:fs'
+import { join } from 'node:path'
+import { normalizeRuntimePathForComparison } from '../../shared/cross-platform-path'
+import { forEachWithConcurrency } from '../../shared/map-with-concurrency'
+import type {
+  WorktreeBaseRepoWatchConfig,
+  WorktreeBaseWatchTarget
+} from './worktree-base-directory-event-filter'
+import type {
+  WorktreeBasePollerOptions,
+  WorktreeBasePollEvent,
+  WorktreeBaseSubscription,
+  WorktreePollerWindowVisibility
+} from './worktree-base-directory-poller'
+
+// Why: the mtime gate is an optimization, not a correctness boundary — some
+// filesystems have coarse dir timestamps, and pending `.git` markers expire.
+// A periodic ungated scan guarantees eventual convergence.
+export const WORKTREE_BASE_BACKSTOP_TICKS = 15
+
+// Why: a `.git` completion marker lands within moments of its worktree dir
+// (git writes it before populating the checkout). Dirs that never get one are
+// not worktrees; stop re-statting them after this many ticks and let the
+// backstop scan cover the pathological case.
+const PENDING_MARKER_MAX_TICKS = 300
+
+// Why: matches the git-common poller's fan-out bound (#17828) — bounded
+// concurrency turns hundreds of serial round trips into a handful of batches
+// without dumping every candidate onto libuv's 4-thread pool at once.
+const MARKER_PROBE_CONCURRENCY = 8
+
+function statSignature(s: { mtimeMs: number; ctimeMs: number; ino: number }): string {
+  return `${s.mtimeMs}:${s.ctimeMs}:${s.ino}`
+}
+
+async function dirSignature(path: string): Promise<string> {
+  try {
+    return statSignature(await stat(path))
+  } catch {
+    return 'missing'
+  }
+}
+
+async function hasGitMarker(dir: string): Promise<boolean> {
+  try {
+    await stat(join(dir, '.git'))
+    return true
+  } catch {
+    return false
+  }
+}
+
+type BaseSnapshot = {
+  // worktree-candidate dir → whether its `.git` completion marker exists
+  markers: Map<string, boolean>
+  // dirs whose listing determines the candidate set: the root plus any
+  // nested repo containers. Their stat signatures gate the next full scan.
+  gateDirs: string[]
+  // index-aligned with gateDirs, each sampled *before* that dir's listing
+  gateSignatures: string[]
+}
+
+async function readdirSafe(path: string): Promise<Dirent[]> {
+  try {
+    return await readdir(path, { withFileTypes: true })
+  } catch {
+    return []
+  }
+}
+
+// Depth-1 worktree dirs (flat layout), plus depth-2 dirs under each nested
+// repo's container, mirroring what worktree-base-directory-event-filter
+// matches: `<wt>/.git` completion markers and `<wt>` deletions.
+async function snapshotBase(
+  rootPath: string,
+  repos: ReadonlyMap<string, WorktreeBaseRepoWatchConfig>
+): Promise<BaseSnapshot> {
+  const markers = new Map<string, boolean>()
+  const gateDirs = [rootPath]
+  // Why: sampling the signature before the listing makes a write that races the
+  // scan look stale next tick (one redundant rescan) instead of invisible until
+  // the backstop, which is up to 15 ticks of missed creates/deletes.
+  const gateSignatures = [await dirSignature(rootPath)]
+  const configs = [...repos.values()]
+  const includeFlat = configs.some((config) => !config.nestWorkspaces)
+  const nestedRepoNames = new Set(
+    configs
+      .filter((config) => config.nestWorkspaces)
+      .map((config) => normalizeRuntimePathForComparison(config.repoName))
+  )
+
+  // Root vanished or unreadable: readdirSafe yields [], producing the same
+  // empty markers/candidates result as the old watcher's error path.
+  const rootEntries = await readdirSafe(rootPath)
+
+  const candidates: string[] = []
+  for (const entry of rootEntries) {
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) {
+      continue
+    }
+    const entryPath = join(rootPath, entry.name)
+    if (includeFlat) {
+      candidates.push(entryPath)
+    }
+    if (nestedRepoNames.has(normalizeRuntimePathForComparison(entry.name))) {
+      gateDirs.push(entryPath)
+      gateSignatures.push(await dirSignature(entryPath))
+      const subEntries = await readdirSafe(entryPath)
+      for (const sub of subEntries) {
+        if (sub.isDirectory() || sub.isSymbolicLink()) {
+          candidates.push(join(entryPath, sub.name))
+        }
+      }
+    }
+  }
+
+  await forEachWithConcurrency(candidates, MARKER_PROBE_CONCURRENCY, async (dir) => {
+    markers.set(dir, await hasGitMarker(dir))
+  })
+  return { markers, gateDirs, gateSignatures }
+}
+
+function diffBase(prev: BaseSnapshot, next: BaseSnapshot): WorktreeBasePollEvent[] {
+  const events: WorktreeBasePollEvent[] = []
+  for (const [dir, marker] of next.markers) {
+    if (marker && prev.markers.get(dir) !== true) {
+      events.push({ type: 'create', path: join(dir, '.git') })
+    }
+  }
+  for (const dir of prev.markers.keys()) {
+    if (!next.markers.has(dir)) {
+      events.push({ type: 'delete', path: dir })
+    }
+  }
+  return events
+}
+
+export async function startBasePoller(
+  target: WorktreeBaseWatchTarget,
+  getRepos: () => ReadonlyMap<string, WorktreeBaseRepoWatchConfig>,
+  onEvents: (events: WorktreeBasePollEvent[]) => void,
+  pollIntervalMs: number,
+  visibility: WorktreePollerWindowVisibility,
+  options: WorktreeBasePollerOptions
+): Promise<WorktreeBaseSubscription> {
+  let disposed = false
+  let ticking = false
+  let tickCount = 0
+  let snapshot = await snapshotBase(target.path, getRepos())
+  let timer: ReturnType<typeof setTimeout> | null = null
+  let parkedWhileHidden = false
+  const pendingMarkerMaxTicks = options.pendingMarkerMaxTicks ?? PENDING_MARKER_MAX_TICKS
+  // dir → first probe tick; null means backstop scans only
+  const markerProbeStartedAt = new Map<string, number | null>()
+  for (const [dir, marker] of snapshot.markers) {
+    if (!marker) {
+      markerProbeStartedAt.set(dir, 0)
+    }
+  }
+
+  const fullScan = async (): Promise<void> => {
+    options.onFullScan?.()
+    const next = await snapshotBase(target.path, getRepos())
+    await options.onSnapshotTaken?.(tickCount)
+    if (disposed) {
+      return
+    }
+    const events = diffBase(snapshot, next)
+    for (const [dir, marker] of next.markers) {
+      if (marker) {
+        markerProbeStartedAt.delete(dir)
+      } else if (!markerProbeStartedAt.has(dir)) {
+        markerProbeStartedAt.set(dir, tickCount)
+      }
+    }
+    for (const dir of markerProbeStartedAt.keys()) {
+      if (!next.markers.has(dir)) {
+        markerProbeStartedAt.delete(dir)
+      }
+    }
+    snapshot = next
+    if (events.length > 0) {
+      onEvents(events)
+    }
+  }
+
+  const checkPendingMarkers = async (): Promise<void> => {
+    const events: WorktreeBasePollEvent[] = []
+    for (const [dir, firstSeenTick] of markerProbeStartedAt) {
+      if (firstSeenTick === null) {
+        continue
+      }
+      if (tickCount - firstSeenTick > pendingMarkerMaxTicks) {
+        markerProbeStartedAt.set(dir, null)
+        continue
+      }
+      options.onPendingMarkerProbe?.(join(dir, '.git'))
+      if (await hasGitMarker(dir)) {
+        markerProbeStartedAt.delete(dir)
+        snapshot.markers.set(dir, true)
+        events.push({ type: 'create', path: join(dir, '.git') })
+      }
+    }
+    if (!disposed && events.length > 0) {
+      onEvents(events)
+    }
+  }
+
+  const poll = async (forceFullScan = false): Promise<void> => {
+    tickCount++
+    if (forceFullScan || tickCount % WORKTREE_BASE_BACKSTOP_TICKS === 0) {
+      await fullScan()
+      return
+    }
+    // Idle fast path: when the dirs whose listings define the candidate set
+    // are untouched, skip the readdir + per-candidate stat fan-out entirely.
+    const signatures = await Promise.all(snapshot.gateDirs.map(dirSignature))
+    const gateChanged =
+      signatures.length !== snapshot.gateSignatures.length ||
+      signatures.some((sig, index) => sig !== snapshot.gateSignatures[index])
+    if (gateChanged) {
+      await fullScan()
+      return
+    }
+    if (markerProbeStartedAt.size > 0) {
+      await checkPendingMarkers()
+    }
+  }
+
+  const tick = async (forceFullScan = false): Promise<void> => {
+    timer = null
+    if (disposed) {
+      return
+    }
+    if (!visibility.isWindowVisible()) {
+      parkedWhileHidden = true
+      return
+    }
+    if (ticking) {
+      return
+    }
+    ticking = true
+    // Why: measure from tick start so the cadence is start-to-start (like the old setInterval), not
+    // gap-after-completion — otherwise each visible refresh lands a full scan-duration late every tick.
+    const startedAt = Date.now()
+    try {
+      await poll(forceFullScan)
+    } catch {
+      // Transient fs error: keep the previous snapshot and retry next tick.
+    } finally {
+      ticking = false
+    }
+    if (!disposed) {
+      // Why: clamp to [0, pollIntervalMs]. Date.now() is not monotonic — a backward wall-clock jump (NTP) would
+      // otherwise make elapsed negative and push the next tick out by the adjustment (suppressing refreshes for
+      // minutes); the upper clamp caps the wait at one interval, the lower clamp keeps a long scan from going negative.
+      const nextDelay = Math.max(
+        0,
+        Math.min(pollIntervalMs, pollIntervalMs - (Date.now() - startedAt))
+      )
+      timer = setTimeout(() => void tick(), nextDelay)
+      timer.unref?.()
+    }
+  }
+
+  const unsubscribeVisibility = visibility.onWindowBecameVisible(() => {
+    if (disposed || !parkedWhileHidden) {
+      return
+    }
+    parkedWhileHidden = false
+    // Why: the ordinary dir-signature gate can miss same-granule changes made
+    // while hidden; resume must diff a fresh full snapshot against the baseline.
+    void tick(true)
+  })
+
+  timer = setTimeout(() => void tick(), pollIntervalMs)
+  timer.unref?.()
+
+  return {
+    unsubscribe: async () => {
+      disposed = true
+      if (timer) {
+        clearTimeout(timer)
+      }
+      unsubscribeVisibility()
+    }
+  }
+}
diff --git a/src/main/ipc/worktree-base-directory-poller.ts b/src/main/ipc/worktree-base-directory-poller.ts
index 201d9782fba..39c5b5f48c0 100644
--- a/src/main/ipc/worktree-base-directory-poller.ts
+++ b/src/main/ipc/worktree-base-directory-poller.ts
@@ -1,15 +1,13 @@
-import { readdir, stat } from 'node:fs/promises'
-import type { Dirent } from 'node:fs'
-import { join } from 'node:path'
-import { normalizeRuntimePathForComparison } from '../../shared/cross-platform-path'
-import { forEachWithConcurrency } from '../../shared/map-with-concurrency'
 import { isMainWindowVisible, onMainWindowBecameVisible } from '../window/main-window-visibility'
 import type {
   WorktreeBaseRepoWatchConfig,
   WorktreeBaseWatchTarget
 } from './worktree-base-directory-event-filter'
+import { startBasePoller } from './worktree-base-directory-marker-poller'
 import { startGitCommonWatch } from './worktree-git-common-watch'
 
+export { WORKTREE_BASE_BACKSTOP_TICKS } from './worktree-base-directory-marker-poller'
+
 export type WorktreeBasePollEvent = { type: 'create' | 'update' | 'delete'; path: string }
 
 export type WorktreeBaseSubscription = { unsubscribe: () => Promise<void> }
@@ -63,6 +61,8 @@ export type WorktreeBasePollerOptions = {
   visibility?: WorktreePollerWindowVisibility
   getGitStatusRefPaths?: () => readonly string[]
   onWatchError?: (error: Error) => void
+  /** Called when the watcher child dropped an event batch (git-common narrow watch only). */
+  onOverflow?: () => void
   /** Test hook: called whenever a full snapshot scan runs (vs. a gated skip). */
   onFullScan?: () => void
   /** Test hook: called before a pending `.git` marker stat. */
@@ -83,280 +83,6 @@ export type WorktreeBasePollerOptions = {
 // Orca's own worktree operations notify the renderer directly.
 export const WORKTREE_BASE_POLL_INTERVAL_MS = 2_000
 
-// Why: the mtime gate is an optimization, not a correctness boundary — some
-// filesystems have coarse dir timestamps, and pending `.git` markers expire.
-// A periodic ungated scan guarantees eventual convergence.
-export const WORKTREE_BASE_BACKSTOP_TICKS = 15
-
-// Why: a `.git` completion marker lands within moments of its worktree dir
-// (git writes it before populating the checkout). Dirs that never get one are
-// not worktrees; stop re-statting them after this many ticks and let the
-// backstop scan cover the pathological case.
-const PENDING_MARKER_MAX_TICKS = 300
-
-// Why: matches the git-common poller's fan-out bound (#17828) — bounded
-// concurrency turns hundreds of serial round trips into a handful of batches
-// without dumping every candidate onto libuv's 4-thread pool at once.
-const MARKER_PROBE_CONCURRENCY = 8
-
-function statSignature(s: { mtimeMs: number; ctimeMs: number; ino: number }): string {
-  return `${s.mtimeMs}:${s.ctimeMs}:${s.ino}`
-}
-
-async function dirSignature(path: string): Promise<string> {
-  try {
-    return statSignature(await stat(path))
-  } catch {
-    return 'missing'
-  }
-}
-
-async function hasGitMarker(dir: string): Promise<boolean> {
-  try {
-    await stat(join(dir, '.git'))
-    return true
-  } catch {
-    return false
-  }
-}
-
-type BaseSnapshot = {
-  // worktree-candidate dir → whether its `.git` completion marker exists
-  markers: Map<string, boolean>
-  // dirs whose listing determines the candidate set: the root plus any
-  // nested repo containers. Their stat signatures gate the next full scan.
-  gateDirs: string[]
-  // index-aligned with gateDirs, each sampled *before* that dir's listing
-  gateSignatures: string[]
-}
-
-async function readdirSafe(path: string): Promise<Dirent[]> {
-  try {
-    return await readdir(path, { withFileTypes: true })
-  } catch {
-    return []
-  }
-}
-
-// Depth-1 worktree dirs (flat layout), plus depth-2 dirs under each nested
-// repo's container, mirroring what worktree-base-directory-event-filter
-// matches: `<wt>/.git` completion markers and `<wt>` deletions.
-async function snapshotBase(
-  rootPath: string,
-  repos: ReadonlyMap<string, WorktreeBaseRepoWatchConfig>
-): Promise<BaseSnapshot> {
-  const markers = new Map<string, boolean>()
-  const gateDirs = [rootPath]
-  // Why: sampling the signature before the listing makes a write that races the
-  // scan look stale next tick (one redundant rescan) instead of invisible until
-  // the backstop, which is up to 15 ticks of missed creates/deletes.
-  const gateSignatures = [await dirSignature(rootPath)]
-  const configs = [...repos.values()]
-  const includeFlat = configs.some((config) => !config.nestWorkspaces)
-  const nestedRepoNames = new Set(
-    configs
-      .filter((config) => config.nestWorkspaces)
-      .map((config) => normalizeRuntimePathForComparison(config.repoName))
-  )
-
-  // Root vanished or unreadable: readdirSafe yields [], producing the same
-  // empty markers/candidates result as the old watcher's error path.
-  const rootEntries = await readdirSafe(rootPath)
-
-  const candidates: string[] = []
-  for (const entry of rootEntries) {
-    if (!entry.isDirectory() && !entry.isSymbolicLink()) {
-      continue
-    }
-    const entryPath = join(rootPath, entry.name)
-    if (includeFlat) {
-      candidates.push(entryPath)
-    }
-    if (nestedRepoNames.has(normalizeRuntimePathForComparison(entry.name))) {
-      gateDirs.push(entryPath)
-      gateSignatures.push(await dirSignature(entryPath))
-      const subEntries = await readdirSafe(entryPath)
-      for (const sub of subEntries) {
-        if (sub.isDirectory() || sub.isSymbolicLink()) {
-          candidates.push(join(entryPath, sub.name))
-        }
-      }
-    }
-  }
-
-  await forEachWithConcurrency(candidates, MARKER_PROBE_CONCURRENCY, async (dir) => {
-    markers.set(dir, await hasGitMarker(dir))
-  })
-  return { markers, gateDirs, gateSignatures }
-}
-
-function diffBase(prev: BaseSnapshot, next: BaseSnapshot): WorktreeBasePollEvent[] {
-  const events: WorktreeBasePollEvent[] = []
-  for (const [dir, marker] of next.markers) {
-    if (marker && prev.markers.get(dir) !== true) {
-      events.push({ type: 'create', path: join(dir, '.git') })
-    }
-  }
-  for (const dir of prev.markers.keys()) {
-    if (!next.markers.has(dir)) {
-      events.push({ type: 'delete', path: dir })
-    }
-  }
-  return events
-}
-
-async function startBasePoller(
-  target: WorktreeBaseWatchTarget,
-  getRepos: () => ReadonlyMap<string, WorktreeBaseRepoWatchConfig>,
-  onEvents: (events: WorktreeBasePollEvent[]) => void,
-  pollIntervalMs: number,
-  visibility: WorktreePollerWindowVisibility,
-  options: WorktreeBasePollerOptions
-): Promise<WorktreeBaseSubscription> {
-  let disposed = false
-  let ticking = false
-  let tickCount = 0
-  let snapshot = await snapshotBase(target.path, getRepos())
-  let timer: ReturnType<typeof setTimeout> | null = null
-  let parkedWhileHidden = false
-  const pendingMarkerMaxTicks = options.pendingMarkerMaxTicks ?? PENDING_MARKER_MAX_TICKS
-  // dir → first probe tick; null means backstop scans only
-  const markerProbeStartedAt = new Map<string, number | null>()
-  for (const [dir, marker] of snapshot.markers) {
-    if (!marker) {
-      markerProbeStartedAt.set(dir, 0)
-    }
-  }
-
-  const fullScan = async (): Promise<void> => {
-    options.onFullScan?.()
-    const next = await snapshotBase(target.path, getRepos())
-    await options.onSnapshotTaken?.(tickCount)
-    if (disposed) {
-      return
-    }
-    const events = diffBase(snapshot, next)
-    for (const [dir, marker] of next.markers) {
-      if (marker) {
-        markerProbeStartedAt.delete(dir)
-      } else if (!markerProbeStartedAt.has(dir)) {
-        markerProbeStartedAt.set(dir, tickCount)
-      }
-    }
-    for (const dir of markerProbeStartedAt.keys()) {
-      if (!next.markers.has(dir)) {
-        markerProbeStartedAt.delete(dir)
-      }
-    }
-    snapshot = next
-    if (events.length > 0) {
-      onEvents(events)
-    }
-  }
-
-  const checkPendingMarkers = async (): Promise<void> => {
-    const events: WorktreeBasePollEvent[] = []
-    for (const [dir, firstSeenTick] of markerProbeStartedAt) {
-      if (firstSeenTick === null) {
-        continue
-      }
-      if (tickCount - firstSeenTick > pendingMarkerMaxTicks) {
-        markerProbeStartedAt.set(dir, null)
-        continue
-      }
-      options.onPendingMarkerProbe?.(join(dir, '.git'))
-      if (await hasGitMarker(dir)) {
-        markerProbeStartedAt.delete(dir)
-        snapshot.markers.set(dir, true)
-        events.push({ type: 'create', path: join(dir, '.git') })
-      }
-    }
-    if (!disposed && events.length > 0) {
-      onEvents(events)
-    }
-  }
-
-  const poll = async (forceFullScan = false): Promise<void> => {
-    tickCount++
-    if (forceFullScan || tickCount % WORKTREE_BASE_BACKSTOP_TICKS === 0) {
-      await fullScan()
-      return
-    }
-    // Idle fast path: when the dirs whose listings define the candidate set
-    // are untouched, skip the readdir + per-candidate stat fan-out entirely.
-    const signatures = await Promise.all(snapshot.gateDirs.map(dirSignature))
-    const gateChanged =
-      signatures.length !== snapshot.gateSignatures.length ||
-      signatures.some((sig, index) => sig !== snapshot.gateSignatures[index])
-    if (gateChanged) {
-      await fullScan()
-      return
-    }
-    if (markerProbeStartedAt.size > 0) {
-      await checkPendingMarkers()
-    }
-  }
-
-  const tick = async (forceFullScan = false): Promise<void> => {
-    timer = null
-    if (disposed) {
-      return
-    }
-    if (!visibility.isWindowVisible()) {
-      parkedWhileHidden = true
-      return
-    }
-    if (ticking) {
-      return
-    }
-    ticking = true
-    // Why: measure from tick start so the cadence is start-to-start (like the old setInterval), not
-    // gap-after-completion — otherwise each visible refresh lands a full scan-duration late every tick.
-    const startedAt = Date.now()
-    try {
-      await poll(forceFullScan)
-    } catch {
-      // Transient fs error: keep the previous snapshot and retry next tick.
-    } finally {
-      ticking = false
-    }
-    if (!disposed) {
-      // Why: clamp to [0, pollIntervalMs]. Date.now() is not monotonic — a backward wall-clock jump (NTP) would
-      // otherwise make elapsed negative and push the next tick out by the adjustment (suppressing refreshes for
-      // minutes); the upper clamp caps the wait at one interval, the lower clamp keeps a long scan from going negative.
-      const nextDelay = Math.max(
-        0,
-        Math.min(pollIntervalMs, pollIntervalMs - (Date.now() - startedAt))
-      )
-      timer = setTimeout(() => void tick(), nextDelay)
-      timer.unref?.()
-    }
-  }
-
-  const unsubscribeVisibility = visibility.onWindowBecameVisible(() => {
-    if (disposed || !parkedWhileHidden) {
-      return
-    }
-    parkedWhileHidden = false
-    // Why: the ordinary dir-signature gate can miss same-granule changes made
-    // while hidden; resume must diff a fresh full snapshot against the baseline.
-    void tick(true)
-  })
-
-  timer = setTimeout(() => void tick(), pollIntervalMs)
-  timer.unref?.()
-
-  return {
-    unsubscribe: async () => {
-      disposed = true
-      if (timer) {
-        clearTimeout(timer)
-      }
-      unsubscribeVisibility()
-    }
-  }
-}
-
 /** Watches the shallow paths a worktree base target cares about and emits
  *  watcher-shaped events. Resolves once the baseline (snapshot or narrow
  *  native subscription) is established. */
@@ -378,7 +104,8 @@ export async function startWorktreeBaseDirectoryPoller(
       visibility,
       options.onFullScan,
       options.getGitStatusRefPaths,
-      options.onWatchError
+      options.onWatchError,
+      options.onOverflow
     )
   }
   return startBasePoller(target, getRepos, onEvents, pollIntervalMs, visibility, options)
diff --git a/src/main/ipc/worktree-base-directory-watch-events.ts b/src/main/ipc/worktree-base-directory-watch-events.ts
new file mode 100644
index 00000000000..caed5627b2b
--- /dev/null
+++ b/src/main/ipc/worktree-base-directory-watch-events.ts
@@ -0,0 +1,90 @@
+import {
+  collectLocalWorktreeBaseChanges,
+  collectRemoteWorktreeBaseChanges,
+  hasCollectedWorktreeBaseChanges
+} from './worktree-base-directory-change-collector'
+import {
+  scheduleWorktreeBaseNotification,
+  type WorktreeBaseNotificationWatch
+} from './worktree-base-directory-notifications'
+import {
+  invalidateActiveGitStatusRefResolution,
+  invalidateGitStatusRefResolutionForPaths
+} from './worktree-git-status-ref-watch'
+import type { WorktreeWatcherFailureRefreshCooldown } from './worktree-watcher-failure-refresh-cooldown'
+
+export type ActiveWatch = WorktreeBaseNotificationWatch & {
+  subscription: { unsubscribe: () => Promise<void> }
+  gitStatusRefPaths: Set<string>
+  watcherFailureRefresh: WorktreeWatcherFailureRefreshCooldown
+}
+
+export function handleLocalWatchEvents(
+  watch: ActiveWatch,
+  error: Error | null,
+  events: { type: 'create' | 'update' | 'delete'; path: string }[],
+  getActiveWatches: () => Iterable<ActiveWatch>
+): void {
+  if (watch.disposed || watch.mainWindow.isDestroyed()) {
+    return
+  }
+  if (error) {
+    console.warn(`[worktree-base-watcher] watcher failed for ${watch.path}:`, error)
+    invalidateActiveGitStatusRefResolution(watch, getActiveWatches)
+    if (watch.watcherFailureRefresh.consume()) {
+      scheduleWorktreeBaseNotification(watch, { structureRepoIds: [...watch.repos.keys()] })
+    }
+    return
+  }
+  watch.watcherFailureRefresh.reset()
+  invalidateGitStatusRefResolutionForPaths(
+    watch,
+    events.map((event) => event.path),
+    getActiveWatches
+  )
+  const changes = collectLocalWorktreeBaseChanges(watch, events)
+  if (hasCollectedWorktreeBaseChanges(changes)) {
+    scheduleWorktreeBaseNotification(watch, changes)
+  }
+}
+
+// Why: after a dropped event batch nothing about the prior state can be
+// trusted — widen unconditionally (structural + status + head-identity),
+// same shape as the remote overflow branch below, bypassing the watcher-error
+// cooldown so a burst of overflows during one bulk op cannot suppress the
+// refresh the fleet actually needs.
+export function handleWatchOverflow(
+  watch: ActiveWatch,
+  getActiveWatches: () => Iterable<ActiveWatch>
+): void {
+  if (watch.disposed || watch.mainWindow.isDestroyed()) {
+    return
+  }
+  invalidateActiveGitStatusRefResolution(watch, getActiveWatches)
+  scheduleWorktreeBaseNotification(watch, { structureRepoIds: [...watch.repos.keys()] })
+}
+
+export function handleRemoteWatchEvents(
+  watch: ActiveWatch,
+  events: Parameters<typeof collectRemoteWorktreeBaseChanges>[1],
+  getActiveWatches: () => Iterable<ActiveWatch>
+): void {
+  if (watch.disposed || watch.mainWindow.isDestroyed()) {
+    return
+  }
+  invalidateGitStatusRefResolutionForPaths(
+    watch,
+    events.flatMap((event) =>
+      event.kind === 'overflow' ? [] : [event.absolutePath, event.oldAbsolutePath]
+    ),
+    getActiveWatches
+  )
+  const changes = collectRemoteWorktreeBaseChanges(watch, events)
+  if (changes.overflow) {
+    handleWatchOverflow(watch, getActiveWatches)
+    return
+  }
+  if (hasCollectedWorktreeBaseChanges(changes)) {
+    scheduleWorktreeBaseNotification(watch, changes)
+  }
+}
diff --git a/src/main/ipc/worktree-base-directory-watcher.test.ts b/src/main/ipc/worktree-base-directory-watcher.test.ts
index 5d701b91211..a23bc901bdc 100644
--- a/src/main/ipc/worktree-base-directory-watcher.test.ts
+++ b/src/main/ipc/worktree-base-directory-watcher.test.ts
@@ -404,6 +404,46 @@ describe('worktree base directory watcher', () => {
     expect(notifyWorktreesChanged).toHaveBeenCalledOnce()
   })
 
+  it('widens an overflowed local git-common watch to a structural refresh', async () => {
+    await syncWorktreeBaseDirectoryWatchers(makeStore([makeRepo()]) as never, makeWindow() as never)
+    const onOverflow = pollerOptions.get(PROJECT_GIT_COMMON_DIR)?.onOverflow
+
+    const request = {
+      worktreeId: `repo-1::${PROJECT_ROOT}`,
+      worktreePath: PROJECT_ROOT,
+      executionHostId: 'local',
+      branch: 'refs/heads/feature',
+      upstreamName: 'origin/feature'
+    }
+    const resolve = vi.fn(async () => 'refs/remotes/origin/feature')
+    await setWorktreeGitStatusRefWatch(request, resolve)
+
+    onOverflow?.()
+    await vi.advanceTimersByTimeAsync(300)
+
+    expect(notifyWorktreesChanged).toHaveBeenCalledWith(expect.anything(), 'repo-1')
+    // Overflow is definite proof of loss, not a possibly-transient error — it
+    // invalidates the cached ref resolution unconditionally.
+    await setWorktreeGitStatusRefWatch(request, resolve)
+    expect(resolve).toHaveBeenCalledTimes(2)
+  })
+
+  it('does not throttle repeated overflow refreshes the way watcher-error refreshes are throttled', async () => {
+    await syncWorktreeBaseDirectoryWatchers(makeStore([makeRepo()]) as never, makeWindow() as never)
+    const onOverflow = pollerOptions.get(PROJECT_GIT_COMMON_DIR)?.onOverflow
+
+    onOverflow?.()
+    await vi.advanceTimersByTimeAsync(300)
+    onOverflow?.()
+    await vi.advanceTimersByTimeAsync(300)
+
+    // A watcher-error burst within the 60s cooldown window collapses to one
+    // refresh (see "throttles repeated structural refreshes from watcher
+    // failures" above); overflow must not inherit that gate, since a bulk op
+    // can legitimately overflow more than once before it settles.
+    expect(notifyWorktreesChanged).toHaveBeenCalledTimes(2)
+  })
+
   it('keeps linked HEAD and lock metadata structural', async () => {
     await syncWorktreeBaseDirectoryWatchers(makeStore([makeRepo()]) as never, makeWindow() as never)
 
diff --git a/src/main/ipc/worktree-base-directory-watcher.ts b/src/main/ipc/worktree-base-directory-watcher.ts
index 57a231e89b2..abb0d51782c 100644
--- a/src/main/ipc/worktree-base-directory-watcher.ts
+++ b/src/main/ipc/worktree-base-directory-watcher.ts
@@ -6,16 +6,9 @@ import {
   disposeWorktreeHeadIdentityRefreshState,
   refreshWorktreeHeadIdentities
 } from './worktree-head-identity-refresh'
-import {
-  collectLocalWorktreeBaseChanges,
-  collectRemoteWorktreeBaseChanges,
-  hasCollectedWorktreeBaseChanges
-} from './worktree-base-directory-change-collector'
 import {
   clearPendingWorktreeBaseNotifications,
-  scheduleWorktreeBaseNotification,
-  supportsWorktreeHeadIdentityRefresh,
-  type WorktreeBaseNotificationWatch
+  supportsWorktreeHeadIdentityRefresh
 } from './worktree-base-directory-notifications'
 import type { WorktreeBaseWatchTarget } from './worktree-base-directory-event-filter'
 import { EMPTY_HEAD_IDENTITY_SCOPE } from './worktree-head-identity-scope'
@@ -30,18 +23,16 @@ import {
 import {
   applyActiveGitStatusRefBinding,
   clearActiveGitStatusRefBinding,
-  invalidateActiveGitStatusRefResolution,
-  invalidateGitStatusRefResolutionForPaths,
   updateActiveGitStatusRefBinding,
   type GitStatusRefBindingRequest
 } from './worktree-git-status-ref-watch'
 import { WorktreeWatcherFailureRefreshCooldown } from './worktree-watcher-failure-refresh-cooldown'
-
-type ActiveWatch = WorktreeBaseNotificationWatch & {
-  subscription: { unsubscribe: () => Promise<void> }
-  gitStatusRefPaths: Set<string>
-  watcherFailureRefresh: WorktreeWatcherFailureRefreshCooldown
-}
+import {
+  handleLocalWatchEvents,
+  handleRemoteWatchEvents,
+  handleWatchOverflow,
+  type ActiveWatch
+} from './worktree-base-directory-watch-events'
 
 const activeWatches = new Map<string, ActiveWatch>()
 let syncGeneration = 0
@@ -54,59 +45,6 @@ export function setWorktreeGitStatusRefWatch(
   return updateActiveGitStatusRefBinding(args, () => activeWatches.values(), resolveUpstreamRef)
 }
 
-function handleLocalWatchEvents(
-  watch: ActiveWatch,
-  error: Error | null,
-  events: { type: 'create' | 'update' | 'delete'; path: string }[]
-): void {
-  if (watch.disposed || watch.mainWindow.isDestroyed()) {
-    return
-  }
-  if (error) {
-    console.warn(`[worktree-base-watcher] watcher failed for ${watch.path}:`, error)
-    invalidateActiveGitStatusRefResolution(watch, () => activeWatches.values())
-    if (watch.watcherFailureRefresh.consume()) {
-      scheduleWorktreeBaseNotification(watch, { structureRepoIds: [...watch.repos.keys()] })
-    }
-    return
-  }
-  watch.watcherFailureRefresh.reset()
-  invalidateGitStatusRefResolutionForPaths(
-    watch,
-    events.map((event) => event.path),
-    () => activeWatches.values()
-  )
-  const changes = collectLocalWorktreeBaseChanges(watch, events)
-  if (hasCollectedWorktreeBaseChanges(changes)) {
-    scheduleWorktreeBaseNotification(watch, changes)
-  }
-}
-
-function handleRemoteWatchEvents(
-  watch: ActiveWatch,
-  events: Parameters<typeof collectRemoteWorktreeBaseChanges>[1]
-): void {
-  if (watch.disposed || watch.mainWindow.isDestroyed()) {
-    return
-  }
-  invalidateGitStatusRefResolutionForPaths(
-    watch,
-    events.flatMap((event) =>
-      event.kind === 'overflow' ? [] : [event.absolutePath, event.oldAbsolutePath]
-    ),
-    () => activeWatches.values()
-  )
-  const changes = collectRemoteWorktreeBaseChanges(watch, events)
-  if (changes.overflow) {
-    invalidateActiveGitStatusRefResolution(watch, () => activeWatches.values())
-    scheduleWorktreeBaseNotification(watch, { structureRepoIds: [...watch.repos.keys()] })
-    return
-  }
-  if (hasCollectedWorktreeBaseChanges(changes)) {
-    scheduleWorktreeBaseNotification(watch, changes)
-  }
-}
-
 function createActiveWatch(
   target: WorktreeBaseWatchTarget,
   mainWindow: BrowserWindow,
@@ -146,7 +84,7 @@ async function subscribeTarget(
       if (!currentWatch || currentWatch.disposed) {
         return
       }
-      handleRemoteWatchEvents(currentWatch, events)
+      handleRemoteWatchEvents(currentWatch, events, () => activeWatches.values())
     })
     activeWatch = createActiveWatch(
       target,
@@ -167,7 +105,7 @@ async function subscribeTarget(
     (events) => {
       const currentWatch = activeWatches.get(target.key) ?? activeWatch
       if (currentWatch && !currentWatch.disposed) {
-        handleLocalWatchEvents(currentWatch, null, events)
+        handleLocalWatchEvents(currentWatch, null, events, () => activeWatches.values())
       }
     },
     {
@@ -178,7 +116,13 @@ async function subscribeTarget(
       onWatchError: (error) => {
         const currentWatch = activeWatches.get(target.key) ?? activeWatch
         if (currentWatch && !currentWatch.disposed) {
-          handleLocalWatchEvents(currentWatch, error, [])
+          handleLocalWatchEvents(currentWatch, error, [], () => activeWatches.values())
+        }
+      },
+      onOverflow: () => {
+        const currentWatch = activeWatches.get(target.key) ?? activeWatch
+        if (currentWatch) {
+          handleWatchOverflow(currentWatch, () => activeWatches.values())
         }
       }
     }
diff --git a/src/main/ipc/worktree-git-common-narrow-watch.ts b/src/main/ipc/worktree-git-common-narrow-watch.ts
index 99e245998a1..fa7c402c5ec 100644
--- a/src/main/ipc/worktree-git-common-narrow-watch.ts
+++ b/src/main/ipc/worktree-git-common-narrow-watch.ts
@@ -24,7 +24,12 @@ export async function startGitCommonNarrowWatch(
   platform: NodeJS.Platform,
   visibility: WorktreePollerWindowVisibility,
   onFullScan?: () => void,
-  onWatchError?: (error: Error) => void
+  onWatchError?: (error: Error) => void,
+  // Why: a dropped event batch (>5,000 events, e.g. a fleet-wide bulk op) is a
+  // harder loss signal than a transient error — nothing about the prior state
+  // can be trusted, so this bypasses onWatchError's failure cooldown instead
+  // of reusing it.
+  onOverflow?: () => void
 ): Promise<WorktreeBaseSubscription> {
   const worktreesDir = join(target.path, 'worktrees')
   const watcherOptions = platform === 'win32' ? { backend: 'windows' as const } : {}
@@ -227,6 +232,23 @@ export async function startGitCommonNarrowWatch(
                 onEvents([{ type: 'update', path: worktreesDir }])
               }
             }
+          },
+          // Why: the watcher child drops the whole batch past 5,000 events
+          // (native FSEvents overflow maps to the same op) instead of reporting
+          // which paths changed. Unlike a transient error, this is definite
+          // proof of loss, so it always widens rather than falling back to the
+          // failure-cooldown-gated onWatchError path.
+          onOverflow: () => {
+            if (disposed || !active || generation !== nativeSubscriptionGeneration) {
+              return
+            }
+            if (onOverflow) {
+              onOverflow()
+            } else if (onWatchError) {
+              onWatchError(new Error('Git common watcher overflowed'))
+            } else {
+              onEvents([{ type: 'update', path: worktreesDir }])
+            }
           }
         }
       )
diff --git a/src/main/ipc/worktree-git-common-watch.test.ts b/src/main/ipc/worktree-git-common-watch.test.ts
index 619133263de..bad700b5445 100644
--- a/src/main/ipc/worktree-git-common-watch.test.ts
+++ b/src/main/ipc/worktree-git-common-watch.test.ts
@@ -526,6 +526,45 @@ describe('worktree git-common narrow watch (local native platforms)', () => {
     expect(narrowSubscription().unsubscribe).not.toHaveBeenCalled()
   })
 
+  it('routes a dropped event batch through the dedicated overflow callback', async () => {
+    installSubscribeMock()
+    const commonDir = await makeCommonDir(true)
+    const received: WorktreeBasePollEvent[][] = []
+    const onOverflow = vi.fn()
+    const watch = await startGitCommonWatch(
+      makeTarget(commonDir),
+      (events) => received.push(events),
+      POLL_MS,
+      'darwin',
+      alwaysVisible,
+      undefined,
+      () => [],
+      undefined,
+      onOverflow
+    )
+    cleanups.push(() => watch.unsubscribe())
+
+    narrowSubscription().hooks.onOverflow?.()
+
+    expect(onOverflow).toHaveBeenCalledOnce()
+    // The dedicated callback owns the refresh; the generic event/error paths
+    // must not also fire so the caller cannot double-count the same loss.
+    expect(received).toEqual([])
+    expect(narrowSubscription().unsubscribe).not.toHaveBeenCalled()
+  })
+
+  it('falls back to a structural change when no overflow callback is wired', async () => {
+    installSubscribeMock()
+    const commonDir = await makeCommonDir(true)
+    const worktreesDir = join(commonDir, 'worktrees')
+    const received: WorktreeBasePollEvent[][] = []
+    await startWatch(commonDir, received)
+
+    narrowSubscription().hooks.onOverflow?.()
+
+    expect(received.flat()).toContainEqual({ type: 'update', path: worktreesDir })
+  })
+
   it('arms via existence polling when the worktrees dir appears later', async () => {
     installSubscribeMock()
     const commonDir = await makeCommonDir(false)
diff --git a/src/main/ipc/worktree-git-common-watch.ts b/src/main/ipc/worktree-git-common-watch.ts
index 8ed696872f7..d719ca257bb 100644
--- a/src/main/ipc/worktree-git-common-watch.ts
+++ b/src/main/ipc/worktree-git-common-watch.ts
@@ -31,7 +31,8 @@ export async function startGitCommonWatch(
   visibility: WorktreePollerWindowVisibility,
   onFullScan?: () => void,
   getStatusRefPaths: () => readonly string[] = () => [],
-  onWatchError?: (error: Error) => void
+  onWatchError?: (error: Error) => void,
+  onOverflow?: () => void
 ): Promise<WorktreeBaseSubscription> {
   if (supportsNarrowWatch(platform)) {
     const [narrowWatch, primaryWatch] = await Promise.all([
@@ -42,7 +43,8 @@ export async function startGitCommonWatch(
         platform,
         visibility,
         onFullScan,
-        onWatchError
+        onWatchError,
+        onOverflow
       ),
       startGitCommonPrimaryWatch(
         target.path,

From 6c8eea5ebeac6948998f769aa0ec4fa8a5ec72ab Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Tue, 1 Sep 2026 20:26:00 -0700
Subject: [PATCH 32/32] perf(worktree): fix the prepared-checkout hit rate and
 make misses visible (#17863)

---
 .../worktree-base-divergence-real-git.test.ts |  99 +++++
 src/main/git/worktree-base-divergence.test.ts | 181 +++++++++
 src/main/git/worktree-base-divergence.ts      | 165 ++++++++
 src/main/git/worktree-base-ref-probe.ts       |  15 +
 ...rktree-create-preparation-real-git.test.ts |  49 +++
 src/main/ipc/worktree-remote.ts               |  16 +-
 .../ipc/worktrees-local-create-flow.test.ts   |   7 +-
 ...trees-setup-launch-sparse-checkout.test.ts |   9 +-
 .../observability/instrumentation.test.ts     |  34 ++
 src/main/observability/instrumentation.ts     |  19 +-
 .../runtime-local-git-worktree-create.ts      |   7 +-
 .../worktree-create-preparation-claim.test.ts | 152 ++++++++
 src/main/worktree-create-preparation-claim.ts | 130 +++++++
 src/main/worktree-create-preparation-pool.ts  | 210 +++++++++++
 ...rktree-create-preparation-wsl-root.test.ts |   9 +-
 src/main/worktree-create-preparation.test.ts  | 353 ++++++++++++++----
 src/main/worktree-create-preparation.ts       | 334 +++++++----------
 src/main/worktree-create-timing.ts            |   9 +-
 src/shared/git-binary-compatibility.test.ts   |  32 ++
 src/shared/worktree/base-ref.test.ts          |  30 +-
 src/shared/worktree/base-ref.ts               |  27 ++
 src/shared/worktree/create-types.ts           |  31 ++
 22 files changed, 1644 insertions(+), 274 deletions(-)
 create mode 100644 src/main/git/worktree-base-divergence-real-git.test.ts
 create mode 100644 src/main/git/worktree-base-divergence.test.ts
 create mode 100644 src/main/git/worktree-base-divergence.ts
 create mode 100644 src/main/worktree-create-preparation-claim.test.ts
 create mode 100644 src/main/worktree-create-preparation-claim.ts
 create mode 100644 src/main/worktree-create-preparation-pool.ts

diff --git a/src/main/git/worktree-base-divergence-real-git.test.ts b/src/main/git/worktree-base-divergence-real-git.test.ts
new file mode 100644
index 00000000000..e17192cf914
--- /dev/null
+++ b/src/main/git/worktree-base-divergence-real-git.test.ts
@@ -0,0 +1,99 @@
+import { execFileSync } from 'node:child_process'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import {
+  measureRetargetDivergence,
+  RETARGET_MAX_COMMIT_DIVERGENCE
+} from './worktree-base-divergence'
+
+const tempRoots: string[] = []
+
+function git(cwd: string, args: string[]): string {
+  return execFileSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe']
+  }).trim()
+}
+
+async function createRepo(): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), 'orca-base-divergence-'))
+  tempRoots.push(root)
+  const repoPath = join(root, 'repo')
+  execFileSync('git', ['init', '--quiet', repoPath])
+  git(repoPath, ['symbolic-ref', 'HEAD', 'refs/heads/main'])
+  git(repoPath, ['config', 'user.email', 'test@example.com'])
+  git(repoPath, ['config', 'user.name', 'Test User'])
+  await writeFile(join(repoPath, 'version.txt'), 'one\n')
+  git(repoPath, ['add', 'version.txt'])
+  git(repoPath, ['commit', '--quiet', '-m', 'initial'])
+  return repoPath
+}
+
+function commitEmpty(repoPath: string, count: number): void {
+  for (let index = 0; index < count; index += 1) {
+    git(repoPath, ['commit', '--quiet', '--allow-empty', '-m', `commit ${index}`])
+  }
+}
+
+afterEach(async () => {
+  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })))
+})
+
+describe('measureRetargetDivergence with real Git', () => {
+  it('allows the drift between a local branch and its remote-tracking copy', async () => {
+    const repoPath = await createRepo()
+    git(repoPath, ['update-ref', 'refs/remotes/origin/main', 'HEAD'])
+    commitEmpty(repoPath, 5)
+    git(repoPath, ['update-ref', 'refs/remotes/origin/main', 'HEAD'])
+    git(repoPath, ['reset', '--hard', '--quiet', 'HEAD~3'])
+
+    await expect(
+      measureRetargetDivergence(repoPath, 'refs/heads/main', 'refs/remotes/origin/main')
+    ).resolves.toBe('within')
+  })
+
+  it('counts drift in both directions', async () => {
+    const repoPath = await createRepo()
+    const forkPoint = git(repoPath, ['rev-parse', 'HEAD'])
+    commitEmpty(repoPath, RETARGET_MAX_COMMIT_DIVERGENCE)
+    git(repoPath, ['update-ref', 'refs/remotes/origin/main', 'HEAD'])
+    git(repoPath, ['reset', '--hard', '--quiet', forkPoint])
+    commitEmpty(repoPath, 1)
+
+    // 100 ahead + 1 behind is over the cap even though neither side alone exceeds it.
+    await expect(
+      measureRetargetDivergence(repoPath, 'refs/heads/main', 'refs/remotes/origin/main')
+    ).resolves.toBe('exceeded')
+  })
+
+  it('refuses a base that has drifted past the cap', async () => {
+    const repoPath = await createRepo()
+    git(repoPath, ['update-ref', 'refs/remotes/origin/main', 'HEAD'])
+    commitEmpty(repoPath, RETARGET_MAX_COMMIT_DIVERGENCE + 1)
+
+    await expect(
+      measureRetargetDivergence(repoPath, 'refs/remotes/origin/main', 'refs/heads/main')
+    ).resolves.toBe('exceeded')
+  })
+
+  it('refuses unrelated histories, which share no commits at all', async () => {
+    const repoPath = await createRepo()
+    git(repoPath, ['checkout', '--quiet', '--orphan', 'unrelated'])
+    git(repoPath, ['commit', '--quiet', '--allow-empty', '-m', 'unrelated root'])
+
+    await expect(
+      measureRetargetDivergence(repoPath, 'refs/heads/main', 'refs/heads/unrelated')
+    ).resolves.toBe('exceeded')
+  })
+
+  it('reports an unreadable ref as unverifiable, not as excess drift', async () => {
+    const repoPath = await createRepo()
+
+    await expect(
+      measureRetargetDivergence(repoPath, 'refs/heads/main', 'refs/heads/missing')
+    ).resolves.toBe('unknown')
+  })
+})
diff --git a/src/main/git/worktree-base-divergence.test.ts b/src/main/git/worktree-base-divergence.test.ts
new file mode 100644
index 00000000000..88eec6a6b11
--- /dev/null
+++ b/src/main/git/worktree-base-divergence.test.ts
@@ -0,0 +1,181 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({ gitExecFileAsync: vi.fn() }))
+
+vi.mock('./runner', () => ({ gitExecFileAsync: mocks.gitExecFileAsync }))
+
+import { GIT_READ_TIMEOUT_MS } from './command-runner/git-command-timeout'
+import { WSL_GIT_READ_ENVIRONMENT_WAIT_MS } from './wsl-git-read-environment'
+import {
+  measureRetargetDivergence,
+  RETARGET_DIVERGENCE_BUDGET_MS
+} from './worktree-base-divergence'
+
+type ExecOptions = { cwd: string; timeout?: number; wslDistro?: string; signal?: AbortSignal }
+
+function callOptions(): ExecOptions[] {
+  return mocks.gitExecFileAsync.mock.calls.map((call) => call[1] as ExecOptions)
+}
+
+function subcommands(): string[] {
+  return mocks.gitExecFileAsync.mock.calls.map((call) => (call[0] as string[])[0]!)
+}
+
+function answerProbes(count: string, mergeBase = 'abc123\n') {
+  mocks.gitExecFileAsync.mockImplementation(async (args: string[]) =>
+    args[0] === 'merge-base' ? { stdout: mergeBase } : { stdout: count }
+  )
+}
+
+function exitCodeError(code: number): Error & { code: number } {
+  return Object.assign(new Error('git exited'), { code })
+}
+
+beforeEach(() => {
+  mocks.gitExecFileAsync.mockReset()
+})
+
+describe('measureRetargetDivergence deadlines', () => {
+  it('puts every probe under one shared budget, not a budget each', async () => {
+    answerProbes('3\n')
+
+    await expect(
+      measureRetargetDivergence('/repo', 'refs/heads/main', 'refs/remotes/origin/main')
+    ).resolves.toBe('within')
+
+    expect(subcommands()).toEqual(['rev-list', 'rev-list', 'merge-base'])
+    const signals = callOptions().map((options) => options.signal)
+    // One signal object across all three: the counts and merge-base are staged, so per-probe
+    // budgets would let the check cost the sum of them.
+    expect(new Set(signals).size).toBe(1)
+    expect(signals[0]).toBeInstanceOf(AbortSignal)
+  })
+
+  it('also gives each probe a command timeout well below git default read deadline', async () => {
+    answerProbes('3\n')
+
+    await measureRetargetDivergence('/repo', 'refs/heads/main', 'refs/remotes/origin/main')
+
+    // The signal covers admission queueing and the WSL environment wait, which start before a
+    // command timeout exists; the timeout still covers a hung spawn.
+    for (const options of callOptions()) {
+      expect(options.timeout).toBe(RETARGET_DIVERGENCE_BUDGET_MS)
+    }
+    expect(RETARGET_DIVERGENCE_BUDGET_MS).toBeLessThan(GIT_READ_TIMEOUT_MS)
+  })
+
+  it('really aborts the in-flight probes when the shared budget expires', async () => {
+    // A probe that behaves like a slow walk: it produces nothing on its own and only settles when
+    // its signal fires. If the budget never fired, or never reached the probe, this hangs and the
+    // test fails on its own timeout rather than passing on a signal that does nothing.
+    mocks.gitExecFileAsync.mockImplementation(
+      (_args: string[], options: ExecOptions) =>
+        new Promise((_resolve, reject) => {
+          options.signal?.addEventListener(
+            'abort',
+            () =>
+              reject(
+                Object.assign(new Error('The operation was aborted.'), { name: 'AbortError' })
+              ),
+            { once: true }
+          )
+        })
+    )
+
+    await expect(
+      measureRetargetDivergence('/repo', 'refs/heads/main', 'refs/remotes/origin/main', {
+        budgetMsForTest: 25
+      })
+    ).resolves.toBe('unknown')
+  })
+
+  it('clears the WSL read-environment wait, which starts before any command timeout', () => {
+    // Equal to it would make the first WSL-routed create of a session `unknown` by construction,
+    // and the WSL numbers meaningless.
+    expect(RETARGET_DIVERGENCE_BUDGET_MS).toBeGreaterThan(WSL_GIT_READ_ENVIRONMENT_WAIT_MS)
+    expect(RETARGET_DIVERGENCE_BUDGET_MS).toBeLessThan(GIT_READ_TIMEOUT_MS)
+  })
+
+  it('stops the probes when the create itself is cancelled, without waiting for the budget', async () => {
+    mocks.gitExecFileAsync.mockImplementation(
+      (_args: string[], options: ExecOptions) =>
+        new Promise((_resolve, reject) => {
+          options.signal?.addEventListener(
+            'abort',
+            () =>
+              reject(
+                Object.assign(new Error('The operation was aborted.'), { name: 'AbortError' })
+              ),
+            { once: true }
+          )
+        })
+    )
+    const controller = new AbortController()
+    const pending = measureRetargetDivergence(
+      '/repo',
+      'refs/heads/main',
+      'refs/remotes/origin/main',
+      // A budget long enough that only the caller's cancellation can end this in time.
+      { signal: controller.signal, budgetMsForTest: 60_000 }
+    )
+    controller.abort()
+
+    await expect(pending).resolves.toBe('unknown')
+  })
+
+  it('reports a blown deadline as unverifiable rather than as excess drift', async () => {
+    mocks.gitExecFileAsync.mockRejectedValue(new Error('git timed out.'))
+
+    await expect(
+      measureRetargetDivergence('/repo', 'refs/heads/main', 'refs/remotes/origin/main')
+    ).resolves.toBe('unknown')
+    // A count that never answered must not go on to spend a merge-base walk.
+    expect(subcommands()).not.toContain('merge-base')
+  })
+
+  it('separates merge-base saying no from merge-base failing', async () => {
+    mocks.gitExecFileAsync.mockImplementation(async (args: string[]) => {
+      if (args[0] === 'merge-base') {
+        // Exit 1 is Git's answer for unrelated histories.
+        throw exitCodeError(1)
+      }
+      return { stdout: '2\n' }
+    })
+    await expect(
+      measureRetargetDivergence('/repo', 'refs/heads/main', 'refs/remotes/origin/main')
+    ).resolves.toBe('exceeded')
+
+    mocks.gitExecFileAsync.mockReset()
+    mocks.gitExecFileAsync.mockImplementation(async (args: string[]) => {
+      if (args[0] === 'merge-base') {
+        // A timeout carries no exit code and must not be read as "no common ancestor".
+        throw new Error('git timed out.')
+      }
+      return { stdout: '2\n' }
+    })
+    await expect(
+      measureRetargetDivergence('/repo', 'refs/heads/main', 'refs/remotes/origin/main')
+    ).resolves.toBe('unknown')
+  })
+
+  it('reports drift past the cap without spending a merge-base walk', async () => {
+    answerProbes('101\n')
+
+    await expect(
+      measureRetargetDivergence('/repo', 'refs/heads/main', 'refs/remotes/origin/main')
+    ).resolves.toBe('exceeded')
+    expect(subcommands()).not.toContain('merge-base')
+  })
+
+  it('routes every probe to the caller-named WSL distro', async () => {
+    answerProbes('1\n')
+
+    await measureRetargetDivergence('/repo', 'refs/heads/main', 'refs/remotes/origin/main', {
+      wslDistro: 'Ubuntu'
+    })
+
+    for (const options of callOptions()) {
+      expect(options).toMatchObject({ cwd: '/repo', wslDistro: 'Ubuntu' })
+    }
+  })
+})
diff --git a/src/main/git/worktree-base-divergence.ts b/src/main/git/worktree-base-divergence.ts
new file mode 100644
index 00000000000..c7c924c2f24
--- /dev/null
+++ b/src/main/git/worktree-base-divergence.ts
@@ -0,0 +1,165 @@
+import { WSL_GIT_READ_ENVIRONMENT_WAIT_MS } from './wsl-git-read-environment'
+import { gitExecFileAsync } from './runner'
+
+export type RetargetDivergenceOptions = {
+  wslDistro?: string
+  /** The create's own cancellation signal. Without it a cancelled create leaves these probes
+   *  running until the budget expires. */
+  signal?: AbortSignal
+  /** Shortens only the end-to-end budget so a test can observe a real abort; production always
+   *  uses the constant. Mirrors `timeoutMsForTest` on the git exec options. */
+  budgetMsForTest?: number
+}
+
+/** `unknown` is deliberately not folded into `exceeded`: "the bound says no" and "the bound could
+ *  not be evaluated" have different causes and different fixes, and only the second one means a
+ *  retarget that would have been cheap was skipped. `unknown` covers a blown deadline, a
+ *  cancelled create, and an ordinary Git failure alike — it is "no answer", not "slow". */
+export type RetargetDivergence = 'within' | 'exceeded' | 'unknown'
+
+/**
+ * How far two bases may drift and still be worth retargeting a prepared checkout between.
+ *
+ * Measured on a 21,715-file repo: a local `main` and its `origin/main` were 5 commits and 74
+ * files apart, while an abandoned fork's `main` — same branch name, so the same base family —
+ * was 8,173 commits and 21,708 files from `origin/main`, i.e. a whole-tree checkout. A commit
+ * count separates those by three orders of magnitude, so it is the cheap proxy for the tree diff
+ * the retarget reset would have to write.
+ */
+export const RETARGET_MAX_COMMIT_DIVERGENCE = 100
+
+/**
+ * Headroom for the walk itself, on top of the worst pre-spawn wait.
+ *
+ * ~3x the slowest walk measured on the 12GB/80k-ref repo (180ms to reject, 57ms to allow), so a
+ * cold WSL environment probe cannot eat the whole budget and make the answer `unknown` by
+ * construction.
+ */
+const RETARGET_DIVERGENCE_WALK_HEADROOM_MS = 500
+
+/**
+ * End-to-end deadline for the whole check, not per probe.
+ *
+ * Derived from the WSL read-environment wait rather than picked: `git-exec-file` awaits that probe
+ * before a command timeout even exists, so a budget merely equal to it would guarantee `unknown`
+ * on the first WSL-routed create of a session and make the WSL numbers meaningless. Deriving it
+ * keeps that relationship explicit instead of coincidental.
+ *
+ * Sized against what it competes with: this exists only to decide whether to skip a ~4.1s p50 cold
+ * `worktree add`, so when it expires the create pays the budget and then does that add anyway. The
+ * total stays under that add even on Windows, where a killed probe also awaits `taskkill /t`.
+ *
+ * It must be a signal, not just a per-command timeout, because a per-command timeout starts only
+ * after `git-exec-file` has awaited admission and the WSL read-environment probe, and because the
+ * counts and `merge-base` are staged — two per-probe budgets in sequence would be twice the number
+ * written here.
+ */
+export const RETARGET_DIVERGENCE_BUDGET_MS =
+  WSL_GIT_READ_ENVIRONMENT_WAIT_MS + RETARGET_DIVERGENCE_WALK_HEADROOM_MS
+
+function probeOptions(
+  repoPath: string,
+  options: RetargetDivergenceOptions,
+  signal: AbortSignal
+): { cwd: string; wslDistro?: string; signal: AbortSignal; timeout: number } {
+  // Built field by field rather than spread: the caller's bag carries a test-only key that must
+  // never reach git's exec options.
+  // Both bounds: the signal covers the pre-spawn waits (admission queue, WSL environment) that a
+  // command timeout cannot see, and the timeout keeps the bounded tree-kill path for a hung spawn.
+  return {
+    cwd: repoPath,
+    ...(options.wslDistro ? { wslDistro: options.wslDistro } : {}),
+    signal,
+    timeout: RETARGET_DIVERGENCE_BUDGET_MS
+  }
+}
+
+/** Commits reachable from `toRef` but not `fromRef`, capped; null when the probe was unusable. */
+async function countCommitsAhead(
+  repoPath: string,
+  fromRef: string,
+  toRef: string,
+  options: RetargetDivergenceOptions,
+  signal: AbortSignal
+): Promise<number | null> {
+  try {
+    // `--max-count` stops the walk, so an unrelated history costs a bounded number of commits
+    // rather than a full traversal. Both flags predate the Git 2.25 baseline.
+    // `--end-of-options` (Git 2.24) because a range whose left side began with `-` would
+    // otherwise parse as an option; callers only pass `refs/`-qualified names today, and this
+    // keeps that from being load-bearing.
+    const { stdout } = await gitExecFileAsync(
+      [
+        'rev-list',
+        '--count',
+        `--max-count=${RETARGET_MAX_COMMIT_DIVERGENCE + 1}`,
+        '--end-of-options',
+        `${fromRef}..${toRef}`
+      ],
+      probeOptions(repoPath, options, signal)
+    )
+    const count = Number.parseInt(stdout.trim(), 10)
+    return Number.isNaN(count) ? null : count
+  } catch {
+    return null
+  }
+}
+
+/** True/false when Git decided, null when the probe was unusable. */
+async function hasCommonHistory(
+  repoPath: string,
+  leftRef: string,
+  rightRef: string,
+  options: RetargetDivergenceOptions,
+  signal: AbortSignal
+): Promise<boolean | null> {
+  try {
+    const { stdout } = await gitExecFileAsync(
+      ['merge-base', '--end-of-options', leftRef, rightRef],
+      probeOptions(repoPath, options, signal)
+    )
+    return stdout.trim().length > 0
+  } catch (error) {
+    // Exit 1 is `merge-base` reporting no common ancestor, which is an answer. A timeout or abort
+    // carries no exit code and must not be read as one.
+    return (error as { code?: unknown }).code === 1 ? false : null
+  }
+}
+
+/**
+ * Whether retargeting a checkout prepared at `preparedBase` onto `targetBase` stays cheap.
+ *
+ * Fails closed on error, slowness, and cancellation alike: only a positive `within` authorizes
+ * reusing the checkout, so every other outcome lands on the cold create path.
+ */
+export async function measureRetargetDivergence(
+  repoPath: string,
+  preparedBase: string,
+  targetBase: string,
+  options: RetargetDivergenceOptions = {}
+): Promise<RetargetDivergence> {
+  const budget = AbortSignal.timeout(options.budgetMsForTest ?? RETARGET_DIVERGENCE_BUDGET_MS)
+  // Combined so cancelling the create stops the probes immediately rather than at the deadline.
+  const signal = options.signal ? AbortSignal.any([options.signal, budget]) : budget
+  // Both directions: commits the target adds decide what the reset writes, commits only the
+  // preparation has decide what it must delete.
+  const [ahead, behind] = await Promise.all([
+    countCommitsAhead(repoPath, preparedBase, targetBase, options, signal),
+    countCommitsAhead(repoPath, targetBase, preparedBase, options, signal)
+  ])
+  if (ahead === null || behind === null) {
+    return 'unknown'
+  }
+  if (ahead + behind > RETARGET_MAX_COMMIT_DIVERGENCE) {
+    return 'exceeded'
+  }
+  // Only now: `merge-base` has no `--max-count`, so on unrelated histories it would walk both of
+  // them in full. Reaching here already proved neither side is more than the cap ahead of the
+  // other, which bounds that walk — and unrelated histories of any size fail the counts first.
+  // Required because unrelated histories replace the whole tree however few commits they carry.
+  const shareHistory = await hasCommonHistory(repoPath, preparedBase, targetBase, options, signal)
+  if (shareHistory === null) {
+    return 'unknown'
+  }
+  return shareHistory ? 'within' : 'exceeded'
+}
diff --git a/src/main/git/worktree-base-ref-probe.ts b/src/main/git/worktree-base-ref-probe.ts
index 8e44877ab76..87c761ebbcc 100644
--- a/src/main/git/worktree-base-ref-probe.ts
+++ b/src/main/git/worktree-base-ref-probe.ts
@@ -42,6 +42,21 @@ export async function hasWorktreeBaseCommitRef(
   return (await resolveWorktreeBaseCommitOid(repoPath, qualifiedRef, options)) !== null
 }
 
+/**
+ * The qualified ref a worktree base names in this repo, or the base unchanged when nothing
+ * matches. Callers that key on a base must compare this, not the raw string, or `main` and
+ * `refs/heads/main` look like different bases.
+ */
+export function resolveLocalWorktreeBaseRef(
+  repoPath: string,
+  baseRef: string,
+  options: GitExecOptions = {}
+): Promise<string> {
+  return resolveWorktreeAddBaseRef(baseRef, (qualifiedRef) =>
+    hasWorktreeBaseCommitRef(repoPath, qualifiedRef, options)
+  )
+}
+
 /**
  * Whether a worktree base — a qualified ref, a short branch or remote name, or a
  * full commit id — already resolves in this repo's own object/ref store.
diff --git a/src/main/git/worktree-create-preparation-real-git.test.ts b/src/main/git/worktree-create-preparation-real-git.test.ts
index bdb1e9fcc4b..63f8021a7ae 100644
--- a/src/main/git/worktree-create-preparation-real-git.test.ts
+++ b/src/main/git/worktree-create-preparation-real-git.test.ts
@@ -68,6 +68,55 @@ describe('prepared worktree creation with real Git', () => {
     expect(await listWorktrees(repoPath, { includeCreatePreparations: true })).toHaveLength(1)
   })
 
+  it('lands a cross-base retarget on exactly the requested commit', async () => {
+    const { repoPath, root } = await createRepo()
+    const preparationRoot = join(root, WORKTREE_CREATE_PREPARATION_DIRECTORY)
+    const preparedPath = join(preparationRoot, `${process.pid}-retarget`)
+    const finalPath = join(root, 'retargeted-worktree')
+    await mkdir(preparationRoot, { recursive: true })
+
+    await writeFile(join(repoPath, 'shared.txt'), 'kept\n')
+    git(repoPath, ['add', 'shared.txt'])
+    git(repoPath, ['commit', '--quiet', '-m', 'local main'])
+    const localMainHead = git(repoPath, ['rev-parse', 'HEAD'])
+
+    // A remote-tracking `main` that diverged: different content, an extra file, and one deletion.
+    git(repoPath, ['checkout', '--quiet', '-b', 'upstream-main'])
+    await writeFile(join(repoPath, 'version.txt'), 'two\n')
+    await writeFile(join(repoPath, 'only-upstream.txt'), 'upstream\n')
+    git(repoPath, ['rm', '--quiet', 'shared.txt'])
+    git(repoPath, ['add', 'version.txt', 'only-upstream.txt'])
+    git(repoPath, ['commit', '--quiet', '-m', 'upstream main'])
+    git(repoPath, ['update-ref', 'refs/remotes/origin/main', 'HEAD'])
+    git(repoPath, ['checkout', '--quiet', 'main'])
+    git(repoPath, ['branch', '--quiet', '-D', 'upstream-main'])
+
+    await prepareWorktreeCreateCheckout(
+      repoPath,
+      preparedPath,
+      'refs/remotes/origin/main',
+      createWorktreePreparationLockReason('retarget-test')
+    )
+    expect(git(preparedPath, ['rev-parse', 'HEAD'])).not.toBe(localMainHead)
+
+    await finalizePreparedWorktree(repoPath, preparedPath, finalPath, 'feature/retargeted', 'main')
+
+    expect(git(finalPath, ['rev-parse', 'HEAD'])).toBe(localMainHead)
+    // A retarget that left stale files behind would be a wrong checkout, not just a slow one.
+    expect(git(finalPath, ['status', '--porcelain'])).toBe('')
+    expect((await readFile(join(finalPath, 'version.txt'), 'utf8')).replaceAll('\r\n', '\n')).toBe(
+      'one\n'
+    )
+    expect((await readFile(join(finalPath, 'shared.txt'), 'utf8')).replaceAll('\r\n', '\n')).toBe(
+      'kept\n'
+    )
+    await expect(readFile(join(finalPath, 'only-upstream.txt'), 'utf8')).rejects.toThrow()
+    expect(git(finalPath, ['branch', '--show-current'])).toBe('feature/retargeted')
+    expect(git(finalPath, ['config', '--get', 'branch.feature/retargeted.base'])).toBe(
+      'refs/heads/main'
+    )
+  })
+
   it('hides the preparation, retargets an advanced base, and attaches the final branch', async () => {
     const { repoPath, root } = await createRepo()
     const preparationRoot = join(root, WORKTREE_CREATE_PREPARATION_DIRECTORY)
diff --git a/src/main/ipc/worktree-remote.ts b/src/main/ipc/worktree-remote.ts
index 7d28f38f2db..ce6ee7b3394 100644
--- a/src/main/ipc/worktree-remote.ts
+++ b/src/main/ipc/worktree-remote.ts
@@ -2402,7 +2402,7 @@ export async function createLocalWorktree(
     addResult =
       (await timing.time('git_worktree_add', async () => {
         if (sparseDirectories.length === 0 && !checkoutExistingBranch) {
-          const preparedResult = await consumePreparedWorktreeCreate({
+          const prepared = await consumePreparedWorktreeCreate({
             repoPath: repo.path,
             workspaceRoot,
             worktreePath,
@@ -2411,9 +2411,19 @@ export async function createLocalWorktree(
             refreshLocalBaseRef: settings.refreshLocalBaseRefOnWorktreeCreate,
             ...(preparedWorktreeOptions ? { options: preparedWorktreeOptions } : {})
           })
-          if (preparedResult) {
-            return preparedResult
+          timing.recordPreparedCheckout(
+            prepared.status === 'hit'
+              ? { status: 'hit', retargeted: prepared.retargeted }
+              : { status: 'miss', reason: prepared.reason }
+          )
+          if (prepared.status === 'hit') {
+            return prepared.result
           }
+        } else {
+          timing.recordPreparedCheckout({
+            status: 'miss',
+            reason: sparseDirectories.length > 0 ? 'sparse_checkout' : 'checkout_existing_branch'
+          })
         }
         if (sparseDirectories.length > 0) {
           if (checkoutExistingBranch) {
diff --git a/src/main/ipc/worktrees-local-create-flow.test.ts b/src/main/ipc/worktrees-local-create-flow.test.ts
index d01efc489da..abc711bbd9b 100644
--- a/src/main/ipc/worktrees-local-create-flow.test.ts
+++ b/src/main/ipc/worktrees-local-create-flow.test.ts
@@ -633,7 +633,10 @@ describe('registerWorktreeHandlers', () => {
     })) as {
       setup?: unknown
       startupTerminal?: { spawned: boolean; surface?: string }
-      timing?: { phases: { phase: string }[] }
+      timing?: {
+        phases: { phase: string }[]
+        preparedCheckout?: { status: string; reason?: string }
+      }
     }
     expect(createSetupRunnerScriptMock).toHaveBeenCalledWith(
       expect.objectContaining({ id: 'repo-1' }),
@@ -695,6 +698,8 @@ describe('registerWorktreeHandlers', () => {
         'spawn_startup_terminal'
       ])
     )
+    // Nothing warmed this repo, so the create must report the cold path rather than stay silent.
+    expect(result.timing?.preparedCheckout).toEqual({ status: 'miss', reason: 'none_armed' })
   })
 
   it('returns the wrapped setup command when startup spawned but setup creation failed', async () => {
diff --git a/src/main/ipc/worktrees-setup-launch-sparse-checkout.test.ts b/src/main/ipc/worktrees-setup-launch-sparse-checkout.test.ts
index 0996df03cb4..725f2df8c1f 100644
--- a/src/main/ipc/worktrees-setup-launch-sparse-checkout.test.ts
+++ b/src/main/ipc/worktrees-setup-launch-sparse-checkout.test.ts
@@ -205,14 +205,14 @@ describe('registerWorktreeHandlers', () => {
       }
     ])
 
-    const result = await handlers['worktrees:create'](null, {
+    const result = (await handlers['worktrees:create'](null, {
       repoId: 'repo-1',
       name: 'improve-dashboard',
       sparseCheckout: {
         directories: [' packages/web ', 'apps\\api\\', 'packages/web/'],
         presetId: 'preset-1'
       }
-    })
+    })) as { timing?: { preparedCheckout?: { status: string; reason?: string } } }
 
     expect(addWorktreeMock).not.toHaveBeenCalled()
     expect(addSparseWorktreeMock).toHaveBeenCalledWith(
@@ -240,6 +240,11 @@ describe('registerWorktreeHandlers', () => {
         sparsePresetId: 'preset-1'
       })
     })
+    // A sparse create can never claim a prepared checkout; say so rather than looking like a miss.
+    expect(result.timing?.preparedCheckout).toEqual({
+      status: 'miss',
+      reason: 'sparse_checkout'
+    })
   })
 
   it('retires a generated sparse name when creation rollback also fails', async () => {
diff --git a/src/main/observability/instrumentation.test.ts b/src/main/observability/instrumentation.test.ts
index 978854897e4..452b5cd155c 100644
--- a/src/main/observability/instrumentation.test.ts
+++ b/src/main/observability/instrumentation.test.ts
@@ -214,4 +214,38 @@ describe('addWorktreeCreatePhaseAttributes', () => {
     expect(attributes['worktree.create.total_ms']).toBe(500)
     expect(attributes['worktree.create.unattributed_ms']).toBe(200)
   })
+
+  it('records a prepared-checkout hit and whether it had to be retargeted', () => {
+    const { attributes, span } = capture()
+    addWorktreeCreatePhaseAttributes(span, {
+      totalDurationMs: 900,
+      phases: [{ phase: 'git_worktree_add', startedAtMs: 0, durationMs: 400 }],
+      preparedCheckout: { status: 'hit', retargeted: true }
+    })
+
+    expect(attributes['worktree.create.prepared_checkout']).toBe('hit')
+    expect(attributes['worktree.create.prepared_checkout_retargeted']).toBe(true)
+    expect(attributes['worktree.create.prepared_checkout_miss']).toBeUndefined()
+    expect(attributes['worktree.create.unattributed_ms']).toBe(500)
+  })
+
+  it('records why a create missed the prepared checkout', () => {
+    const { attributes, span } = capture()
+    addWorktreeCreatePhaseAttributes(span, {
+      totalDurationMs: 8_000,
+      phases: [],
+      preparedCheckout: { status: 'miss', reason: 'base_mismatch' }
+    })
+
+    expect(attributes['worktree.create.prepared_checkout']).toBe('miss')
+    expect(attributes['worktree.create.prepared_checkout_miss']).toBe('base_mismatch')
+    expect(attributes['worktree.create.prepared_checkout_retargeted']).toBeUndefined()
+  })
+
+  it('stays silent on paths that never consult the prepared checkout', () => {
+    const { attributes, span } = capture()
+    addWorktreeCreatePhaseAttributes(span, { totalDurationMs: 10, phases: [] })
+
+    expect(attributes['worktree.create.prepared_checkout']).toBeUndefined()
+  })
 })
diff --git a/src/main/observability/instrumentation.ts b/src/main/observability/instrumentation.ts
index fb57aa5a870..8569ab6ef04 100644
--- a/src/main/observability/instrumentation.ts
+++ b/src/main/observability/instrumentation.ts
@@ -21,6 +21,7 @@
 // itself becomes a `noopSpan` that swallows all calls — call sites do not
 // need to branch on whether tracing is on.
 
+import type { PreparedCheckoutOutcome } from '../../shared/worktree/create-types'
 import { startSpan, withSpan, type ActiveSpan } from './tracer'
 
 const GIT_FAST_SUCCESS_THRESHOLD_MS = 250
@@ -259,9 +260,25 @@ type WorktreePhaseInterval = Pick<WorktreeCreatePhaseTiming, 'startedAtMs' | 'du
  *  the recorder, so they are safe to key on; nothing here carries a branch name or a path. */
 export function addWorktreeCreatePhaseAttributes(
   span: ActiveSpan,
-  timing: { totalDurationMs: number; phases: readonly WorktreeCreatePhaseTiming[] }
+  timing: {
+    totalDurationMs: number
+    phases: readonly WorktreeCreatePhaseTiming[]
+    preparedCheckout?: PreparedCheckoutOutcome
+  }
 ): void {
   span.setAttribute('worktree.create.total_ms', Math.round(timing.totalDurationMs))
+  if (timing.preparedCheckout) {
+    span.setAttribute('worktree.create.prepared_checkout', timing.preparedCheckout.status)
+    if (timing.preparedCheckout.status === 'hit') {
+      // A retargeted hit still pays a reset, so it must not be read as a free hit.
+      span.setAttribute(
+        'worktree.create.prepared_checkout_retargeted',
+        timing.preparedCheckout.retargeted
+      )
+    } else {
+      span.setAttribute('worktree.create.prepared_checkout_miss', timing.preparedCheckout.reason)
+    }
+  }
   for (const phase of timing.phases) {
     span.setAttribute(`worktree.create.phase.${phase.phase}_ms`, Math.round(phase.durationMs))
   }
diff --git a/src/main/runtime/runtime-local-git-worktree-create.ts b/src/main/runtime/runtime-local-git-worktree-create.ts
index 528aa318cd4..9875e5a07d0 100644
--- a/src/main/runtime/runtime-local-git-worktree-create.ts
+++ b/src/main/runtime/runtime-local-git-worktree-create.ts
@@ -185,7 +185,7 @@ export async function createRuntimeLocalGitWorktree(args: {
         )) ?? {})
   let addResult: AddWorktreeResult
   try {
-    const preparedResult =
+    const preparedAttempt =
       sparseDirectories.length === 0 && !args.checkoutExistingBranch
         ? await consumePreparedWorktreeCreate({
             repoPath: args.repo.path,
@@ -197,8 +197,9 @@ export async function createRuntimeLocalGitWorktree(args: {
             ...(preparedWorktreeOptions ? { options: preparedWorktreeOptions } : {})
           })
         : null
-    if (preparedResult) {
-      addResult = preparedResult
+    // This path has no create-span recorder, so the miss reason is only observable on the IPC path.
+    if (preparedAttempt?.status === 'hit') {
+      addResult = preparedAttempt.result
     } else if (sparseDirectories.length > 0) {
       addResult =
         (await (addOptions
diff --git a/src/main/worktree-create-preparation-claim.test.ts b/src/main/worktree-create-preparation-claim.test.ts
new file mode 100644
index 00000000000..8abc42f30fe
--- /dev/null
+++ b/src/main/worktree-create-preparation-claim.test.ts
@@ -0,0 +1,152 @@
+import { describe, expect, it } from 'vitest'
+import {
+  preparationPathKey,
+  selectPreparationForCreate,
+  type PreparationCandidate,
+  type PreparationRequest
+} from './worktree-create-preparation-claim'
+
+function candidate(overrides: Partial<PreparationCandidate> = {}): PreparationCandidate {
+  return {
+    repoPathKey: '/repo',
+    workspaceRootKey: '/workspace',
+    wslDistro: '',
+    baseBranch: 'origin/main',
+    canonicalBase: 'refs/remotes/origin/main',
+    createdAt: 1_000,
+    ...overrides
+  }
+}
+
+function request(overrides: Partial<PreparationRequest> = {}): PreparationRequest {
+  return {
+    repoPathKey: '/repo',
+    workspaceRootKey: '/workspace',
+    wslDistro: '',
+    baseBranch: 'origin/main',
+    canonicalBase: 'refs/remotes/origin/main',
+    ...overrides
+  }
+}
+
+describe('selectPreparationForCreate', () => {
+  it('matches the identical base before any ref probe has run', () => {
+    const selection = selectPreparationForCreate([candidate()], request({ canonicalBase: null }))
+
+    expect(selection).toEqual({
+      kind: 'exact',
+      candidate: candidate(),
+      canonicalBase: 'refs/remotes/origin/main'
+    })
+  })
+
+  it('asks for a canonical base only when something is armed under another spelling', () => {
+    expect(
+      selectPreparationForCreate(
+        [candidate()],
+        request({ baseBranch: 'main', canonicalBase: null })
+      )
+    ).toEqual({ kind: 'needs-canonical-base' })
+    // Nothing armed for this repo, so the create must not pay a probe to learn that.
+    expect(
+      selectPreparationForCreate([], request({ baseBranch: 'main', canonicalBase: null }))
+    ).toEqual({ kind: 'miss', reason: 'none_armed' })
+  })
+
+  it('matches when the two sides spell the same ref differently', () => {
+    const selection = selectPreparationForCreate(
+      [candidate()],
+      request({ baseBranch: 'refs/remotes/origin/main' })
+    )
+
+    expect(selection).toEqual({
+      kind: 'exact',
+      candidate: candidate(),
+      canonicalBase: 'refs/remotes/origin/main'
+    })
+  })
+
+  it('retargets a local base onto the armed remote-tracking base of the same branch', () => {
+    const selection = selectPreparationForCreate(
+      [candidate()],
+      request({ baseBranch: 'main', canonicalBase: 'refs/heads/main' })
+    )
+
+    expect(selection).toEqual({
+      kind: 'retarget',
+      candidate: candidate(),
+      canonicalBase: 'refs/heads/main'
+    })
+  })
+
+  it('prefers the freshest armed entry when several share the family', () => {
+    const older = candidate({ canonicalBase: 'refs/remotes/origin/main', createdAt: 1 })
+    const newer = candidate({ canonicalBase: 'refs/remotes/upstream/main', createdAt: 2 })
+
+    const selection = selectPreparationForCreate(
+      [older, newer],
+      request({ baseBranch: 'main', canonicalBase: 'refs/heads/main' })
+    )
+
+    expect(selection).toMatchObject({ kind: 'retarget', candidate: newer })
+  })
+
+  it('refuses to retarget onto a different branch', () => {
+    const selection = selectPreparationForCreate(
+      [candidate()],
+      request({ baseBranch: 'origin/release', canonicalBase: 'refs/remotes/origin/release' })
+    )
+
+    expect(selection).toEqual({ kind: 'miss', reason: 'base_mismatch' })
+  })
+
+  it('refuses to retarget onto a bare commit id, whose divergence is unbounded', () => {
+    const selection = selectPreparationForCreate(
+      [candidate()],
+      request({ baseBranch: '1f2e3d4c5b6a7988', canonicalBase: '1f2e3d4c5b6a7988' })
+    )
+
+    expect(selection).toEqual({ kind: 'miss', reason: 'base_mismatch' })
+  })
+
+  it('names the key field that disagreed', () => {
+    expect(selectPreparationForCreate([], request())).toEqual({
+      kind: 'miss',
+      reason: 'none_armed'
+    })
+    // Something is warm, just not for this repo — the shape of a size-cap eviction.
+    expect(
+      selectPreparationForCreate([candidate()], request({ repoPathKey: '/other-repo' }))
+    ).toEqual({ kind: 'miss', reason: 'repo_mismatch' })
+    expect(selectPreparationForCreate([candidate()], request({ wslDistro: 'Ubuntu' }))).toEqual({
+      kind: 'miss',
+      reason: 'wsl_distro_mismatch'
+    })
+    expect(
+      selectPreparationForCreate([candidate()], request({ workspaceRootKey: '/other' }))
+    ).toEqual({ kind: 'miss', reason: 'workspace_root_mismatch' })
+  })
+
+  it('never crosses hosts to satisfy a family retarget', () => {
+    const selection = selectPreparationForCreate(
+      [candidate({ wslDistro: 'Ubuntu' })],
+      request({ baseBranch: 'main', canonicalBase: 'refs/heads/main' })
+    )
+
+    expect(selection).toEqual({ kind: 'miss', reason: 'wsl_distro_mismatch' })
+  })
+})
+
+describe('preparationPathKey', () => {
+  it('normalizes a posix path without folding case', () => {
+    expect(preparationPathKey('/workspace/./repo/')).toBe('/workspace/repo/')
+    expect(preparationPathKey('/Workspace/Repo')).toBe('/Workspace/Repo')
+  })
+
+  it('folds case for Windows drive and UNC paths, which compare case-insensitively', () => {
+    expect(preparationPathKey('C:\\Workspace\\Repo')).toBe('c:\\workspace\\repo')
+    expect(preparationPathKey('\\\\wsl.localhost\\Ubuntu\\home\\jin')).toBe(
+      '\\\\wsl.localhost\\ubuntu\\home\\jin'
+    )
+  })
+})
diff --git a/src/main/worktree-create-preparation-claim.ts b/src/main/worktree-create-preparation-claim.ts
new file mode 100644
index 00000000000..e329282982d
--- /dev/null
+++ b/src/main/worktree-create-preparation-claim.ts
@@ -0,0 +1,130 @@
+import { posix, win32 } from 'node:path'
+import { isWindowsAbsolutePathLike } from '../shared/cross-platform-path'
+import { worktreeBaseRefFamily } from '../shared/worktree/base-ref'
+import type { PreparedCheckoutMissReason } from '../shared/worktree/create-types'
+
+/** The subset of miss reasons this selection can produce; the rest are decided by the caller
+ *  (sparse/existing-branch skips) or by the finalize step. */
+export type PreparationSelectionMissReason = Extract<
+  PreparedCheckoutMissReason,
+  | 'none_armed'
+  | 'repo_mismatch'
+  | 'base_mismatch'
+  | 'workspace_root_mismatch'
+  | 'wsl_distro_mismatch'
+>
+
+export type PreparationCandidate = {
+  repoPathKey: string
+  workspaceRootKey: string
+  wslDistro: string
+  /** The base exactly as the prefetch handler armed it. */
+  baseBranch: string
+  /** That base after `resolveWorktreeAddBaseRef`, so `main` and `refs/heads/main` compare equal. */
+  canonicalBase: string
+  createdAt: number
+}
+
+export type PreparationRequest = {
+  repoPathKey: string
+  workspaceRootKey: string
+  wslDistro: string
+  baseBranch: string
+  /** `null` until the caller has paid the ref probe. A raw-base match resolves without it, so the
+   *  common hit spawns no git at all. */
+  canonicalBase: string | null
+}
+
+/** Case-folded on Windows, so the arming and claiming sides key on the same path. */
+export function preparationPathKey(path: string): string {
+  if (isWindowsAbsolutePathLike(path)) {
+    return win32.normalize(path).toLowerCase()
+  }
+  return posix.normalize(path)
+}
+
+/** Keyed on the canonical base so the prefetch and the create agree when they spell the same ref
+ *  differently; a genuinely different ref still gets its own entry. */
+export function preparationEntryKey(
+  repoPathKey: string,
+  workspaceRootKey: string,
+  canonicalBase: string,
+  wslDistro: string
+): string {
+  return `${repoPathKey}\0${workspaceRootKey}\0${canonicalBase}\0${wslDistro}`
+}
+
+export type PreparationSelection<T> =
+  /** `canonicalBase` is echoed back so the caller can re-arm on the create's own base without
+   *  paying the ref probe a second time. */
+  | { kind: 'exact'; candidate: T; canonicalBase: string }
+  | { kind: 'retarget'; candidate: T; canonicalBase: string }
+  /** Something is armed for this repo but not under this raw base; only a resolved canonical base
+   *  can decide between a hit and a miss. */
+  | { kind: 'needs-canonical-base' }
+  | { kind: 'miss'; reason: PreparationSelectionMissReason }
+
+/**
+ * Picks the armed preparation a create may claim.
+ *
+ * The two sides of the pool disagree in practice — the prefetch arms `origin/main` while the
+ * create resolves `main`, or vice versa — and an exact-string key turns every such disagreement
+ * into a silent cold create. Canonicalizing catches the spelling differences; the base-family
+ * retarget catches the local-vs-remote-tracking ones, where finalize's existing drift reset lands
+ * the checkout on the requested commit for far less than a cold add plus a full materialize.
+ *
+ * The bound matters: refs outside the same branch family are rejected, because a retarget across
+ * unrelated history degenerates into a full checkout and wins nothing.
+ *
+ * Synchronous on purpose: the caller claims the returned entry in the same run, so two concurrent
+ * creates cannot both walk away with the same prepared checkout.
+ */
+export function selectPreparationForCreate<T extends PreparationCandidate>(
+  candidates: readonly T[],
+  request: PreparationRequest
+): PreparationSelection<T> {
+  if (candidates.length === 0) {
+    return { kind: 'miss', reason: 'none_armed' }
+  }
+  const sameRepo = candidates.filter((candidate) => candidate.repoPathKey === request.repoPathKey)
+  if (sameRepo.length === 0) {
+    // Separate from `none_armed`: this is what a size-cap eviction looks like from the create side.
+    return { kind: 'miss', reason: 'repo_mismatch' }
+  }
+  // Distro before root: the distro decides which filesystem the root is even on.
+  const sameHost = sameRepo.filter((candidate) => candidate.wslDistro === request.wslDistro)
+  if (sameHost.length === 0) {
+    return { kind: 'miss', reason: 'wsl_distro_mismatch' }
+  }
+  const sameRoot = sameHost.filter(
+    (candidate) => candidate.workspaceRootKey === request.workspaceRootKey
+  )
+  if (sameRoot.length === 0) {
+    return { kind: 'miss', reason: 'workspace_root_mismatch' }
+  }
+
+  const { canonicalBase } = request
+  if (canonicalBase === null) {
+    const rawMatch = sameRoot.find((candidate) => candidate.baseBranch === request.baseBranch)
+    // Same spelling, so the armed entry already holds this request's canonical form.
+    return rawMatch
+      ? { kind: 'exact', candidate: rawMatch, canonicalBase: rawMatch.canonicalBase }
+      : { kind: 'needs-canonical-base' }
+  }
+
+  const canonicalMatch = sameRoot.find((candidate) => candidate.canonicalBase === canonicalBase)
+  if (canonicalMatch) {
+    return { kind: 'exact', candidate: canonicalMatch, canonicalBase }
+  }
+
+  const family = worktreeBaseRefFamily(canonicalBase)
+  if (family) {
+    const retarget = sameRoot
+      .filter((candidate) => worktreeBaseRefFamily(candidate.canonicalBase) === family)
+      .sort((left, right) => right.createdAt - left.createdAt)[0]
+    if (retarget) {
+      return { kind: 'retarget', candidate: retarget, canonicalBase }
+    }
+  }
+  return { kind: 'miss', reason: 'base_mismatch' }
+}
diff --git a/src/main/worktree-create-preparation-pool.ts b/src/main/worktree-create-preparation-pool.ts
new file mode 100644
index 00000000000..26ee1c41aad
--- /dev/null
+++ b/src/main/worktree-create-preparation-pool.ts
@@ -0,0 +1,210 @@
+import { randomUUID } from 'node:crypto'
+import { mkdir } from 'node:fs/promises'
+import { posix, win32 } from 'node:path'
+import { isWindowsAbsolutePathLike } from '../shared/cross-platform-path'
+import {
+  WORKTREE_CREATE_PREPARATION_DIRECTORY,
+  createWorktreePreparationLockReason
+} from '../shared/worktree/create-preparation'
+import type { AddWorktreeOptions } from './git/worktree'
+import { prepareWorktreeCreateCheckout } from './git/worktree-create-preparation'
+import { toHostFilesystemPath } from './host-tree-removal'
+import { preparationEntryKey, preparationPathKey } from './worktree-create-preparation-claim'
+import {
+  cleanupStalePreparations,
+  hasPendingStalePreparationCleanup,
+  resetStalePreparationCleanupForTests
+} from './worktree-create-preparation-stale-cleanup'
+import {
+  discardPreparationWithRetry,
+  resetPendingPreparationDiscardsForTests,
+  trackPreparationDiscard
+} from './worktree-preparation-discard-retry'
+
+export const WORKTREE_CREATE_PREPARATION_TTL_MS = 5 * 60_000
+export const WORKTREE_CREATE_PREPARATION_LIMIT = 3
+
+export type PreparationEntry = {
+  key: string
+  repoPath: string
+  repoPathKey: string
+  workspaceRoot: string
+  workspaceRootKey: string
+  wslDistro: string
+  baseBranch: string
+  canonicalBase: string
+  preparedPath: string
+  options: AddWorktreeOptions
+  createdAt: number
+  ready: Promise<void>
+  expiration: NodeJS.Timeout
+}
+
+export type StartPreparationArgs = {
+  repoPath: string
+  workspaceRoot: string
+  baseBranch: string
+  canonicalBase: string
+  options: AddWorktreeOptions
+}
+
+const preparations = new Map<string, PreparationEntry>()
+
+/** One repo on one Git host: the scope a stranded discard is retried under. */
+function preparationHostKey(repoPathKey: string, wslDistro: string): string {
+  return `${repoPathKey}\0${wslDistro}`
+}
+
+/** A prepared checkout is a create that is either in flight or imminent. */
+export function hasPendingPreparations(): boolean {
+  return preparations.size > 0 || hasPendingStalePreparationCleanup()
+}
+
+function pathOps(path: string): Pick<typeof posix, 'dirname' | 'join'> {
+  return isWindowsAbsolutePathLike(path) ? win32 : posix
+}
+
+async function discardEntry(entry: PreparationEntry): Promise<void> {
+  // A failed checkout self-discards, but that self-discard is best-effort too, so it can strand the
+  // registration for the same reason the discard here can. Enrol either way.
+  await entry.ready.catch(() => {})
+  await discardPreparationWithRetry({
+    hostKey: preparationHostKey(entry.repoPathKey, entry.wslDistro),
+    repoPath: entry.repoPath,
+    preparedPath: entry.preparedPath,
+    options: entry.options
+  })
+}
+
+function discardEntryInBackground(entry: PreparationEntry): void {
+  // Tracked, not bare `void`: the test reset must be able to settle it before dropping the registry.
+  trackPreparationDiscard(discardEntry(entry))
+}
+
+function expireEntry(entry: PreparationEntry): void {
+  if (preparations.get(entry.key) !== entry) {
+    return
+  }
+  preparations.delete(entry.key)
+  discardEntryInBackground(entry)
+}
+
+/**
+ * Frees a slot for an incoming preparation, preferring one the same workspace already owns.
+ *
+ * The cap is a disk bound — a prepared checkout is a full tree, ~200 MB of tracked content in the
+ * repo this was measured against — so it stays small. But flipping through the composer's base
+ * picker arms several preparations for one repo, and a plain oldest-first eviction let that churn
+ * throw away another project's warm checkout, which is a structural miss for anyone working across
+ * several repos. Evict the incoming workspace's own oldest entry first; only reach across
+ * workspaces when this one holds none.
+ */
+function enforcePreparationLimit(
+  repoPathKey: string,
+  workspaceRootKey: string,
+  wslDistro: string
+): void {
+  while (preparations.size >= WORKTREE_CREATE_PREPARATION_LIMIT) {
+    const byAge = [...preparations.values()].sort((left, right) => left.createdAt - right.createdAt)
+    const victim =
+      byAge.find(
+        (entry) =>
+          entry.repoPathKey === repoPathKey &&
+          entry.workspaceRootKey === workspaceRootKey &&
+          entry.wslDistro === wslDistro
+      ) ?? byAge[0]
+    if (!victim) {
+      return
+    }
+    preparations.delete(victim.key)
+    clearTimeout(victim.expiration)
+    discardEntryInBackground(victim)
+  }
+}
+
+export function listPreparations(): PreparationEntry[] {
+  return [...preparations.values()]
+}
+
+export function findPreparation(
+  repoPathKey: string,
+  workspaceRootKey: string,
+  canonicalBase: string,
+  wslDistro: string
+): PreparationEntry | undefined {
+  return preparations.get(
+    preparationEntryKey(repoPathKey, workspaceRootKey, canonicalBase, wslDistro)
+  )
+}
+
+/** Removes an entry from the pool so no other create can claim it. Callers must run this in the
+ *  same synchronous turn as the selection that produced `entry`. */
+export function takePreparation(entry: PreparationEntry): void {
+  preparations.delete(entry.key)
+  clearTimeout(entry.expiration)
+}
+
+export function startPreparation({
+  repoPath,
+  workspaceRoot,
+  baseBranch,
+  canonicalBase,
+  options
+}: StartPreparationArgs): Promise<void> {
+  const repoPathKey = preparationPathKey(repoPath)
+  const workspaceRootKey = preparationPathKey(workspaceRoot)
+  const wslDistro = options.wslDistro ?? ''
+  const key = preparationEntryKey(repoPathKey, workspaceRootKey, canonicalBase, wslDistro)
+  enforcePreparationLimit(repoPathKey, workspaceRootKey, wslDistro)
+  const preparationId = `${process.pid}-${randomUUID()}`
+  const lockReason = createWorktreePreparationLockReason(preparationId)
+  const preparationRoot = pathOps(workspaceRoot).join(
+    workspaceRoot,
+    WORKTREE_CREATE_PREPARATION_DIRECTORY
+  )
+  const preparedPath = pathOps(workspaceRoot).join(preparationRoot, preparationId)
+  const entry = {} as PreparationEntry
+  const expiration = setTimeout(() => expireEntry(entry), WORKTREE_CREATE_PREPARATION_TTL_MS)
+  expiration.unref()
+  Object.assign(entry, {
+    key,
+    repoPath,
+    repoPathKey,
+    workspaceRoot,
+    workspaceRootKey,
+    wslDistro,
+    baseBranch,
+    canonicalBase,
+    preparedPath,
+    options,
+    createdAt: Date.now(),
+    expiration,
+    ready: (async () => {
+      await cleanupStalePreparations(preparationHostKey(repoPathKey, wslDistro), repoPath, options)
+      await mkdir(toHostFilesystemPath(preparationRoot), { recursive: true })
+      // Already canonical, so the add re-resolves nothing.
+      await prepareWorktreeCreateCheckout(repoPath, preparedPath, canonicalBase, lockReason, options)
+    })()
+  } satisfies PreparationEntry)
+  preparations.set(key, entry)
+  void entry.ready.catch(() => {
+    if (preparations.get(key) === entry) {
+      preparations.delete(key)
+      clearTimeout(entry.expiration)
+    }
+  })
+  return entry.ready
+}
+
+export async function _resetPreparationPoolForTests(): Promise<void> {
+  const entries = [...preparations.values()]
+  preparations.clear()
+  resetStalePreparationCleanupForTests()
+  await Promise.all(
+    entries.map(async (entry) => {
+      clearTimeout(entry.expiration)
+      await discardEntry(entry)
+    })
+  )
+  await resetPendingPreparationDiscardsForTests()
+}
diff --git a/src/main/worktree-create-preparation-wsl-root.test.ts b/src/main/worktree-create-preparation-wsl-root.test.ts
index f0c8e664298..2c752b74a80 100644
--- a/src/main/worktree-create-preparation-wsl-root.test.ts
+++ b/src/main/worktree-create-preparation-wsl-root.test.ts
@@ -16,7 +16,8 @@ const mocks = vi.hoisted(() => ({
   getWorktreeOptions: vi.fn(),
   getMirrorDistro: vi.fn(),
   getWslHome: vi.fn(),
-  getWslHomeAsync: vi.fn()
+  getWslHomeAsync: vi.fn(),
+  resolveBaseRef: vi.fn()
 }))
 
 vi.mock('node:fs/promises', () => ({ mkdir: mocks.mkdir }))
@@ -27,6 +28,9 @@ vi.mock('./git/worktree-create-preparation', () => ({
   discardPreparedWorktree: mocks.discard,
   unlockPreparedWorktree: mocks.unlock
 }))
+vi.mock('./git/worktree-base-ref-probe', () => ({
+  resolveLocalWorktreeBaseRef: mocks.resolveBaseRef
+}))
 vi.mock('./project-runtime-git-options', () => ({
   getLocalProjectWorktreeGitOptions: mocks.getWorktreeOptions,
   getWorktreeMirrorDistro: mocks.getMirrorDistro
@@ -86,6 +90,9 @@ beforeEach(() => {
     throw new Error('the blocking wsl.exe home probe must not run while preparing')
   })
   mocks.getWslHomeAsync.mockReset().mockResolvedValue(WSL_HOME)
+  mocks.resolveBaseRef
+    .mockReset()
+    .mockImplementation(async (_repoPath: string, baseRef: string) => `refs/remotes/${baseRef}`)
 })
 
 afterEach(async () => {
diff --git a/src/main/worktree-create-preparation.test.ts b/src/main/worktree-create-preparation.test.ts
index eae3b59081f..06818fec422 100644
--- a/src/main/worktree-create-preparation.test.ts
+++ b/src/main/worktree-create-preparation.test.ts
@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import type { Store } from './persistence'
 import type { Repo } from '../shared/repo-types'
 import { WORKTREE_CREATE_PREPARATION_DIRECTORY } from '../shared/worktree/create-preparation'
+import { resolveWorktreeAddBaseRef } from '../shared/worktree/base-ref'
 
 const mocks = vi.hoisted(() => ({
   mkdir: vi.fn(),
@@ -12,7 +13,9 @@ const mocks = vi.hoisted(() => ({
   unlock: vi.fn(),
   getWorktreeOptions: vi.fn(),
   computeWorkspaceRoot: vi.fn(),
-  computeWorkspaceRootAsync: vi.fn()
+  computeWorkspaceRootAsync: vi.fn(),
+  resolveBaseRef: vi.fn(),
+  measureDivergence: vi.fn()
 }))
 
 vi.mock('node:fs/promises', () => ({ mkdir: mocks.mkdir }))
@@ -23,6 +26,12 @@ vi.mock('./git/worktree-create-preparation', () => ({
   discardPreparedWorktree: mocks.discard,
   unlockPreparedWorktree: mocks.unlock
 }))
+vi.mock('./git/worktree-base-ref-probe', () => ({
+  resolveLocalWorktreeBaseRef: mocks.resolveBaseRef
+}))
+vi.mock('./git/worktree-base-divergence', () => ({
+  measureRetargetDivergence: mocks.measureDivergence
+}))
 vi.mock('./project-runtime-git-options', () => ({
   getLocalProjectWorktreeGitOptions: mocks.getWorktreeOptions,
   getWorktreeMirrorDistro: () => undefined
@@ -48,6 +57,11 @@ function flushBackgroundWork(ms = 0): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms))
 }
 
+const EXISTING_REFS = new Set([
+  'refs/heads/main',
+  'refs/remotes/origin/main',
+  'refs/remotes/origin/release'
+])
 const repo = { id: 'repo-1', path: '/repo' } as Repo
 const store = { getSettings: () => ({}) } as unknown as Store
 
@@ -59,6 +73,12 @@ beforeEach(() => {
   mocks.discard.mockReset().mockResolvedValue(undefined)
   mocks.unlock.mockReset().mockResolvedValue(undefined)
   mocks.getWorktreeOptions.mockReset().mockReturnValue({})
+  mocks.measureDivergence.mockReset().mockResolvedValue('within')
+  mocks.resolveBaseRef
+    .mockReset()
+    .mockImplementation((_repoPath: string, baseRef: string) =>
+      resolveWorktreeAddBaseRef(baseRef, async (candidate) => EXISTING_REFS.has(candidate))
+    )
   mocks.computeWorkspaceRoot.mockReset().mockImplementation(() => {
     throw new Error('synchronous workspace-root lookup must not run on the main thread')
   })
@@ -135,7 +155,7 @@ describe('worktree create preparation registry', () => {
     expect(mocks.prepareCheckout).toHaveBeenCalledTimes(1)
   })
 
-  it('does not claim a preparation after the selected base changes', async () => {
+  it('does not claim a preparation after the selected base changes to another branch', async () => {
     await prepareWorktreeCreateForRepo(store, repo, 'origin/main')
 
     await expect(
@@ -146,10 +166,185 @@ describe('worktree create preparation registry', () => {
         branch: 'feature/test',
         baseBranch: 'origin/release'
       })
-    ).resolves.toBeNull()
+    ).resolves.toEqual({ status: 'miss', reason: 'base_mismatch' })
     expect(mocks.finalize).not.toHaveBeenCalled()
   })
 
+  it('claims across the local/remote spelling of the same base and reports the retarget', async () => {
+    await prepareWorktreeCreateForRepo(store, repo, 'origin/main')
+
+    // `main` has no local ref here, so the canonical forms differ and only the base family matches.
+    await expect(
+      consumePreparedWorktreeCreate({
+        repoPath: repo.path,
+        workspaceRoot: '/workspace',
+        worktreePath: '/workspace/final',
+        branch: 'feature/test',
+        baseBranch: 'main'
+      })
+    ).resolves.toEqual({ status: 'hit', retargeted: true, result: {} })
+    // Finalize still receives the requested base, so it resets onto the requested commit.
+    expect(mocks.finalize).toHaveBeenCalledWith(
+      repo.path,
+      expect.any(String),
+      '/workspace/final',
+      'feature/test',
+      'main',
+      undefined,
+      {}
+    )
+  })
+
+  it('refuses a same-family retarget whose bases have drifted too far apart', async () => {
+    await prepareWorktreeCreateForRepo(store, repo, 'origin/main')
+    // An abandoned fork's `main` is the same base family but a whole-tree checkout away.
+    mocks.measureDivergence.mockResolvedValue('exceeded')
+
+    await expect(
+      consumePreparedWorktreeCreate({
+        repoPath: repo.path,
+        workspaceRoot: '/workspace',
+        worktreePath: '/workspace/final',
+        branch: 'feature/test',
+        baseBranch: 'main'
+      })
+    ).resolves.toEqual({ status: 'miss', reason: 'retarget_too_divergent' })
+    expect(mocks.finalize).not.toHaveBeenCalled()
+    // The preparation is left armed for the base it actually holds.
+    expect(mocks.discard).not.toHaveBeenCalled()
+  })
+
+  it('separates a drift check that said no from one that could not answer', async () => {
+    await prepareWorktreeCreateForRepo(store, repo, 'origin/main')
+    // A timed-out or aborted walk skipped a retarget that may well have been cheap; that is a
+    // tuning signal, not the bound working as intended, so it must not report as excess drift.
+    mocks.measureDivergence.mockResolvedValue('unknown')
+
+    await expect(
+      consumePreparedWorktreeCreate({
+        repoPath: repo.path,
+        workspaceRoot: '/workspace',
+        worktreePath: '/workspace/final',
+        branch: 'feature/test',
+        baseBranch: 'main'
+      })
+    ).resolves.toEqual({ status: 'miss', reason: 'retarget_unverifiable' })
+    expect(mocks.finalize).not.toHaveBeenCalled()
+    expect(mocks.discard).not.toHaveBeenCalled()
+  })
+
+  it('does not spend a divergence walk when the base matches exactly', async () => {
+    await prepareWorktreeCreateForRepo(store, repo, 'origin/main')
+
+    await consumePreparedWorktreeCreate({
+      repoPath: repo.path,
+      workspaceRoot: '/workspace',
+      worktreePath: '/workspace/final',
+      branch: 'feature/test',
+      baseBranch: 'origin/main'
+    })
+
+    expect(mocks.measureDivergence).not.toHaveBeenCalled()
+  })
+
+  it('claims when the two sides spell the same ref differently', async () => {
+    await prepareWorktreeCreateForRepo(store, repo, 'origin/main')
+
+    await expect(
+      consumePreparedWorktreeCreate({
+        repoPath: repo.path,
+        workspaceRoot: '/workspace',
+        worktreePath: '/workspace/final',
+        branch: 'feature/test',
+        baseBranch: 'refs/remotes/origin/main'
+      })
+    ).resolves.toEqual({ status: 'hit', retargeted: false, result: {} })
+  })
+
+  it('never hands the same prepared checkout to two concurrent creates', async () => {
+    await prepareWorktreeCreateForRepo(store, repo, 'origin/main')
+
+    // `main` needs the ref probe, so the claim has to await mid-flight — the window where a
+    // second create could otherwise walk away with the same preparation.
+    const [first, second] = await Promise.all([
+      consumePreparedWorktreeCreate({
+        repoPath: repo.path,
+        workspaceRoot: '/workspace',
+        worktreePath: '/workspace/first',
+        branch: 'feature/first',
+        baseBranch: 'main'
+      }),
+      consumePreparedWorktreeCreate({
+        repoPath: repo.path,
+        workspaceRoot: '/workspace',
+        worktreePath: '/workspace/second',
+        branch: 'feature/second',
+        baseBranch: 'main'
+      })
+    ])
+
+    expect([first.status, second.status]).toContain('hit')
+    const preparedPaths = mocks.finalize.mock.calls.map((call) => call[1])
+    expect(new Set(preparedPaths).size).toBe(preparedPaths.length)
+  })
+
+  it('reports which part of the claim key disagreed', async () => {
+    await prepareWorktreeCreateForRepo(store, repo, 'origin/main')
+
+    await expect(
+      consumePreparedWorktreeCreate({
+        repoPath: repo.path,
+        workspaceRoot: '/other-workspace',
+        worktreePath: '/other-workspace/final',
+        branch: 'feature/test',
+        baseBranch: 'origin/main'
+      })
+    ).resolves.toEqual({ status: 'miss', reason: 'workspace_root_mismatch' })
+
+    await expect(
+      consumePreparedWorktreeCreate({
+        repoPath: repo.path,
+        workspaceRoot: '/workspace',
+        worktreePath: '/workspace/final',
+        branch: 'feature/test',
+        baseBranch: 'origin/main',
+        options: { wslDistro: 'Ubuntu' }
+      })
+    ).resolves.toEqual({ status: 'miss', reason: 'wsl_distro_mismatch' })
+
+    await expect(
+      consumePreparedWorktreeCreate({
+        repoPath: '/other-repo',
+        workspaceRoot: '/workspace',
+        worktreePath: '/workspace/final',
+        branch: 'feature/test',
+        baseBranch: 'origin/main'
+      })
+    ).resolves.toEqual({ status: 'miss', reason: 'repo_mismatch' })
+    expect(mocks.finalize).not.toHaveBeenCalled()
+  })
+
+  it("evicts a repo's own stale preparation before another repo's", async () => {
+    const otherRepo = { id: 'repo-2', path: '/other-repo' } as Repo
+    await prepareWorktreeCreateForRepo(store, otherRepo, 'origin/main')
+    // Fill the pool from one repo, as flipping the composer's base picker does, until the next
+    // arm has to evict something.
+    await prepareWorktreeCreateForRepo(store, repo, 'origin/main')
+    await prepareWorktreeCreateForRepo(store, repo, 'origin/release')
+    await prepareWorktreeCreateForRepo(store, repo, 'main')
+
+    // The eviction must cost `repo` a slot, not `otherRepo` its warm checkout.
+    await expect(
+      consumePreparedWorktreeCreate({
+        repoPath: otherRepo.path,
+        workspaceRoot: '/workspace',
+        worktreePath: '/workspace/other',
+        branch: 'feature/other',
+        baseBranch: 'origin/main'
+      })
+    ).resolves.toMatchObject({ status: 'hit' })
+  })
+
   it('routes preparation and finalization through the selected WSL runtime', async () => {
     const options = { wslDistro: 'Ubuntu' }
     mocks.getWorktreeOptions.mockReturnValue(options)
@@ -167,7 +362,7 @@ describe('worktree create preparation registry', () => {
     expect(mocks.prepareCheckout).toHaveBeenCalledWith(
       repo.path,
       expect.any(String),
-      'origin/main',
+      'refs/remotes/origin/main',
       expect.any(String),
       options
     )
@@ -247,6 +442,76 @@ describe('worktree create preparation registry', () => {
     )
   })
 
+  it('cleans up and reports a finalize miss so normal add can run', async () => {
+    await prepareWorktreeCreateForRepo(store, repo, 'origin/main')
+    mocks.finalize.mockRejectedValueOnce(new Error('submodules prevent worktree move'))
+
+    await expect(
+      consumePreparedWorktreeCreate({
+        repoPath: repo.path,
+        workspaceRoot: '/workspace',
+        worktreePath: '/workspace/final',
+        branch: 'feature/test',
+        baseBranch: 'origin/main'
+      })
+    ).resolves.toEqual({ status: 'miss', reason: 'finalize_failed' })
+    expect(mocks.mkdir).toHaveBeenCalledWith('/workspace', { recursive: true })
+    expect(mocks.discard).toHaveBeenCalledTimes(1)
+  })
+
+  async function consumeOnce(name: string): Promise<void> {
+    await consumePreparedWorktreeCreate({
+      repoPath: repo.path,
+      workspaceRoot: '/workspace',
+      worktreePath: `/workspace/${name}`,
+      branch: `feature/${name}`,
+      baseBranch: 'origin/main'
+    })
+  }
+
+  it('does not re-arm after an isolated create', async () => {
+    await prepareWorktreeCreateForRepo(store, repo, 'origin/main')
+    await consumeOnce('only')
+
+    // Why: a lone create would otherwise leave a full spare checkout on disk for the whole TTL.
+    expect(mocks.prepareCheckout).toHaveBeenCalledTimes(1)
+  })
+
+  it('re-arms a preparation once creates arrive in a burst', async () => {
+    await prepareWorktreeCreateForRepo(store, repo, 'origin/main')
+    await consumeOnce('first')
+    expect(mocks.prepareCheckout).toHaveBeenCalledTimes(1)
+
+    await prepareWorktreeCreateForRepo(store, repo, 'origin/main')
+    await consumeOnce('second')
+    await prepareWorktreeCreateForRepo(store, repo, 'origin/main')
+
+    expect(mocks.prepareCheckout).toHaveBeenCalledTimes(3)
+    // The replacement is claimable, so a third create still skips the cold add.
+    await expect(
+      consumePreparedWorktreeCreate({
+        repoPath: repo.path,
+        workspaceRoot: '/workspace',
+        worktreePath: '/workspace/third',
+        branch: 'feature/third',
+        baseBranch: 'origin/main'
+      })
+    ).resolves.toEqual({ status: 'hit', retargeted: false, result: {} })
+    expect(mocks.finalize).toHaveBeenCalledTimes(3)
+  })
+
+  it('does not re-arm when finalization failed', async () => {
+    await prepareWorktreeCreateForRepo(store, repo, 'origin/main')
+    await consumeOnce('first')
+    await prepareWorktreeCreateForRepo(store, repo, 'origin/main')
+    mocks.prepareCheckout.mockClear()
+    mocks.finalize.mockRejectedValueOnce(new Error('submodules prevent worktree move'))
+
+    await consumeOnce('second')
+
+    expect(mocks.prepareCheckout).not.toHaveBeenCalled()
+  })
+
   it('retries a discard that failed while this process is still alive', async () => {
     await prepareWorktreeCreateForRepo(store, repo, 'origin/main')
     const leakedPath = mocks.prepareCheckout.mock.calls[0][1] as string
@@ -286,10 +551,14 @@ describe('worktree create preparation registry', () => {
     unremovable.add(leakedHere)
     unremovable.add(leakedElsewhere)
 
-    // Evict both, oldest first, so each host has one recorded discard failure.
-    for (const base of ['origin/one', 'origin/two', 'origin/three']) {
+    // Evict through each host's own arming: eviction prefers the incoming workspace's oldest
+    // entry, so preparing for `repo` no longer reaches across and takes `otherRepo`'s.
+    for (const base of ['origin/one', 'origin/two']) {
       await prepareWorktreeCreateForRepo(store, repo, base)
     }
+    for (const base of ['origin/one', 'origin/two']) {
+      await prepareWorktreeCreateForRepo(store, otherRepo, base)
+    }
     await flushBackgroundWork()
     expect(mocks.discard).toHaveBeenCalledWith(repo.path, leakedHere, {})
     expect(mocks.discard).toHaveBeenCalledWith(otherRepo.path, leakedElsewhere, {})
@@ -379,11 +648,15 @@ describe('worktree create preparation registry', () => {
     unremovable.add(leakedOnUbuntu)
     unremovable.add(leakedOnDebian)
 
-    // Evict both, oldest first, so each distro has one recorded discard failure.
+    // Evict through each distro's own arming: the eviction scope includes the distro, so arming
+    // under Ubuntu no longer reaches across and takes the Debian entry.
     mocks.getWorktreeOptions.mockReturnValue({ wslDistro: 'Ubuntu' })
-    for (const base of ['origin/one', 'origin/two', 'origin/three']) {
+    for (const base of ['origin/one', 'origin/two']) {
       await prepareWorktreeCreateForRepo(store, repo, base)
     }
+    mocks.getWorktreeOptions.mockReturnValue({ wslDistro: 'Debian' })
+    await prepareWorktreeCreateForRepo(store, repo, 'origin/one')
+    mocks.getWorktreeOptions.mockReturnValue({ wslDistro: 'Ubuntu' })
     await flushBackgroundWork()
     expect(mocks.discard).toHaveBeenCalledWith(repo.path, leakedOnUbuntu, { wslDistro: 'Ubuntu' })
     expect(mocks.discard).toHaveBeenCalledWith(repo.path, leakedOnDebian, { wslDistro: 'Debian' })
@@ -451,33 +724,6 @@ describe('worktree create preparation registry', () => {
     expect(mocks.discard).not.toHaveBeenCalledWith(repo.path, leakedPath, {})
   })
 
-  it('cleans up and returns null so normal add can run when finalization fails', async () => {
-    await prepareWorktreeCreateForRepo(store, repo, 'origin/main')
-    mocks.finalize.mockRejectedValueOnce(new Error('submodules prevent worktree move'))
-
-    await expect(
-      consumePreparedWorktreeCreate({
-        repoPath: repo.path,
-        workspaceRoot: '/workspace',
-        worktreePath: '/workspace/final',
-        branch: 'feature/test',
-        baseBranch: 'origin/main'
-      })
-    ).resolves.toBeNull()
-    expect(mocks.mkdir).toHaveBeenCalledWith('/workspace', { recursive: true })
-    expect(mocks.discard).toHaveBeenCalledTimes(1)
-  })
-
-  function consumeOnce(name: string): ReturnType<typeof consumePreparedWorktreeCreate> {
-    return consumePreparedWorktreeCreate({
-      repoPath: repo.path,
-      workspaceRoot: '/workspace',
-      worktreePath: `/workspace/${name}`,
-      branch: `feature/${name}`,
-      baseBranch: 'origin/main'
-    })
-  }
-
   it('reports a pending create while a stale-cleanup scan is running', async () => {
     let releaseListing!: () => void
     mocks.listWorktreeGraph.mockReturnValueOnce(
@@ -498,41 +744,4 @@ describe('worktree create preparation registry', () => {
     releaseListing()
     await arming
   })
-
-  it('does not re-arm after an isolated create', async () => {
-    await prepareWorktreeCreateForRepo(store, repo, 'origin/main')
-    await expect(consumeOnce('only')).resolves.toEqual({})
-
-    // Why: a lone create would otherwise leave a full spare checkout on disk for the whole TTL.
-    expect(mocks.prepareCheckout).toHaveBeenCalledTimes(1)
-  })
-
-  it('re-arms a preparation once creates arrive in a burst', async () => {
-    await prepareWorktreeCreateForRepo(store, repo, 'origin/main')
-    await expect(consumeOnce('first')).resolves.toEqual({})
-    expect(mocks.prepareCheckout).toHaveBeenCalledTimes(1)
-
-    await prepareWorktreeCreateForRepo(store, repo, 'origin/main')
-    expect(mocks.prepareCheckout).toHaveBeenCalledTimes(2)
-
-    // No arming call follows this consume: the third checkout can only come from the re-arm.
-    await expect(consumeOnce('second')).resolves.toEqual({})
-    expect(mocks.prepareCheckout).toHaveBeenCalledTimes(3)
-
-    // The replacement is claimable, so a third create still skips the cold add.
-    await expect(consumeOnce('third')).resolves.toEqual({})
-    expect(mocks.finalize).toHaveBeenCalledTimes(3)
-  })
-
-  it('does not re-arm when finalization failed', async () => {
-    await prepareWorktreeCreateForRepo(store, repo, 'origin/main')
-    await expect(consumeOnce('first')).resolves.toEqual({})
-    await prepareWorktreeCreateForRepo(store, repo, 'origin/main')
-    mocks.prepareCheckout.mockClear()
-    mocks.finalize.mockRejectedValueOnce(new Error('submodules prevent worktree move'))
-
-    await expect(consumeOnce('second')).resolves.toBeNull()
-
-    expect(mocks.prepareCheckout).not.toHaveBeenCalled()
-  })
 })
diff --git a/src/main/worktree-create-preparation.ts b/src/main/worktree-create-preparation.ts
index 8ddb2a5e69c..b13916194ca 100644
--- a/src/main/worktree-create-preparation.ts
+++ b/src/main/worktree-create-preparation.ts
@@ -1,19 +1,26 @@
-import { randomUUID } from 'node:crypto'
 import { mkdir } from 'node:fs/promises'
 import { posix, win32 } from 'node:path'
 import type { Store } from './persistence'
 import type { Repo } from '../shared/repo-types'
 import { isFolderRepo } from '../shared/repo-kind'
 import { isWindowsAbsolutePathLike } from '../shared/cross-platform-path'
-import {
-  WORKTREE_CREATE_PREPARATION_DIRECTORY,
-  createWorktreePreparationLockReason
-} from '../shared/worktree/create-preparation'
+import type { PreparedCheckoutMissReason } from '../shared/worktree/create-types'
 import type { AddWorktreeOptions, AddWorktreeResult } from './git/worktree'
+import { measureRetargetDivergence } from './git/worktree-base-divergence'
+import { resolveLocalWorktreeBaseRef } from './git/worktree-base-ref-probe'
+import { preparationPathKey, selectPreparationForCreate } from './worktree-create-preparation-claim'
+import {
+  _resetPreparationPoolForTests,
+  findPreparation,
+  hasPendingPreparations,
+  listPreparations,
+  startPreparation,
+  takePreparation,
+  type PreparationEntry
+} from './worktree-create-preparation-pool'
 import {
   discardPreparedWorktree,
-  finalizePreparedWorktree,
-  prepareWorktreeCreateCheckout
+  finalizePreparedWorktree
 } from './git/worktree-create-preparation'
 import {
   getLocalProjectWorktreeGitOptions,
@@ -24,32 +31,22 @@ import {
   recordPreparationConsume,
   resetPreparationConsumeHistoryForTests
 } from './worktree-create-preparation-burst'
-import {
-  cleanupStalePreparations,
-  hasPendingStalePreparationCleanup,
-  resetStalePreparationCleanupForTests
-} from './worktree-create-preparation-stale-cleanup'
 import { toHostFilesystemPath } from './host-tree-removal'
-import {
-  discardPreparationWithRetry,
-  resetPendingPreparationDiscardsForTests,
-  trackPreparationDiscard
-} from './worktree-preparation-discard-retry'
 
-export const WORKTREE_CREATE_PREPARATION_TTL_MS = 5 * 60_000
-export const WORKTREE_CREATE_PREPARATION_LIMIT = 3
+export {
+  WORKTREE_CREATE_PREPARATION_LIMIT,
+  WORKTREE_CREATE_PREPARATION_TTL_MS
+} from './worktree-create-preparation-pool'
 
-type PreparationEntry = {
-  key: string
-  repoPath: string
-  workspaceRoot: string
-  preparedPath: string
-  options: AddWorktreeOptions
-  createdAt: number
-  ready: Promise<void>
-  expiration: NodeJS.Timeout
+/** A prepared checkout is a create that is either in flight or imminent. */
+export function hasPendingWorktreeCreatePreparations(): boolean {
+  return hasPendingPreparations()
 }
 
+export type PreparedWorktreeCreateAttempt =
+  | { status: 'hit'; retargeted: boolean; result: AddWorktreeResult }
+  | { status: 'miss'; reason: PreparedCheckoutMissReason }
+
 type ConsumePreparedWorktreeArgs = {
   repoPath: string
   workspaceRoot: string
@@ -60,72 +57,16 @@ type ConsumePreparedWorktreeArgs = {
   options?: AddWorktreeOptions
 }
 
-const preparations = new Map<string, PreparationEntry>()
-
-/** A prepared checkout is a create that is either in flight or imminent. */
-export function hasPendingWorktreeCreatePreparations(): boolean {
-  return preparations.size > 0 || hasPendingStalePreparationCleanup()
-}
-
-function pathOps(path: string): Pick<typeof posix, 'dirname' | 'join' | 'normalize'> {
-  return isWindowsAbsolutePathLike(path) ? win32 : posix
-}
-
-function pathKey(path: string): string {
-  const normalized = pathOps(path).normalize(path)
-  return isWindowsAbsolutePathLike(path) ? normalized.toLowerCase() : normalized
-}
-
-function preparationKey(
+function canonicalBaseRef(
   repoPath: string,
-  workspaceRoot: string,
   baseBranch: string,
   options: AddWorktreeOptions
-): string {
-  return `${pathKey(repoPath)}\0${pathKey(workspaceRoot)}\0${baseBranch}\0${options.wslDistro ?? ''}`
-}
-
-function preparationHostKey(repoPath: string, options: AddWorktreeOptions): string {
-  return `${pathKey(repoPath)}\0${options.wslDistro ?? ''}`
-}
-
-async function discardEntry(entry: PreparationEntry): Promise<void> {
-  // A failed checkout self-discards, but that self-discard is best-effort too, so it can strand the
-  // registration for the same reason the discard here can. Enrol either way.
-  await entry.ready.catch(() => {})
-  await discardPreparationWithRetry({
-    hostKey: preparationHostKey(entry.repoPath, entry.options),
-    repoPath: entry.repoPath,
-    preparedPath: entry.preparedPath,
-    options: entry.options
-  })
-}
-
-function discardEntryInBackground(entry: PreparationEntry): void {
-  // Tracked, not bare `void`: the test reset must be able to settle it before dropping the registry.
-  trackPreparationDiscard(discardEntry(entry))
-}
-
-function expireEntry(entry: PreparationEntry): void {
-  if (preparations.get(entry.key) !== entry) {
-    return
-  }
-  preparations.delete(entry.key)
-  discardEntryInBackground(entry)
-}
-
-function enforcePreparationLimit(): void {
-  while (preparations.size >= WORKTREE_CREATE_PREPARATION_LIMIT) {
-    const oldest = [...preparations.values()].sort(
-      (left, right) => left.createdAt - right.createdAt
-    )[0]
-    if (!oldest) {
-      return
-    }
-    preparations.delete(oldest.key)
-    clearTimeout(oldest.expiration)
-    discardEntryInBackground(oldest)
-  }
+): Promise<string> {
+  return resolveLocalWorktreeBaseRef(
+    repoPath,
+    baseBranch,
+    options.wslDistro ? { wslDistro: options.wslDistro } : {}
+  )
 }
 
 export async function prepareWorktreeCreateForRepo(
@@ -145,122 +86,146 @@ export async function prepareWorktreeCreateForRepo(
     repo.path,
     getWorktreePathSettings(repo, store.getSettings(), getWorktreeMirrorDistro(store, repo))
   )
-  const key = preparationKey(repo.path, workspaceRoot, baseBranch, options)
-  const existing = preparations.get(key)
+  const canonicalBase = await canonicalBaseRef(repo.path, baseBranch, options)
+  const existing = findPreparation(
+    preparationPathKey(repo.path),
+    preparationPathKey(workspaceRoot),
+    canonicalBase,
+    options.wslDistro ?? ''
+  )
   if (existing) {
     return existing.ready
   }
 
-  return startPreparation(key, repo.path, workspaceRoot, baseBranch, options)
+  return startPreparation({
+    repoPath: repo.path,
+    workspaceRoot,
+    baseBranch,
+    canonicalBase,
+    options
+  })
 }
 
-function startPreparation(
-  key: string,
-  repoPath: string,
-  workspaceRoot: string,
-  baseBranch: string,
-  options: AddWorktreeOptions
-): Promise<void> {
-  enforcePreparationLimit()
-  const preparationId = `${process.pid}-${randomUUID()}`
-  const lockReason = createWorktreePreparationLockReason(preparationId)
-  const preparedPath = pathOps(workspaceRoot).join(
-    workspaceRoot,
-    WORKTREE_CREATE_PREPARATION_DIRECTORY,
-    preparationId
-  )
-  const entry = {} as PreparationEntry
-  const expiration = setTimeout(() => expireEntry(entry), WORKTREE_CREATE_PREPARATION_TTL_MS)
-  expiration.unref()
-  Object.assign(entry, {
-    key,
-    repoPath,
-    workspaceRoot,
-    preparedPath,
-    options,
-    createdAt: Date.now(),
-    expiration,
-    ready: (async () => {
-      await cleanupStalePreparations(preparationHostKey(repoPath, options), repoPath, options)
-      await mkdir(
-        toHostFilesystemPath(
-          pathOps(workspaceRoot).join(workspaceRoot, WORKTREE_CREATE_PREPARATION_DIRECTORY)
-        ),
-        { recursive: true }
-      )
-      await prepareWorktreeCreateCheckout(repoPath, preparedPath, baseBranch, lockReason, options)
-    })()
-  } satisfies PreparationEntry)
-  preparations.set(key, entry)
-  void entry.ready.catch(() => {
-    if (preparations.get(key) === entry) {
-      preparations.delete(key)
-      clearTimeout(entry.expiration)
-    }
-  })
-  return entry.ready
-}
+type ClaimedPreparation =
+  | { status: 'claimed'; entry: PreparationEntry; retargeted: boolean; canonicalBase: string }
+  | { status: 'miss'; reason: PreparedCheckoutMissReason }
 
 async function claimPreparedWorktree(
-  repoPath: string,
-  workspaceRoot: string,
-  baseBranch: string,
+  args: ConsumePreparedWorktreeArgs,
   options: AddWorktreeOptions
-): Promise<PreparationEntry | null> {
-  const key = preparationKey(repoPath, workspaceRoot, baseBranch, options)
-  const entry = preparations.get(key)
-  if (!entry) {
-    return null
+): Promise<ClaimedPreparation> {
+  const request = {
+    repoPathKey: preparationPathKey(args.repoPath),
+    workspaceRootKey: preparationPathKey(args.workspaceRoot),
+    wslDistro: options.wslDistro ?? '',
+    baseBranch: args.baseBranch
   }
-  preparations.delete(key)
-  clearTimeout(entry.expiration)
+  let selection = selectPreparationForCreate(listPreparations(), {
+    ...request,
+    canonicalBase: null
+  })
+  if (selection.kind === 'needs-canonical-base') {
+    // The probe is the only await here, and the pool is re-read after it, so the select-and-take
+    // below stays one synchronous run and no other create can hold the same entry.
+    const canonicalBase = await canonicalBaseRef(args.repoPath, args.baseBranch, options)
+    selection = selectPreparationForCreate(listPreparations(), { ...request, canonicalBase })
+  }
+  if (selection.kind !== 'exact' && selection.kind !== 'retarget') {
+    return {
+      status: 'miss',
+      reason: selection.kind === 'miss' ? selection.reason : 'base_mismatch'
+    }
+  }
+  if (selection.kind === 'retarget') {
+    const candidate = selection.candidate
+    const { canonicalBase } = selection
+    const divergence = await measureRetargetDivergence(
+      args.repoPath,
+      candidate.canonicalBase,
+      canonicalBase,
+      {
+        ...(options.wslDistro ? { wslDistro: options.wslDistro } : {}),
+        // Why forward it: a cancelled create must stop these probes now, not at the deadline.
+        ...(options.signal ? { signal: options.signal } : {})
+      }
+    )
+    if (divergence !== 'within') {
+      return {
+        status: 'miss',
+        reason: divergence === 'exceeded' ? 'retarget_too_divergent' : 'retarget_unverifiable'
+      }
+    }
+    // Re-select after the walk: the pool may have gained an exact match or lost this entry. A
+    // different retarget candidate is left for the next create rather than claimed unverified.
+    selection = selectPreparationForCreate(listPreparations(), { ...request, canonicalBase })
+    if (selection.kind === 'miss' || selection.kind === 'needs-canonical-base') {
+      return { status: 'miss', reason: 'base_mismatch' }
+    }
+    if (selection.kind === 'retarget' && selection.candidate !== candidate) {
+      return { status: 'miss', reason: 'base_mismatch' }
+    }
+  }
+  const entry = selection.candidate
+  takePreparation(entry)
   try {
     await entry.ready
-    return entry
+    return {
+      status: 'claimed',
+      entry,
+      retargeted: selection.kind === 'retarget',
+      canonicalBase: selection.canonicalBase
+    }
   } catch {
-    return null
+    return { status: 'miss', reason: 'prepare_failed' }
   }
 }
 
-/** Replaces a just-consumed preparation, but only once the user has shown they are creating in a
- *  burst. A replacement costs a full checkout and ~5 minutes of disk until its TTL, so arming one
- *  after an isolated create spends that on nobody. Never awaited: create has already returned by
- *  the time the replacement checkout finishes. */
-function rearmPreparation(entry: PreparationEntry, baseBranch: string): void {
+/** Replaces a just-consumed preparation, re-armed on the base the create actually used so the
+ *  next one hits exactly — but only once the user has shown they are creating in a burst. A
+ *  replacement costs a full checkout and ~5 minutes of disk until its TTL, so arming one after an
+ *  isolated create spends that on nobody. Never awaited: create has already returned by the time
+ *  the replacement checkout finishes. */
+function rearmPreparation(
+  entry: PreparationEntry,
+  baseBranch: string,
+  canonicalBase: string
+): void {
   // Record first: a prefetch that re-armed this key while we finalized would otherwise swallow the
   // consume, and the next create would look isolated when it is really the middle of a burst.
   const continuesBurst = recordPreparationConsume(entry.key)
-  if (preparations.has(entry.key) || !continuesBurst) {
+  if (
+    !continuesBurst ||
+    findPreparation(entry.repoPathKey, entry.workspaceRootKey, canonicalBase, entry.wslDistro)
+  ) {
     return
   }
-  void startPreparation(
-    entry.key,
-    entry.repoPath,
-    entry.workspaceRoot,
+  void startPreparation({
+    repoPath: entry.repoPath,
+    workspaceRoot: entry.workspaceRoot,
     baseBranch,
-    entry.options
-  ).catch(() => {
+    canonicalBase,
+    options: entry.options
+  }).catch(() => {
     // Why: a warm-up failure is recovered by the normal add on the next create.
   })
 }
 
 export async function consumePreparedWorktreeCreate(
   args: ConsumePreparedWorktreeArgs
-): Promise<AddWorktreeResult | null> {
+): Promise<PreparedWorktreeCreateAttempt> {
   const options = args.options ?? {}
-  const entry = await claimPreparedWorktree(
-    args.repoPath,
-    args.workspaceRoot,
-    args.baseBranch,
-    options
-  )
-  if (!entry) {
-    return null
+  const claim = await claimPreparedWorktree(args, options)
+  if (claim.status === 'miss') {
+    return { status: 'miss', reason: claim.reason }
   }
+  const { entry } = claim
   try {
-    await mkdir(toHostFilesystemPath(pathOps(args.worktreePath).dirname(args.worktreePath)), {
-      recursive: true
-    })
+    const parentDir = isWindowsAbsolutePathLike(args.worktreePath)
+      ? win32.dirname(args.worktreePath)
+      : posix.dirname(args.worktreePath)
+    await mkdir(toHostFilesystemPath(parentDir), { recursive: true })
+    // Finalize resolves the requested base itself and resets the prepared checkout onto that
+    // commit, so a retargeted claim is handed over at the requested commit or not at all.
     const result = await finalizePreparedWorktree(
       args.repoPath,
       entry.preparedPath,
@@ -272,28 +237,19 @@ export async function consumePreparedWorktreeCreate(
     )
     // Consuming the only prepared checkout leaves the next create cold. Re-arm for a user who is
     // creating in a burst; the TTL and the preparation limit still bound an unused replacement.
-    rearmPreparation(entry, args.baseBranch)
-    return result
+    rearmPreparation(entry, args.baseBranch, claim.canonicalBase)
+    return { status: 'hit', retargeted: claim.retargeted, result }
   } catch (error) {
     await discardPreparedWorktree(args.repoPath, entry.preparedPath, options).catch(() => {})
     console.warn(
       '[worktree-create] prepared checkout could not be finalized; using normal add',
       error
     )
-    return null
+    return { status: 'miss', reason: 'finalize_failed' }
   }
 }
 
 export async function _resetWorktreeCreatePreparationsForTests(): Promise<void> {
-  const entries = [...preparations.values()]
-  preparations.clear()
   resetPreparationConsumeHistoryForTests()
-  resetStalePreparationCleanupForTests()
-  await Promise.all(
-    entries.map(async (entry) => {
-      clearTimeout(entry.expiration)
-      await discardEntry(entry)
-    })
-  )
-  await resetPendingPreparationDiscardsForTests()
+  await _resetPreparationPoolForTests()
 }
diff --git a/src/main/worktree-create-timing.ts b/src/main/worktree-create-timing.ts
index 433a9ac0098..bc1e49f4842 100644
--- a/src/main/worktree-create-timing.ts
+++ b/src/main/worktree-create-timing.ts
@@ -1,4 +1,5 @@
 import type {
+  PreparedCheckoutOutcome,
   WorktreeCreateTiming,
   WorktreeCreateTimingPhase
 } from '../shared/worktree/create-types'
@@ -8,6 +9,7 @@ type TimingClock = () => number
 export type WorktreeCreateTimingRecorder = {
   time<T>(phase: string, operation: () => Promise<T>): Promise<T>
   timeSync<T>(phase: string, operation: () => T): T
+  recordPreparedCheckout(outcome: PreparedCheckoutOutcome): void
   finish(): WorktreeCreateTiming
 }
 
@@ -37,6 +39,7 @@ export function createWorktreeCreateTimingRecorder(
 ): WorktreeCreateTimingRecorder {
   const startedAt = clock()
   const phases: WorktreeCreateTimingPhase[] = []
+  let preparedCheckout: PreparedCheckoutOutcome | undefined
 
   const recordPhase = (phase: string, operationStartedAt: number): void => {
     phases.push(createPhase(phase, operationStartedAt, clock(), startedAt))
@@ -59,10 +62,14 @@ export function createWorktreeCreateTimingRecorder(
         recordPhase(phase, operationStartedAt)
       }
     },
+    recordPreparedCheckout(outcome: PreparedCheckoutOutcome): void {
+      preparedCheckout = outcome
+    },
     finish() {
       return {
         totalDurationMs: clampDuration(clock() - startedAt),
-        phases: [...phases]
+        phases: [...phases],
+        ...(preparedCheckout ? { preparedCheckout } : {})
       }
     }
   }
diff --git a/src/shared/git-binary-compatibility.test.ts b/src/shared/git-binary-compatibility.test.ts
index 2861c447788..a61e64464da 100644
--- a/src/shared/git-binary-compatibility.test.ts
+++ b/src/shared/git-binary-compatibility.test.ts
@@ -182,6 +182,38 @@ describeBinaryCompatibility('real Git binary compatibility', () => {
     await runGit(['branch', '-D', 'compat-prepared-final'])
   })
 
+  // Why pin this: the prepared-checkout retarget bound reads these as data, and it fails closed,
+  // so a version that printed a different shape would silently stop every retarget rather than
+  // error. Built with `commit-tree` so the check leaves no ref, branch, or worktree behind.
+  it('measures retarget drift identically on every supported Git', async () => {
+    const tree = (await runGit(['rev-parse', 'HEAD^{tree}'])).stdout.trim()
+    const head = (await runGit(['rev-parse', 'HEAD'])).stdout.trim()
+    const ahead1 = (await runGit(['commit-tree', tree, '-p', head, '-m', 'drift 1'])).stdout.trim()
+    const ahead2 = (
+      await runGit(['commit-tree', tree, '-p', ahead1, '-m', 'drift 2'])
+    ).stdout.trim()
+
+    await expect(
+      runGit(['rev-list', '--count', '--max-count=101', '--end-of-options', `${head}..${ahead2}`])
+    ).resolves.toMatchObject({ stdout: '2\n' })
+    // `--max-count` must report the capped number, not the full one: the bound reads it as a
+    // ceiling, so a Git that returned the true count would reject every retarget instead.
+    await expect(
+      runGit(['rev-list', '--count', '--max-count=1', '--end-of-options', `${head}..${ahead2}`])
+    ).resolves.toMatchObject({ stdout: '1\n' })
+    await expect(
+      runGit(['rev-list', '--count', '--max-count=101', '--end-of-options', `${ahead2}..${head}`])
+    ).resolves.toMatchObject({ stdout: '0\n' })
+
+    await expect(runGit(['merge-base', '--end-of-options', head, ahead2])).resolves.toMatchObject({
+      stdout: `${head}\n`
+    })
+    // A parentless commit shares no history, which is the case the bound must reject however few
+    // commits each side carries.
+    const unrelated = (await runGit(['commit-tree', tree, '-m', 'unrelated root'])).stdout.trim()
+    await expect(runGit(['merge-base', '--end-of-options', head, unrelated])).rejects.toBeDefined()
+  })
+
   it('recognizes ref and merge-tree compatibility boundaries', async () => {
     const fetchHeadPath = join(repoPath, '.git', 'FETCH_HEAD')
     await writeFile(fetchHeadPath, 'sentinel\n')
diff --git a/src/shared/worktree/base-ref.test.ts b/src/shared/worktree/base-ref.test.ts
index 062d840b1cd..de87a1b0880 100644
--- a/src/shared/worktree/base-ref.test.ts
+++ b/src/shared/worktree/base-ref.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from 'vitest'
-import { resolveWorktreeAddBaseRef } from './base-ref'
+import { resolveWorktreeAddBaseRef, worktreeBaseRefFamily } from './base-ref'
 
 describe('resolveWorktreeAddBaseRef', () => {
   it('leaves fully qualified refs unchanged', async () => {
@@ -62,3 +62,31 @@ describe('resolveWorktreeAddBaseRef', () => {
     await expect(resolveWorktreeAddBaseRef('abc1234', refExists)).resolves.toBe('abc1234')
   })
 })
+
+describe('worktreeBaseRefFamily', () => {
+  it('gives a local branch and its remote-tracking copies the same family', () => {
+    expect(worktreeBaseRefFamily('refs/heads/main')).toBe('main')
+    expect(worktreeBaseRefFamily('refs/remotes/origin/main')).toBe('main')
+    expect(worktreeBaseRefFamily('refs/remotes/upstream/main')).toBe('main')
+  })
+
+  it('keeps the full branch path for slash-containing branches', () => {
+    expect(worktreeBaseRefFamily('refs/heads/release/24.1')).toBe('release/24.1')
+    expect(worktreeBaseRefFamily('refs/remotes/origin/release/24.1')).toBe('release/24.1')
+  })
+
+  it('separates different branches', () => {
+    expect(worktreeBaseRefFamily('refs/heads/main')).not.toBe(
+      worktreeBaseRefFamily('refs/heads/release')
+    )
+  })
+
+  it('has no family for anything that is not a branch ref', () => {
+    expect(worktreeBaseRefFamily('abc1234')).toBeNull()
+    expect(worktreeBaseRefFamily('main')).toBeNull()
+    expect(worktreeBaseRefFamily('refs/tags/v1.0.0')).toBeNull()
+    expect(worktreeBaseRefFamily('refs/pull/123/head')).toBeNull()
+    expect(worktreeBaseRefFamily('refs/remotes/origin/HEAD')).toBeNull()
+    expect(worktreeBaseRefFamily('refs/remotes/origin')).toBeNull()
+  })
+})
diff --git a/src/shared/worktree/base-ref.ts b/src/shared/worktree/base-ref.ts
index 6b4b840910f..08b39f6ef27 100644
--- a/src/shared/worktree/base-ref.ts
+++ b/src/shared/worktree/base-ref.ts
@@ -23,3 +23,30 @@ export async function resolveWorktreeAddBaseRef(
 
   return baseRef
 }
+
+/**
+ * The branch identity two base refs share when one is the local branch and the
+ * other is a remote-tracking copy of it: `refs/heads/main` and
+ * `refs/remotes/origin/main` both return `main`.
+ *
+ * Bounds the prepared-checkout retarget. A prepared checkout may only be reused
+ * for a different base when both name the same branch, so the retarget reset is
+ * bounded by that branch's drift across remotes rather than by an arbitrary
+ * divergence. Anything unqualified — a bare name, a commit id — has no family.
+ */
+export function worktreeBaseRefFamily(qualifiedRef: string): string | null {
+  if (qualifiedRef.startsWith('refs/heads/')) {
+    return qualifiedRef.slice('refs/heads/'.length) || null
+  }
+  if (qualifiedRef.startsWith('refs/remotes/')) {
+    const withoutRemote = qualifiedRef.slice('refs/remotes/'.length)
+    const separator = withoutRemote.indexOf('/')
+    if (separator <= 0) {
+      return null
+    }
+    const branch = withoutRemote.slice(separator + 1)
+    // `refs/remotes/<remote>/HEAD` is a symbolic pointer, not a branch identity.
+    return branch && branch !== 'HEAD' ? branch : null
+  }
+  return null
+}
diff --git a/src/shared/worktree/create-types.ts b/src/shared/worktree/create-types.ts
index cb773336db1..d8f3cfc81c5 100644
--- a/src/shared/worktree/create-types.ts
+++ b/src/shared/worktree/create-types.ts
@@ -31,9 +31,40 @@ export type WorktreeCreateTimingPhase = {
   durationMs: number
 }
 
+/** Closed vocabulary: these values reach span attributes, so none of them may ever
+ *  be derived from a branch name, a ref, or a path. */
+export type PreparedCheckoutMissReason =
+  | 'none_armed'
+  /** Preparations exist, but none for this repo — it was never warmed, or the pool's size cap
+   *  evicted it for another repo. Distinguished from `none_armed` because it is the signal that
+   *  the cap is thrashing for a multi-project user. */
+  | 'repo_mismatch'
+  | 'base_mismatch'
+  | 'retarget_too_divergent'
+  /** The drift check returned no answer. Distinct from `retarget_too_divergent` because that one
+   *  is the bound working as intended, while this one means a possibly cheap retarget was skipped
+   *  anyway. Deliberately a mixed bucket — a blown deadline, a cancelled create, and an ordinary
+   *  Git failure such as a missing ref all land here — so treat a rise as "look at why", not as a
+   *  direct readout of the budget being too small. */
+  | 'retarget_unverifiable'
+  | 'workspace_root_mismatch'
+  | 'wsl_distro_mismatch'
+  | 'prepare_failed'
+  | 'finalize_failed'
+  | 'checkout_existing_branch'
+  | 'sparse_checkout'
+
+/** Whether a create reused a prewarmed checkout, and when it did not, which part of
+ *  the claim key disagreed. `retargeted` marks a hit that had to reset the prepared
+ *  checkout onto a different ref in the same base family. */
+export type PreparedCheckoutOutcome =
+  | { status: 'hit'; retargeted: boolean }
+  | { status: 'miss'; reason: PreparedCheckoutMissReason }
+
 export type WorktreeCreateTiming = {
   totalDurationMs: number
   phases: WorktreeCreateTimingPhase[]
+  preparedCheckout?: PreparedCheckoutOutcome
 }
 
 export type CreateSparseCheckoutRequest = {