From 11936f08ab1bb736a8f53e215cea5da3b2793793 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Fri, 31 Jul 2026 00:25:52 -0700
Subject: [PATCH 01/23] perf(renderer): lazy load Linear setup dialog (#11687)

---
 src/renderer/src/app-startup-routing.test.ts  |  12 ++
 .../sidebar/LinearAgentSkillSetupDialog.tsx   |   2 +
 ...ntSkillSetupPrompt.reminder-toast.test.tsx |   1 +
 .../LinearAgentSkillSetupPrompt.test.tsx      |  15 +-
 .../sidebar/LinearAgentSkillSetupPrompt.tsx   | 132 +++++++++---------
 ...ntSkillSetupPrompt.update-command.test.tsx |   1 +
 6 files changed, 93 insertions(+), 70 deletions(-)

diff --git a/src/renderer/src/app-startup-routing.test.ts b/src/renderer/src/app-startup-routing.test.ts
index f638ae82083..8547e17a135 100644
--- a/src/renderer/src/app-startup-routing.test.ts
+++ b/src/renderer/src/app-startup-routing.test.ts
@@ -328,6 +328,18 @@ describe('renderer startup runtime routing', () => {
     )
   })
 
+  it('loads Linear agent setup implementation only after the prompt opens it', () => {
+    const source = readFileSync(
+      join(process.cwd(), 'src/renderer/src/components/sidebar/LinearAgentSkillSetupPrompt.tsx'),
+      'utf8'
+    )
+
+    expect(source).toContain("() => import('./LinearAgentSkillSetupDialog')")
+    expect(source).not.toContain("from './LinearAgentSkillSetupDialog'")
+    expect(source).toContain('const setupDialog = setupDialogOpen ? (')
+    expect(source).toContain('<Suspense fallback={null}>')
+  })
+
   it('does not eagerly import optional status-bar segments on startup', () => {
     const source = readFileSync(
       join(process.cwd(), 'src/renderer/src/components/status-bar/StatusBar.tsx'),
diff --git a/src/renderer/src/components/sidebar/LinearAgentSkillSetupDialog.tsx b/src/renderer/src/components/sidebar/LinearAgentSkillSetupDialog.tsx
index e67b946cff9..1de868ec200 100644
--- a/src/renderer/src/components/sidebar/LinearAgentSkillSetupDialog.tsx
+++ b/src/renderer/src/components/sidebar/LinearAgentSkillSetupDialog.tsx
@@ -191,3 +191,5 @@ export function LinearAgentSkillSetupDialog({
     </Dialog>
   )
 }
+
+export default LinearAgentSkillSetupDialog
diff --git a/src/renderer/src/components/sidebar/LinearAgentSkillSetupPrompt.reminder-toast.test.tsx b/src/renderer/src/components/sidebar/LinearAgentSkillSetupPrompt.reminder-toast.test.tsx
index d05496a19fe..72fcede0b7b 100644
--- a/src/renderer/src/components/sidebar/LinearAgentSkillSetupPrompt.reminder-toast.test.tsx
+++ b/src/renderer/src/components/sidebar/LinearAgentSkillSetupPrompt.reminder-toast.test.tsx
@@ -119,6 +119,7 @@ async function renderPrompt(
   await act(async () => {
     root?.render(<LinearAgentSkillSetupPrompt {...props} />)
   })
+  await import('./LinearAgentSkillSetupDialog')
   await act(async () => {})
 }
 
diff --git a/src/renderer/src/components/sidebar/LinearAgentSkillSetupPrompt.test.tsx b/src/renderer/src/components/sidebar/LinearAgentSkillSetupPrompt.test.tsx
index 0d784cb1033..c26f7024a9a 100644
--- a/src/renderer/src/components/sidebar/LinearAgentSkillSetupPrompt.test.tsx
+++ b/src/renderer/src/components/sidebar/LinearAgentSkillSetupPrompt.test.tsx
@@ -147,6 +147,9 @@ async function renderPrompt(
   await act(async () => {
     root?.render(<LinearAgentSkillSetupPrompt {...props} />)
   })
+  if (props.surface === 'modal') {
+    await import('./LinearAgentSkillSetupDialog')
+  }
   await act(async () => {})
   return container
 }
@@ -178,6 +181,7 @@ function findBodyButton(label: string): HTMLButtonElement | undefined {
 }
 
 async function settleRender(): Promise<void> {
+  await import('./LinearAgentSkillSetupDialog')
   await act(async () => {})
   await act(async () => {})
 }
@@ -253,12 +257,7 @@ describe('LinearAgentSkillSetupPrompt', () => {
     const unlinked = await renderPrompt({ linked: false, remote: false })
     expect(unlinked.textContent).not.toContain('Set up Linear agent skill')
 
-    await act(async () => {
-      root?.unmount()
-    })
-    root = null
-    unlinked.remove()
-    container = null
+    await unmountPrompt()
 
     const ready = await renderPrompt({ linked: true, remote: false })
     expect(ready.textContent).not.toContain('Set up Linear agent skill')
@@ -343,6 +342,7 @@ describe('LinearAgentSkillSetupPrompt', () => {
     await act(async () => {
       setupButton?.dispatchEvent(new MouseEvent('click', { bubbles: true }))
     })
+    await settleRender()
 
     expect(document.body.textContent).toContain("wsl.exe -d 'Fedora' -- bash -lc 'npx skills add")
     expect(mocks.panelProps.at(-1)).toEqual(
@@ -425,7 +425,7 @@ describe('LinearAgentSkillSetupPrompt', () => {
     expect(mocks.getWslCliStatus).not.toHaveBeenCalled()
   })
 
-  it('opens the terminal setup panel in a dialog only after the user asks to set up', async () => {
+  it('keeps the prompt usable and loads the lazy setup dialog only when requested', async () => {
     const rendered = await renderPrompt({ linked: true, remote: false })
 
     expect(document.body.querySelector('[data-testid="linear-skill-inline-panel"]')).toBeNull()
@@ -436,6 +436,7 @@ describe('LinearAgentSkillSetupPrompt', () => {
     await act(async () => {
       setupButton?.dispatchEvent(new MouseEvent('click', { bubbles: true }))
     })
+    await settleRender()
 
     expect(document.body.querySelector('[data-testid="linear-skill-inline-panel"]')).not.toBeNull()
     expect(document.body.textContent).toContain('orca-linear')
diff --git a/src/renderer/src/components/sidebar/LinearAgentSkillSetupPrompt.tsx b/src/renderer/src/components/sidebar/LinearAgentSkillSetupPrompt.tsx
index d840807a7e6..31c648da74b 100644
--- a/src/renderer/src/components/sidebar/LinearAgentSkillSetupPrompt.tsx
+++ b/src/renderer/src/components/sidebar/LinearAgentSkillSetupPrompt.tsx
@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { Suspense, useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { RefreshCw, TicketCheck, X } from 'lucide-react'
 import type { CliInstallStatus } from '../../../../shared/cli-install-types'
 import type { ProjectExecutionRuntimeResolution } from '../../../../shared/project-execution-runtime'
@@ -16,6 +16,7 @@ import {
   ensureOrcaCliAvailableForAgentSkillTerminal,
   isOrcaCliAvailableOnPath
 } from '@/lib/agent-skill-cli-prerequisite'
+import { lazyWithRetry } from '@/lib/lazy-with-retry'
 import { cn } from '@/lib/utils'
 import {
   buildSkillCommandForRuntime,
@@ -45,9 +46,12 @@ import {
   readLocalDismissed,
   type LinearAgentSkillPromptSettings
 } from './linear-agent-skill-runtime'
-import { LinearAgentSkillSetupDialog } from './LinearAgentSkillSetupDialog'
 import { translate } from '@/i18n/i18n'
 
+const LinearAgentSkillSetupDialog = lazyWithRetry(() => import('./LinearAgentSkillSetupDialog'), {
+  reloadKey: 'linear-agent-skill-setup-dialog'
+})
+
 export const _linearAgentSkillSetupPromptInternalsForTests = {
   resetSessionReminders(): void {
     resetLinearAgentSkillSetupReminderToastState()
@@ -278,69 +282,71 @@ export function LinearAgentSkillSetupPrompt({
     return null
   }
 
-  const setupDialog = (
-    <LinearAgentSkillSetupDialog
-      open={setupDialogOpen}
-      showSuccess={showSuccessModal}
-      successDescription={successDescription}
-      missingLabel={missingLabel}
-      command={command}
-      installedCommand={installedCommand}
-      terminalShellOverride={terminalShellOverride}
-      installed={skill.installed}
-      loading={showCheckingModal || cliLoading || skill.loading}
-      error={skill.error}
-      getPrerequisiteStatus={
-        agentRuntime.runtime === 'wsl'
-          ? () => window.api.cli.getWslInstallStatus(getWslCliDistroRequest(agentRuntime))
-          : undefined
-      }
-      onBeforeOpenTerminal={async () => {
-        const requestIdentity = setupCheckIdentity
-        const writeIfCurrent = (write: () => void): void => {
-          writeCliStatusForIdentity(requestIdentity, write)
-        }
-        const nextStatus =
+  const setupDialog = setupDialogOpen ? (
+    <Suspense fallback={null}>
+      <LinearAgentSkillSetupDialog
+        open
+        showSuccess={showSuccessModal}
+        successDescription={successDescription}
+        missingLabel={missingLabel}
+        command={command}
+        installedCommand={installedCommand}
+        terminalShellOverride={terminalShellOverride}
+        installed={skill.installed}
+        loading={showCheckingModal || cliLoading || skill.loading}
+        error={skill.error}
+        getPrerequisiteStatus={
           agentRuntime.runtime === 'wsl'
-            ? await ensureWslCliAvailableForAgentSkillTerminal(agentRuntime)
-            : await ensureOrcaCliAvailableForAgentSkillTerminal({
-                onStatusChange: (nextCliStatus) => {
-                  writeIfCurrent(() => setCliStatus(nextCliStatus))
-                }
-              })
-        if (agentRuntime.runtime === 'wsl') {
-          writeIfCurrent(() => setCliStatus(nextStatus))
+            ? () => window.api.cli.getWslInstallStatus(getWslCliDistroRequest(agentRuntime))
+            : undefined
         }
-      }}
-      onRecheck={async () => {
-        if (surface === 'modal') {
-          setActiveSetupCheckIdentity(setupCheckIdentity)
-          setSetupCheckResult('checking')
-          await Promise.all([refreshCliStatus(), skill.refresh()])
-          return
-        }
-        await refreshCliStatus()
-        await skill.refresh()
-      }}
-      onOpenChange={(open) => {
-        if (open) {
-          setSetupDialogOpen(true)
-          return
-        }
-        if (showSuccessModal) {
-          closeSuccessModal()
-          return
-        }
-        if (surface === 'modal') {
-          snoozeForSession()
-          return
-        }
-        setSetupDialogOpen(false)
-      }}
-      onDismissPermanently={dismissPermanently}
-      onDone={closeSuccessModal}
-    />
-  )
+        onBeforeOpenTerminal={async () => {
+          const requestIdentity = setupCheckIdentity
+          const writeIfCurrent = (write: () => void): void => {
+            writeCliStatusForIdentity(requestIdentity, write)
+          }
+          const nextStatus =
+            agentRuntime.runtime === 'wsl'
+              ? await ensureWslCliAvailableForAgentSkillTerminal(agentRuntime)
+              : await ensureOrcaCliAvailableForAgentSkillTerminal({
+                  onStatusChange: (nextCliStatus) => {
+                    writeIfCurrent(() => setCliStatus(nextCliStatus))
+                  }
+                })
+          if (agentRuntime.runtime === 'wsl') {
+            writeIfCurrent(() => setCliStatus(nextStatus))
+          }
+        }}
+        onRecheck={async () => {
+          if (surface === 'modal') {
+            setActiveSetupCheckIdentity(setupCheckIdentity)
+            setSetupCheckResult('checking')
+            await Promise.all([refreshCliStatus(), skill.refresh()])
+            return
+          }
+          await refreshCliStatus()
+          await skill.refresh()
+        }}
+        onOpenChange={(open) => {
+          if (open) {
+            setSetupDialogOpen(true)
+            return
+          }
+          if (showSuccessModal) {
+            closeSuccessModal()
+            return
+          }
+          if (surface === 'modal') {
+            snoozeForSession()
+            return
+          }
+          setSetupDialogOpen(false)
+        }}
+        onDismissPermanently={dismissPermanently}
+        onDone={closeSuccessModal}
+      />
+    </Suspense>
+  ) : null
 
   if (surface === 'modal') {
     return setupDialog
diff --git a/src/renderer/src/components/sidebar/LinearAgentSkillSetupPrompt.update-command.test.tsx b/src/renderer/src/components/sidebar/LinearAgentSkillSetupPrompt.update-command.test.tsx
index 7ff473b49da..af2c3f85572 100644
--- a/src/renderer/src/components/sidebar/LinearAgentSkillSetupPrompt.update-command.test.tsx
+++ b/src/renderer/src/components/sidebar/LinearAgentSkillSetupPrompt.update-command.test.tsx
@@ -107,6 +107,7 @@ async function renderPrompt(
       <LinearAgentSkillSetupPrompt linked={true} remote={false} surface="modal" {...props} />
     )
   })
+  await import('./LinearAgentSkillSetupDialog')
   await act(async () => {})
 }
 

From 037f7a07d30ca25a68764e074ec2f448049ca8f3 Mon Sep 17 00:00:00 2001
From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com>
Date: Fri, 31 Jul 2026 00:29:01 -0700
Subject: [PATCH 02/23] fix(mobile): open host editor reliably (#11635)

---
 mobile/app/index.tsx                          |  3 +-
 .../transport/host-edit-navigation.test.ts    | 29 +++++++++++++++++++
 mobile/src/transport/host-edit-navigation.ts  | 19 ++++++++++++
 3 files changed, 50 insertions(+), 1 deletion(-)
 create mode 100644 mobile/src/transport/host-edit-navigation.test.ts
 create mode 100644 mobile/src/transport/host-edit-navigation.ts

diff --git a/mobile/app/index.tsx b/mobile/app/index.tsx
index f486fe99c78..4000906c933 100644
--- a/mobile/app/index.tsx
+++ b/mobile/app/index.tsx
@@ -26,6 +26,7 @@ import {
 } from '../src/components/AccountUsage'
 import AsyncStorage from '@react-native-async-storage/async-storage'
 import { loadHosts } from '../src/transport/host-store'
+import { navigateToMobileHostEdit } from '../src/transport/host-edit-navigation'
 import { removeHostAndCloseClient } from '../src/transport/host-removal-lifecycle'
 import { pickResumeWorktree } from '../src/worktree/resume-worktree'
 import type { RpcClient } from '../src/transport/rpc-client'
@@ -1010,7 +1011,7 @@ export default function HomeScreen() {
             closeBeforePress: true,
             onPress: () => {
               setActionTarget(null)
-              router.push(`/h/${host.id}/edit`)
+              navigateToMobileHostEdit(router, host.id)
             }
           })
           items.push({
diff --git a/mobile/src/transport/host-edit-navigation.test.ts b/mobile/src/transport/host-edit-navigation.test.ts
new file mode 100644
index 00000000000..66ca63c5efa
--- /dev/null
+++ b/mobile/src/transport/host-edit-navigation.test.ts
@@ -0,0 +1,29 @@
+import { describe, expect, it, vi } from 'vitest'
+import { mobileHostEditRoute, navigateToMobileHostEdit } from './host-edit-navigation'
+
+describe('mobileHostEditRoute', () => {
+  it('keeps the dynamic host segment explicit for a cold host navigator', () => {
+    expect(mobileHostEditRoute('host-1')).toEqual({
+      pathname: '/h/[hostId]/edit',
+      params: { hostId: 'host-1' }
+    })
+  })
+
+  it('mounts a cold host navigator before replacing its index with edit', () => {
+    let nextFrame: FrameRequestCallback | null = null
+    const push = vi.fn()
+    const replace = vi.fn()
+    vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => {
+      nextFrame = callback
+      return 1
+    })
+
+    navigateToMobileHostEdit({ push, replace }, 'host-1')
+    expect(push).toHaveBeenCalledWith('/h/host-1')
+    expect(replace).not.toHaveBeenCalled()
+
+    nextFrame?.(0)
+    expect(replace).toHaveBeenCalledWith(mobileHostEditRoute('host-1'))
+    vi.unstubAllGlobals()
+  })
+})
diff --git a/mobile/src/transport/host-edit-navigation.ts b/mobile/src/transport/host-edit-navigation.ts
new file mode 100644
index 00000000000..19dbf703dec
--- /dev/null
+++ b/mobile/src/transport/host-edit-navigation.ts
@@ -0,0 +1,19 @@
+type HostEditRouter = {
+  push: (href: `/h/${string}`) => void
+  replace: (href: ReturnType<typeof mobileHostEditRoute>) => void
+}
+
+export function mobileHostEditRoute(hostId: string) {
+  return {
+    pathname: '/h/[hostId]/edit' as const,
+    params: { hostId }
+  }
+}
+
+export function navigateToMobileHostEdit(router: HostEditRouter, hostId: string): void {
+  // Why: a cold nested host navigator resolves a deep push to its index route.
+  router.push(`/h/${hostId}`)
+  requestAnimationFrame(() => {
+    router.replace(mobileHostEditRoute(hostId))
+  })
+}

From fe979a402a12a05115b83ff7c2ec60fe74e2bac1 Mon Sep 17 00:00:00 2001
From: OrcaWin <alpha-eng@stably.ai>
Date: Fri, 31 Jul 2026 00:36:09 -0700
Subject: [PATCH 03/23] Fix SSH port-forward rows disappearing after hydration
 (#11713)

---
 config/reliability-gates.jsonc                | 135 ++++++-
 src/renderer/src/hooks/useIpcEvents.test.ts   | 300 ++++++++++++++
 src/renderer/src/hooks/useIpcEvents.ts        |  62 ++-
 .../ssh-port-forward-lifecycle-evidence.ts    | 225 +++++++++++
 .../ssh-port-forward-snapshot-barrier.ts      | 158 ++++++++
 ...port-forward-snapshot-barrier.unit.test.ts |  69 ++++
 .../ssh-port-forward-transport-evidence.ts    | 145 +++++++
 tests/e2e/ssh-port-forward-lifecycle.spec.ts  | 370 ++++++++++++++++++
 8 files changed, 1445 insertions(+), 19 deletions(-)
 create mode 100644 tests/e2e/helpers/ssh-port-forward-lifecycle-evidence.ts
 create mode 100644 tests/e2e/helpers/ssh-port-forward-snapshot-barrier.ts
 create mode 100644 tests/e2e/helpers/ssh-port-forward-snapshot-barrier.unit.test.ts
 create mode 100644 tests/e2e/helpers/ssh-port-forward-transport-evidence.ts
 create mode 100644 tests/e2e/ssh-port-forward-lifecycle.spec.ts

diff --git a/config/reliability-gates.jsonc b/config/reliability-gates.jsonc
index a243d500d0b..fb86c790432 100644
--- a/config/reliability-gates.jsonc
+++ b/config/reliability-gates.jsonc
@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "updatedAt": "2026-07-29",
+  "updatedAt": "2026-07-30",
   "policy": {
     "maturityLevels": ["experimental", "soak", "blocking", "accepted-gap", "deprecated"],
     "blockingPromotion": {
@@ -7879,6 +7879,139 @@
         "Relay-hosted plugin provisioning, consent persistence, workers, and audit services remain out of scope and the relay registration therefore denies every provisioned identity by default."
       ],
       "demotionRule": "Keep experimental or demote to protection none if the suite flakes, permits a mismatched terminal send, performs more than one inventory list per call, accepts client-supplied grants, or relay and desktop error codes diverge."
+    },
+    {
+      "id": "ssh-port-forward.renderer-snapshot-continuity",
+      "title": "SSH forwarded-port state survives stale renderer hydration",
+      "maturity": "experimental",
+      "protection": "partial",
+      "owner": "desktop-ssh",
+      "layer": "renderer-ssh-snapshot-reconciliation",
+      "surfaces": [
+        "SSH Ports panel",
+        "forwarded-port renderer state",
+        "persisted forward restoration",
+        "ssh2 port forwarding",
+        "system-SSH port forwarding"
+      ],
+      "platforms": ["macos", "linux", "windows"],
+      "providers": ["ssh2", "system-ssh"],
+      "coveredPlatforms": ["macos"],
+      "coveredProviders": ["ssh2", "system-ssh"],
+      "coverageNotes": "A deterministic renderer ordering test covers stale initial snapshots independently by target and stream, including hydration after partial SSH authority reconciliation. Headed macOS Electron tests force the same startup hydration race and use an ephemeral Docker sshd, a real remote Git worktree, real remote Node listeners, real HTTP forwards, in-place relay and full transport reconnect restoration, collision rejection, scan refresh, explicit removal, and an unrelated surviving forward through both transports. The forced-system run requires a recorded OpenSSH -L invocation.",
+      "motivatingLinks": ["user-reported SSH Ports panel disappearance"],
+      "invariant": "For one connected SSH authority, a renderer snapshot may update Forwarded or Detected state only if no newer push for that target and stream arrived after the snapshot began. Active tunnels and persisted intent remain authoritative through scan refresh and reconnect until explicit removal or a real connection-lifecycle transition.",
+      "oracle": "Hold empty initial Forwarded and Detected snapshot promises, publish live events, release the snapshots, and require each target and stream to preserve only its own newer push while applying unaffected snapshots. Reject one target's Detected snapshot and require its Forwarded snapshot plus later targets to hydrate independently. Begin another target with partial connected authority and require its snapshots to hydrate after same-watermark authority reconciliation. In headed Electron, hold an authoritative empty Forwarded snapshot across renderer reload, add a forward through the Ports panel, release and confirm the wrapped main handler resumed, then complete a later renderer-to-main listPortForwards round trip as the ordered hydration-continuation barrier. Before checking the Forwarded row, require main inventory, persisted intent, HTTP, remote process identity, and close warnings to prove the tunnel remained authoritative. Then forward two real Docker listeners, refresh detection, force an in-place relay-channel reconnect, perform a full transport reconnect, reject a bound local-port collision, remove one row, and require all signals to agree.",
+      "commands": [
+        "pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/hooks/useIpcEvents.test.ts src/main/ssh/ssh-port-forward.test.ts src/main/ssh/system-ssh-forward-process.test.ts src/main/ipc/ssh.test.ts src/main/ssh/ssh-relay-session.test.ts tests/e2e/helpers/ssh-port-forward-snapshot-barrier.unit.test.ts --reporter=dot",
+        "pnpm exec electron-vite build --mode e2e",
+        "ORCA_E2E_SSH_DOCKER=1 ORCA_E2E_FORWARD_APP_LOGS=1 SKIP_BUILD=1 pnpm exec playwright test tests/e2e/ssh-port-forward-lifecycle.spec.ts --config tests/playwright.config.ts --project electron-headful --workers=1",
+        "ORCA_E2E_SSH_DOCKER=1 ORCA_SSH_FORCE_SYSTEM_TRANSPORT=1 ORCA_E2E_FORWARD_APP_LOGS=1 SKIP_BUILD=1 pnpm exec playwright test tests/e2e/ssh-port-forward-lifecycle.spec.ts --config tests/playwright.config.ts --project electron-headful --workers=1"
+      ],
+      "testFiles": [
+        "src/renderer/src/hooks/useIpcEvents.test.ts",
+        "src/main/ssh/ssh-port-forward.test.ts",
+        "src/main/ssh/system-ssh-forward-process.test.ts",
+        "src/main/ipc/ssh.test.ts",
+        "src/main/ssh/ssh-relay-session.test.ts",
+        "tests/e2e/helpers/ssh-port-forward-snapshot-barrier.unit.test.ts",
+        "tests/e2e/ssh-port-forward-lifecycle.spec.ts"
+      ],
+      "assertionRefs": [
+        {
+          "file": "src/renderer/src/hooks/useIpcEvents.test.ts",
+          "assertions": ["does not let initial SSH port snapshots overwrite newer push events"]
+        },
+        {
+          "file": "src/main/ssh/ssh-port-forward.test.ts",
+          "assertions": ["lists forwards filtered by connectionId", "removes a forward by id"]
+        },
+        {
+          "file": "src/main/ssh/system-ssh-forward-process.test.ts",
+          "assertions": [
+            "does not spawn ssh when the requested local forward port is already in use",
+            "sends SIGTERM then SIGKILL when the process does not exit",
+            "does not resolve stop until the process exits"
+          ]
+        },
+        {
+          "file": "src/main/ipc/ssh.test.ts",
+          "assertions": [
+            "preserves active port forwards and live connections across handler re-registration",
+            "persists desired forwards and broadcasts when an active forward closes unexpectedly"
+          ]
+        },
+        {
+          "file": "src/main/ssh/ssh-relay-session.test.ts",
+          "assertions": ["cleans up port forwards on reconnect"]
+        },
+        {
+          "file": "tests/e2e/helpers/ssh-port-forward-snapshot-barrier.unit.test.ts",
+          "assertions": ["holds only the first matching request while its snapshot is unresolved"]
+        },
+        {
+          "file": "tests/e2e/ssh-port-forward-lifecycle.spec.ts",
+          "assertions": ["keeps a user-forwarded listener live across scan refresh @headful"]
+        }
+      ],
+      "evidenceRuns": [
+        {
+          "date": "2026-07-30",
+          "runner": "local",
+          "platform": "macos",
+          "command": "pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/hooks/useIpcEvents.test.ts src/main/ssh/ssh-port-forward.test.ts src/main/ssh/system-ssh-forward-process.test.ts src/main/ipc/ssh.test.ts src/main/ssh/ssh-relay-session.test.ts tests/e2e/helpers/ssh-port-forward-snapshot-barrier.unit.test.ts --reporter=dot",
+          "result": "passed",
+          "durationSeconds": 6.77,
+          "summary": "Six renderer, main-process, and barrier lifecycle files passed with 215 tests, including deterministic stale-snapshot, rejected-stream, partial-authority, and single-capture isolation plus existing collision, delayed-exit, reconnect, persistence, re-registration, and unrelated-forward contracts."
+        },
+        {
+          "date": "2026-07-30",
+          "runner": "local",
+          "platform": "macos",
+          "command": "ORCA_E2E_SSH_DOCKER=1 ORCA_E2E_FORWARD_APP_LOGS=1 SKIP_BUILD=1 pnpm exec playwright test tests/e2e/ssh-port-forward-lifecycle.spec.ts --config tests/playwright.config.ts --project electron-headful --workers=1",
+          "result": "passed",
+          "durationSeconds": 53.7,
+          "summary": "Headed Electron passed against a real Docker sshd over ssh2 after forcing the stale startup-snapshot race and exact renderer-continuation barrier, with two remote listeners, scan refresh, in-place relay and full transport reconnect restoration, collision rejection, explicit removal, independent state inventories, HTTP responses, process identity, and no live forward-close warning."
+        },
+        {
+          "date": "2026-07-30",
+          "runner": "local",
+          "platform": "macos",
+          "command": "ORCA_E2E_SSH_DOCKER=1 ORCA_SSH_FORCE_SYSTEM_TRANSPORT=1 ORCA_E2E_FORWARD_APP_LOGS=1 SKIP_BUILD=1 pnpm exec playwright test tests/e2e/ssh-port-forward-lifecycle.spec.ts --config tests/playwright.config.ts --project electron-headful --workers=1",
+          "result": "passed",
+          "durationSeconds": 66,
+          "summary": "The identical stale-snapshot and headed lifecycle passed through forced system OpenSSH, with a wrapper marker proving the -L forward process executed; in-place relay and full transport reconnects restored both intents, no unexpected forward close was captured before assertions, and intentional removal completed."
+        }
+      ],
+      "runtimeBudget": {
+        "p95Seconds": 180,
+        "scope": "focused renderer/main contracts plus two headed Docker SSH transport runs"
+      },
+      "flakeHistory": {
+        "status": "unknown",
+        "evidence": "The deterministic contract and both real transport runs passed locally; CI and soak history are not yet available."
+      },
+      "redGreenEvidence": {
+        "status": "complete",
+        "evidence": "The identical renderer unit and headed Electron oracles fail on current main because the stale empty hydration reply becomes a second and final Forwarded write, pass with bounded per-target per-stream pending-hydration state, fail again when only that fix is removed, and pass again after restoration. In the tightened headed revert, both transports first proved main inventory, persisted intent, HTTP, remote process identity, no live close warning, and renderer continuation, then failed only at the missing Forwarded-row assertion. Both passed after rebuilding the restored candidate."
+      },
+      "performanceBudget": {
+        "required": true,
+        "evidence": "The fix adds one effect-scoped map containing only unresolved target hydrations, one O(1) boolean write per relevant existing push event, and one O(1) authority/stream check per initial snapshot. Forwarded and Detected hydrate independently so a stalled stream does not block its peer or later targets; entries are removed after both settle. It adds no polling, timers, IPC calls, scans, subprocesses, or renderer subscriptions."
+      },
+      "promotionCriteria": [
+        "Collect 100 consecutive focused CI passes or 14 days of soak history.",
+        "Run the headed topology on Linux and Windows with their native system-SSH clients.",
+        "Re-run the headed snapshot barrier after Electron major-version upgrades.",
+        "Keep the independent Forwarded and Detected freshness assertions and both transport runs green."
+      ],
+      "knownGaps": [
+        "Headed live evidence is macOS-only; Linux and Windows system-SSH clients were not exercised.",
+        "The headed race uses Electron's private invoke-handler registry to delay the real listPortForwards handler because Electron exposes no public handler-wrapping API.",
+        "The live run reconnects an existing app session but does not restart the packaged application from disk.",
+        "The live topology uses an SSH Git worktree; folder-workspace behavior is covered by target-scoped renderer reconciliation rather than a second headed topology."
+      ],
+      "demotionRule": "Keep experimental or demote if same-authority snapshots can overwrite newer pushes, reconnect silently loses persisted intent, one forward operation disturbs unrelated forwards, live HTTP diverges from renderer/main inventory, or either transport topology flakes without an identified product or harness fault."
     }
   ]
 }
diff --git a/src/renderer/src/hooks/useIpcEvents.test.ts b/src/renderer/src/hooks/useIpcEvents.test.ts
index 1f9b1763851..cfc4bd5d8fc 100644
--- a/src/renderer/src/hooks/useIpcEvents.test.ts
+++ b/src/renderer/src/hooks/useIpcEvents.test.ts
@@ -5539,6 +5539,306 @@ describe('useIpcEvents agent status snapshot integration', () => {
     }
   )
 
+  it('does not let initial SSH port snapshots overwrite newer push events', async () => {
+    const targetId = 'target-ports'
+    const secondTargetId = 'target-ports-second'
+    const rejectingTargetId = 'target-ports-rejecting'
+    const partialTargetId = 'target-ports-partial'
+    const connectedState = {
+      targetId,
+      status: 'connected' as const,
+      error: null,
+      reconnectAttempt: 0,
+      providerEpoch: 'epoch-ports',
+      connectionGeneration: 3
+    }
+    const secondConnectedState = {
+      ...connectedState,
+      targetId: secondTargetId,
+      providerEpoch: 'epoch-ports-second'
+    }
+    const rejectingConnectedState = {
+      ...connectedState,
+      targetId: rejectingTargetId,
+      providerEpoch: 'epoch-ports-rejecting'
+    }
+    const partialConnectedState = {
+      ...connectedState,
+      targetId: partialTargetId,
+      providerEpoch: null,
+      connectionGeneration: undefined
+    }
+    const reconciledPartialState = {
+      ...connectedState,
+      targetId: partialTargetId,
+      providerEpoch: 'epoch-ports-partial',
+      connectionGeneration: 4
+    }
+    const liveForward = {
+      id: 'forward-live',
+      targetId,
+      localPort: 17860,
+      remoteHost: '127.0.0.1',
+      remotePort: 7860,
+      status: 'active' as const
+    }
+    const secondForward = {
+      ...liveForward,
+      id: 'forward-second',
+      targetId: secondTargetId,
+      localPort: 17861,
+      remotePort: 7861
+    }
+    const rejectingTargetForward = {
+      ...liveForward,
+      id: 'forward-rejecting-target',
+      targetId: rejectingTargetId,
+      localPort: 17862,
+      remotePort: 7862
+    }
+    const partialTargetForward = {
+      ...liveForward,
+      id: 'forward-partial-target',
+      targetId: partialTargetId,
+      localPort: 17863,
+      remotePort: 7863
+    }
+    const detectedPort = {
+      port: 7860,
+      pid: 42,
+      processName: 'python',
+      command: 'python -m http.server 7860'
+    }
+    const secondDetectedPort = {
+      ...detectedPort,
+      port: 7861,
+      pid: 43,
+      command: 'python -m http.server 7861'
+    }
+    let resolveForwards: (value: []) => void = () => {}
+    let resolveDetected: (value: (typeof detectedPort)[]) => void = () => {}
+    let resolveSecondForwards: (value: (typeof secondForward)[]) => void = () => {}
+    let resolveSecondDetected: (value: []) => void = () => {}
+    const forwardsSnapshot = new Promise<[]>((resolve) => {
+      resolveForwards = resolve
+    })
+    const detectedSnapshot = new Promise<(typeof detectedPort)[]>((resolve) => {
+      resolveDetected = resolve
+    })
+    const secondForwardsSnapshot = new Promise<(typeof secondForward)[]>((resolve) => {
+      resolveSecondForwards = resolve
+    })
+    const secondDetectedSnapshot = new Promise<[]>((resolve) => {
+      resolveSecondDetected = resolve
+    })
+    const listPortForwards = vi.fn(({ targetId: requestedTargetId }: { targetId: string }) => {
+      if (requestedTargetId === rejectingTargetId) {
+        return Promise.resolve([rejectingTargetForward])
+      }
+      if (requestedTargetId === partialTargetId) {
+        return Promise.resolve([partialTargetForward])
+      }
+      return requestedTargetId === targetId ? forwardsSnapshot : secondForwardsSnapshot
+    })
+    const listDetectedPorts = vi.fn(({ targetId: requestedTargetId }: { targetId: string }) => {
+      if (requestedTargetId === rejectingTargetId) {
+        return Promise.reject(new Error('detected snapshot unavailable'))
+      }
+      if (requestedTargetId === partialTargetId) {
+        return Promise.resolve([])
+      }
+      return requestedTargetId === targetId ? detectedSnapshot : secondDetectedSnapshot
+    })
+    let forwardListener:
+      | ((data: { targetId: string; forwards: (typeof liveForward)[] }) => void)
+      | undefined
+    let detectedListener:
+      | ((data: { targetId: string; ports: (typeof detectedPort)[] }) => void)
+      | undefined
+    const setPortForwards = vi.fn()
+    const setDetectedPorts = vi.fn()
+    const sshConnectionStates = new Map<
+      string,
+      | typeof connectedState
+      | typeof secondConnectedState
+      | typeof rejectingConnectedState
+      | typeof partialConnectedState
+      | typeof reconciledPartialState
+    >()
+    const storeState = buildStoreState({
+      sshTargetLabels: new Map([
+        [targetId, 'Ports Target'],
+        [secondTargetId, 'Second Ports Target'],
+        [rejectingTargetId, 'Rejecting Ports Target'],
+        [partialTargetId, 'Partial Ports Target']
+      ]),
+      sshConnectionStates,
+      setSshConnectionState: (
+        nextTargetId: string,
+        state:
+          | typeof connectedState
+          | typeof secondConnectedState
+          | typeof rejectingConnectedState
+          | typeof partialConnectedState
+          | typeof reconciledPartialState
+      ) => {
+        sshConnectionStates.set(nextTargetId, state)
+      },
+      setPortForwards,
+      setDetectedPorts,
+      setSshTargetsMetadata: vi.fn(),
+      setRemovedSshTargetLabels: vi.fn(),
+      setRemoteWorkspaceSyncStatus: vi.fn(),
+      fetchRuntimeEnvironmentRepos: vi.fn(async () => []),
+      fetchWorktreeLineage: vi.fn(async () => undefined),
+      clearRemoteDetectedAgents: vi.fn(),
+      clearDirectSshTargetPtyBindings: vi.fn(),
+      clearRemovedSshTargetState: vi.fn(),
+      invalidateStaleDirectSshTargetPtyBindings: vi.fn(() => 0),
+      retryDirectSshTargetPanes: vi.fn(() => 0)
+    })
+    const coordinator = {
+      requestReconnect: vi.fn(async () => ({ status: 'complete' })),
+      replaceAuthority: vi.fn(),
+      prepareOnly: vi.fn(async () => ({ token: null })),
+      correctUnboundTerminals: vi.fn(() => 0),
+      finalizeHydratedTerminals: vi.fn(() => 0),
+      invalidate: vi.fn(),
+      stop: vi.fn()
+    }
+    let partialTargetStateCalls = 0
+
+    stubReactSyncEffect()
+    stubAuxiliaryModules()
+    vi.doMock('../store', () => ({
+      useAppStore: {
+        subscribe: vi.fn(() => () => {}),
+        getState: () => storeState
+      }
+    }))
+    vi.doMock('./direct-ssh-reconnect-rollout', () => ({
+      isDirectSshReconnectCoordinatorRoutingEnabled: () => true
+    }))
+    vi.doMock('./direct-ssh-worktree-refresh-scheduler', () => ({
+      createDirectSshWorktreeRefreshScheduler: () => ({
+        stop: vi.fn(),
+        disposeProvider: vi.fn()
+      })
+    }))
+    vi.doMock('./direct-ssh-host-hydration', () => ({
+      createDirectSshHostHydration: () => ({
+        capturePreparationInput: vi.fn(),
+        readHostScopedLineage: vi.fn(),
+        isPreparationTokenCurrent: vi.fn(() => true),
+        stop: vi.fn()
+      })
+    }))
+    vi.doMock('./direct-ssh-reconnect-coordinator', () => ({
+      createDirectSshReconnectCoordinator: () => coordinator
+    }))
+    vi.doMock('@/lib/direct-ssh-reconnect-product-telemetry', () => ({
+      createDirectSshReconnectProductTelemetryAdapter: vi.fn()
+    }))
+    vi.stubGlobal(
+      'window',
+      buildWindowApi({
+        onSet: () => () => {},
+        ssh: {
+          listTargets: () =>
+            Promise.resolve([
+              { id: rejectingTargetId, label: 'Rejecting Ports Target' },
+              { id: partialTargetId, label: 'Partial Ports Target' },
+              { id: targetId, label: 'Ports Target' },
+              { id: secondTargetId, label: 'Second Ports Target' }
+            ]),
+          listRemovedTargetLabels: () => Promise.resolve({}),
+          getState: ({ targetId: requestedTargetId }: { targetId: string }) => {
+            if (requestedTargetId === partialTargetId) {
+              partialTargetStateCalls += 1
+              return Promise.resolve(
+                partialTargetStateCalls === 1 ? partialConnectedState : reconciledPartialState
+              )
+            }
+            return Promise.resolve(
+              requestedTargetId === rejectingTargetId
+                ? rejectingConnectedState
+                : requestedTargetId === targetId
+                  ? connectedState
+                  : secondConnectedState
+            )
+          },
+          listPortForwards,
+          listDetectedPorts,
+          onPortForwardsChanged: (
+            listener: (data: { targetId: string; forwards: (typeof liveForward)[] }) => void
+          ) => {
+            forwardListener = listener
+            return () => {}
+          },
+          onDetectedPortsChanged: (
+            listener: (data: { targetId: string; ports: (typeof detectedPort)[] }) => void
+          ) => {
+            detectedListener = listener
+            return () => {}
+          }
+        }
+      })
+    )
+
+    const { useIpcEvents } = await import('./useIpcEvents')
+    useIpcEvents()
+
+    await vi.waitFor(() => {
+      expect(forwardListener).toBeTypeOf('function')
+      expect(detectedListener).toBeTypeOf('function')
+      expect(partialTargetStateCalls).toBe(2)
+      expect(sshConnectionStates.get(partialTargetId)).toEqual(reconciledPartialState)
+      expect(listPortForwards).toHaveBeenCalledTimes(4)
+      expect(listDetectedPorts).toHaveBeenCalledTimes(4)
+      expect(
+        setPortForwards.mock.calls.filter(
+          ([requestedTargetId]) => requestedTargetId === rejectingTargetId
+        )
+      ).toEqual([[rejectingTargetId, [rejectingTargetForward]]])
+      expect(
+        setPortForwards.mock.calls.filter(
+          ([requestedTargetId]) => requestedTargetId === partialTargetId
+        )
+      ).toEqual([[partialTargetId, [partialTargetForward]]])
+    })
+    forwardListener?.({ targetId, forwards: [liveForward] })
+    resolveForwards([])
+    resolveDetected([detectedPort])
+
+    await vi.waitFor(() => {
+      expect(
+        setPortForwards.mock.calls.filter(([requestedTargetId]) => requestedTargetId === targetId)
+      ).toEqual([[targetId, [liveForward]]])
+      expect(
+        setDetectedPorts.mock.calls.filter(([requestedTargetId]) => requestedTargetId === targetId)
+      ).toEqual([[targetId, [detectedPort]]])
+      expect(listPortForwards).toHaveBeenCalledTimes(4)
+      expect(listDetectedPorts).toHaveBeenCalledTimes(4)
+    })
+    forwardListener?.({ targetId, forwards: [liveForward] })
+    detectedListener?.({ targetId: secondTargetId, ports: [secondDetectedPort] })
+    resolveSecondForwards([secondForward])
+    resolveSecondDetected([])
+
+    await vi.waitFor(() => {
+      expect(
+        setPortForwards.mock.calls.filter(
+          ([requestedTargetId]) => requestedTargetId === secondTargetId
+        )
+      ).toEqual([[secondTargetId, [secondForward]]])
+      expect(
+        setDetectedPorts.mock.calls.filter(
+          ([requestedTargetId]) => requestedTargetId === secondTargetId
+        )
+      ).toEqual([[secondTargetId, [secondDetectedPort]]])
+    })
+  })
+
   it('caps pending mobile state events while startup hydration is unresolved', async () => {
     const setFitOverride = vi.fn()
     const hydrateOverrides = vi.fn()
diff --git a/src/renderer/src/hooks/useIpcEvents.ts b/src/renderer/src/hooks/useIpcEvents.ts
index 915df3dc05a..ba500554ae2 100644
--- a/src/renderer/src/hooks/useIpcEvents.ts
+++ b/src/renderer/src/hooks/useIpcEvents.ts
@@ -2631,6 +2631,37 @@ export function useIpcEvents(): void {
     }
 
     const sshStateWatermarkByTargetId = new Map<string, number>()
+    const pendingPortHydrationByTargetId = new Map<
+      string,
+      { receivedForwardPush: boolean; receivedDetectedPush: boolean }
+    >()
+    const hydrateSshPorts = (targetId: string, authority: DirectSshAuthority): void => {
+      const pendingPortHydration = {
+        receivedForwardPush: false,
+        receivedDetectedPush: false
+      }
+      pendingPortHydrationByTargetId.set(targetId, pendingPortHydration)
+      const isHydrationAuthorityCurrent = (): boolean =>
+        !directSshEffectStopped &&
+        directSshAuthoritiesEqual(currentDirectSshAuthority(targetId), authority)
+      const forwardHydration = window.api.ssh.listPortForwards({ targetId }).then((forwards) => {
+        // Why: if the session disconnected while awaiting the snapshot, applying it would resurrect a dead session's ports.
+        if (isHydrationAuthorityCurrent() && !pendingPortHydration.receivedForwardPush) {
+          useAppStore.getState().setPortForwards(targetId, forwards)
+        }
+      })
+      const detectedHydration = window.api.ssh.listDetectedPorts({ targetId }).then((detected) => {
+        if (isHydrationAuthorityCurrent() && !pendingPortHydration.receivedDetectedPush) {
+          useAppStore.getState().setDetectedPorts(targetId, detected)
+        }
+      })
+      // Why: one failed or stalled port stream must not block the other stream or later targets.
+      void Promise.allSettled([forwardHydration, detectedHydration]).then(() => {
+        if (pendingPortHydrationByTargetId.get(targetId) === pendingPortHydration) {
+          pendingPortHydrationByTargetId.delete(targetId)
+        }
+      })
+    }
     let applySshConnectionStateChange!: (
       targetId: string,
       state: SshConnectionState,
@@ -2668,23 +2699,6 @@ export function useIpcEvents(): void {
               state as SshConnectionState,
               'initial-hydration'
             )
-            // Why: ports arrive only via push events; on reattach to a live session fetch snapshots or the Ports panel shows empty.
-            if ((state as SshConnectionState).status === 'connected') {
-              const authority = currentDirectSshAuthority(target.id)
-              const [forwards, detected] = await Promise.all([
-                window.api.ssh.listPortForwards({ targetId: target.id }),
-                window.api.ssh.listDetectedPorts({ targetId: target.id })
-              ])
-              // Why: if the session disconnected while awaiting the snapshot, applying it would resurrect a dead session's ports.
-              if (
-                !directSshEffectStopped &&
-                authority &&
-                directSshAuthoritiesEqual(currentDirectSshAuthority(target.id), authority)
-              ) {
-                useAppStore.getState().setPortForwards(target.id, forwards)
-                useAppStore.getState().setDetectedPorts(target.id, detected)
-              }
-            }
           }
         }
       } catch {
@@ -2706,12 +2720,20 @@ export function useIpcEvents(): void {
 
     unsubs.push(
       window.api.ssh.onPortForwardsChanged(({ targetId, forwards }) => {
+        const pendingPortHydration = pendingPortHydrationByTargetId.get(targetId)
+        if (pendingPortHydration) {
+          pendingPortHydration.receivedForwardPush = true
+        }
         useAppStore.getState().setPortForwards(targetId, forwards)
       })
     )
 
     unsubs.push(
       window.api.ssh.onDetectedPortsChanged(({ targetId, ports }) => {
+        const pendingPortHydration = pendingPortHydrationByTargetId.get(targetId)
+        if (pendingPortHydration) {
+          pendingPortHydration.receivedDetectedPush = true
+        }
         useAppStore.getState().setDetectedPorts(targetId, ports)
       })
     )
@@ -2736,7 +2758,7 @@ export function useIpcEvents(): void {
             latest?.targetId !== targetId ||
             !latest?.providerEpoch ||
             latest.connectionGeneration === undefined ||
-            sshStateWatermarkByTargetId.get(targetId) !== watermark
+            (sshStateWatermarkByTargetId.get(targetId) ?? 0) !== watermark
           ) {
             return
           }
@@ -2840,6 +2862,10 @@ export function useIpcEvents(): void {
         },
         { authority, previousAuthority, origin }
       )
+      // Why: initial connected state can be partial; hydrate only after reconciliation yields a complete authority.
+      if (origin === 'initial-hydration') {
+        hydrateSshPorts(targetId, authority)
+      }
     }
 
     let sshTargetStateEventId = 0
diff --git a/tests/e2e/helpers/ssh-port-forward-lifecycle-evidence.ts b/tests/e2e/helpers/ssh-port-forward-lifecycle-evidence.ts
new file mode 100644
index 00000000000..9d4c35b924b
--- /dev/null
+++ b/tests/e2e/helpers/ssh-port-forward-lifecycle-evidence.ts
@@ -0,0 +1,225 @@
+import { request } from 'node:http'
+
+import { expect, type ElectronApplication, type Page } from '@stablyai/playwright-test'
+import {
+  execDockerSshRelayTargetCommand,
+  shellQuote,
+  type DockerSshRelayTarget
+} from './docker-ssh-relay-target'
+
+export type PortForwardEvidence = {
+  events: { targetId: string; forwards: { localPort: number; remotePort: number }[] }[]
+  rendererForwards: { localPort: number; remotePort: number }[]
+  managerForwards: { localPort: number; remotePort: number }[]
+  persistedForwards: { localPort: number; remotePort: number }[]
+}
+
+export function requestForward(localPort: number): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const req = request(
+      { host: '127.0.0.1', port: localPort, path: '/', method: 'GET', timeout: 2_000 },
+      (response) => {
+        let body = ''
+        response.setEncoding('utf8')
+        response.on('data', (chunk) => {
+          body += chunk
+        })
+        response.on('end', () => resolve(body))
+      }
+    )
+    req.once('error', reject)
+    req.once('timeout', () => req.destroy(new Error('Forwarded HTTP request timed out')))
+    req.end()
+  })
+}
+
+export function startRemoteHttpListener(
+  target: DockerSshRelayTarget,
+  port: number,
+  marker: string
+): number {
+  const script = [
+    "const http = require('node:http')",
+    `const marker = ${JSON.stringify(marker)}`,
+    "const server = http.createServer((_request, response) => response.end(marker + '\\n'))",
+    `server.listen(${port}, '127.0.0.1')`
+  ].join(';')
+  execDockerSshRelayTargetCommand(
+    target,
+    [
+      `nohup node -e ${shellQuote(script)} >/tmp/orca-http-${port}.log 2>&1 < /dev/null &`,
+      `echo $! >/tmp/orca-http-${port}.pid`
+    ].join(' ')
+  )
+  return Number(execDockerSshRelayTargetCommand(target, `cat /tmp/orca-http-${port}.pid`))
+}
+
+export function readRemoteListenerIdentity(
+  target: DockerSshRelayTarget,
+  port: number
+): { pid: number; executable: string; command: string } {
+  const pid = Number(execDockerSshRelayTargetCommand(target, `cat /tmp/orca-http-${port}.pid`))
+  return {
+    pid,
+    executable: execDockerSshRelayTargetCommand(target, `readlink /proc/${pid}/exe`),
+    command: execDockerSshRelayTargetCommand(target, `tr '\\000' ' ' </proc/${pid}/cmdline`)
+  }
+}
+
+export async function installLifecycleWarningCapture(
+  electronApp: ElectronApplication
+): Promise<void> {
+  await electronApp.evaluate(() => {
+    const scope = globalThis as typeof globalThis & {
+      __sshPortForwardWarnings?: string[]
+      __sshPortForwardOriginalWarn?: typeof console.warn
+    }
+    scope.__sshPortForwardWarnings = []
+    scope.__sshPortForwardOriginalWarn = console.warn
+    console.warn = (...args: unknown[]) => {
+      const message = args.map(String).join(' ')
+      if (message.includes('[ssh')) {
+        scope.__sshPortForwardWarnings?.push(message)
+      }
+      scope.__sshPortForwardOriginalWarn?.(...args)
+    }
+  })
+}
+
+export async function readLifecycleWarnings(electronApp: ElectronApplication): Promise<string[]> {
+  return electronApp.evaluate(() => {
+    const scope = globalThis as typeof globalThis & {
+      __sshPortForwardWarnings?: string[]
+    }
+    return scope.__sshPortForwardWarnings ?? []
+  })
+}
+
+export async function restoreLifecycleWarningCapture(
+  electronApp: ElectronApplication
+): Promise<void> {
+  await electronApp.evaluate(() => {
+    const scope = globalThis as typeof globalThis & {
+      __sshPortForwardWarnings?: string[]
+      __sshPortForwardOriginalWarn?: typeof console.warn
+    }
+    if (scope.__sshPortForwardOriginalWarn) {
+      console.warn = scope.__sshPortForwardOriginalWarn
+    }
+    delete scope.__sshPortForwardWarnings
+    delete scope.__sshPortForwardOriginalWarn
+  })
+}
+
+export async function installRendererForwardCapture(page: Page): Promise<void> {
+  await page.evaluate(() => {
+    const scope = window as typeof window & {
+      __sshPortForwardEvents?: unknown[]
+      __sshPortForwardUnsubscribe?: () => void
+    }
+    scope.__sshPortForwardEvents = []
+    scope.__sshPortForwardUnsubscribe?.()
+    scope.__sshPortForwardUnsubscribe = window.api.ssh.onPortForwardsChanged((event) => {
+      scope.__sshPortForwardEvents?.push(event)
+    })
+  })
+}
+
+export async function readPortForwardEvidence(
+  page: Page,
+  targetId: string
+): Promise<PortForwardEvidence> {
+  return page.evaluate(
+    async ({ targetId }) => {
+      const store = window.__store
+      if (!store) {
+        throw new Error('Store unavailable')
+      }
+      const target = (await window.api.ssh.listTargets()).find((entry) => entry.id === targetId)
+      const scope = window as typeof window & {
+        __sshPortForwardEvents?: PortForwardEvidence['events']
+      }
+      return {
+        events: scope.__sshPortForwardEvents ?? [],
+        rendererForwards: store.getState().portForwardsByConnection[targetId] ?? [],
+        managerForwards: await window.api.ssh.listPortForwards({ targetId }),
+        persistedForwards: target?.portForwards ?? []
+      }
+    },
+    { targetId }
+  )
+}
+
+export async function openPortsPanel(page: Page): Promise<void> {
+  await page.evaluate(() => {
+    const state = window.__store?.getState()
+    state?.setRightSidebarTab('ports')
+    state?.setRightSidebarOpen(true)
+  })
+  await expect(page.getByText('Ports', { exact: true }).last()).toBeVisible()
+}
+
+export async function forwardPortFromPanel(
+  page: Page,
+  localPort: number,
+  remotePort: number
+): Promise<void> {
+  await page.getByRole('button', { name: 'Add', exact: true }).last().click()
+  const dialog = page.getByRole('dialog', { name: 'Forward a Port' })
+  await expect(dialog).toBeVisible()
+  await dialog.getByLabel('Remote Port').fill(String(remotePort))
+  await dialog.getByLabel('Local Port').fill(String(localPort))
+  await dialog.getByRole('button', { name: 'Forward', exact: true }).click()
+  await expect(dialog).not.toBeVisible()
+}
+
+export async function addPortForward(
+  page: Page,
+  args: {
+    targetId: string
+    localPort: number
+    remotePort: number
+    label: string
+  }
+): Promise<{ id: string }> {
+  return page.evaluate(
+    ({ targetId, localPort, remotePort, label }) =>
+      window.api.ssh.addPortForward({
+        targetId,
+        localPort,
+        remoteHost: '127.0.0.1',
+        remotePort,
+        label
+      }),
+    args
+  )
+}
+
+export async function expectForwardEvidence(
+  page: Page,
+  targetId: string,
+  expected: { localPort: number; remotePort: number }[]
+): Promise<void> {
+  await expect
+    .poll(
+      async () => {
+        const evidence = await readPortForwardEvidence(page, targetId)
+        return {
+          renderer: evidence.rendererForwards.map(({ localPort, remotePort }) => ({
+            localPort,
+            remotePort
+          })),
+          manager: evidence.managerForwards.map(({ localPort, remotePort }) => ({
+            localPort,
+            remotePort
+          })),
+          persisted: evidence.persistedForwards.map(({ localPort, remotePort }) => ({
+            localPort,
+            remotePort
+          }))
+        }
+      },
+      { timeout: 30_000, message: 'renderer, manager, and persisted forward state did not agree' }
+    )
+    .toEqual({ renderer: expected, manager: expected, persisted: expected })
+}
diff --git a/tests/e2e/helpers/ssh-port-forward-snapshot-barrier.ts b/tests/e2e/helpers/ssh-port-forward-snapshot-barrier.ts
new file mode 100644
index 00000000000..7127a754163
--- /dev/null
+++ b/tests/e2e/helpers/ssh-port-forward-snapshot-barrier.ts
@@ -0,0 +1,158 @@
+import { createServer } from 'node:net'
+
+import type { ElectronApplication } from '@stablyai/playwright-test'
+
+type InvokeHandler = (event: unknown, args?: { targetId?: string }) => unknown
+
+type SnapshotBarrierState = {
+  targetId: string
+  captureClaimed: boolean
+  captured: boolean
+  released: boolean
+  release: () => void
+  originalHandler: InvokeHandler
+  handlerReturned: Promise<void>
+  markHandlerReturned: () => void
+}
+
+export type ReservedLocalPort = {
+  port: number
+  release: () => Promise<void>
+}
+
+export async function reserveLocalPort(): Promise<ReservedLocalPort> {
+  const server = createServer()
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(0, '127.0.0.1', resolve)
+  })
+  const address = server.address()
+  if (!address || typeof address === 'string') {
+    server.close()
+    throw new Error('Unable to reserve a local port')
+  }
+  let released = false
+  return {
+    port: address.port,
+    release: async () => {
+      if (released) {
+        return
+      }
+      released = true
+      await new Promise<void>((resolve, reject) =>
+        server.close((error) => (error ? reject(error) : resolve()))
+      )
+    }
+  }
+}
+
+export async function installSshPortForwardSnapshotBarrier(
+  app: ElectronApplication,
+  targetId: string
+): Promise<void> {
+  await app.evaluate(({ ipcMain }, targetId) => {
+    const scope = globalThis as typeof globalThis & {
+      __sshPortForwardSnapshotBarrier?: SnapshotBarrierState
+    }
+    const handlers = (
+      ipcMain as unknown as {
+        _invokeHandlers?: Map<string, InvokeHandler>
+      }
+    )._invokeHandlers
+    const originalHandler = handlers?.get('ssh:listPortForwards')
+    if (!handlers || !originalHandler) {
+      throw new Error('ssh:listPortForwards handler is unavailable')
+    }
+    if (scope.__sshPortForwardSnapshotBarrier) {
+      throw new Error('SSH port-forward snapshot barrier is already installed')
+    }
+    let release!: () => void
+    const barrier = new Promise<void>((resolve) => {
+      release = resolve
+    })
+    let markHandlerReturned!: () => void
+    const handlerReturned = new Promise<void>((resolve) => {
+      markHandlerReturned = resolve
+    })
+    const state: SnapshotBarrierState = {
+      targetId,
+      captureClaimed: false,
+      captured: false,
+      released: false,
+      release,
+      originalHandler,
+      handlerReturned,
+      markHandlerReturned
+    }
+    scope.__sshPortForwardSnapshotBarrier = state
+    handlers.set('ssh:listPortForwards', async (event, args) => {
+      if (state.captureClaimed || args?.targetId !== state.targetId) {
+        return state.originalHandler(event, args)
+      }
+      state.captureClaimed = true
+      const snapshot = await state.originalHandler(event, args)
+      state.captured = true
+      await barrier
+      state.markHandlerReturned()
+      return snapshot
+    })
+  }, targetId)
+}
+
+export async function readSshPortForwardSnapshotBarrier(
+  app: ElectronApplication
+): Promise<{ captured: boolean; released: boolean }> {
+  return app.evaluate(() => {
+    const state = (
+      globalThis as typeof globalThis & {
+        __sshPortForwardSnapshotBarrier?: SnapshotBarrierState
+      }
+    ).__sshPortForwardSnapshotBarrier
+    return {
+      captured: state?.captured ?? false,
+      released: state?.released ?? false
+    }
+  })
+}
+
+export async function releaseSshPortForwardSnapshotBarrier(
+  app: ElectronApplication
+): Promise<void> {
+  await app.evaluate(async () => {
+    const state = (
+      globalThis as typeof globalThis & {
+        __sshPortForwardSnapshotBarrier?: SnapshotBarrierState
+      }
+    ).__sshPortForwardSnapshotBarrier
+    if (state && !state.released) {
+      state.released = true
+      state.release()
+    }
+    await state?.handlerReturned
+  })
+}
+
+export async function restoreSshPortForwardSnapshotHandler(
+  app: ElectronApplication
+): Promise<void> {
+  await app.evaluate(({ ipcMain }) => {
+    const scope = globalThis as typeof globalThis & {
+      __sshPortForwardSnapshotBarrier?: SnapshotBarrierState
+    }
+    const state = scope.__sshPortForwardSnapshotBarrier
+    if (!state) {
+      return
+    }
+    if (!state.released) {
+      state.released = true
+      state.release()
+    }
+    const handlers = (
+      ipcMain as unknown as {
+        _invokeHandlers?: Map<string, InvokeHandler>
+      }
+    )._invokeHandlers
+    handlers?.set('ssh:listPortForwards', state.originalHandler)
+    delete scope.__sshPortForwardSnapshotBarrier
+  })
+}
diff --git a/tests/e2e/helpers/ssh-port-forward-snapshot-barrier.unit.test.ts b/tests/e2e/helpers/ssh-port-forward-snapshot-barrier.unit.test.ts
new file mode 100644
index 00000000000..e85564d185e
--- /dev/null
+++ b/tests/e2e/helpers/ssh-port-forward-snapshot-barrier.unit.test.ts
@@ -0,0 +1,69 @@
+import type { ElectronApplication } from '@stablyai/playwright-test'
+import { describe, expect, it, vi } from 'vitest'
+import {
+  installSshPortForwardSnapshotBarrier,
+  readSshPortForwardSnapshotBarrier,
+  releaseSshPortForwardSnapshotBarrier,
+  restoreSshPortForwardSnapshotHandler
+} from './ssh-port-forward-snapshot-barrier'
+
+type InvokeHandler = (event: unknown, args?: { targetId?: string }) => unknown
+
+describe('SSH port-forward snapshot barrier', () => {
+  it('holds only the first matching request while its snapshot is unresolved', async () => {
+    const handlers = new Map<string, InvokeHandler>()
+    let resolveFirstSnapshot: (value: string[]) => void = () => {}
+    const firstSnapshot = new Promise<string[]>((resolve) => {
+      resolveFirstSnapshot = resolve
+    })
+    let callCount = 0
+    const originalHandler = vi.fn(() => {
+      callCount += 1
+      return callCount === 1 ? firstSnapshot : Promise.resolve(['later-snapshot'])
+    })
+    handlers.set('ssh:listPortForwards', originalHandler)
+    const app = {
+      evaluate: (
+        callback: (electron: unknown, arg?: unknown) => unknown,
+        arg?: unknown
+      ): Promise<unknown> =>
+        Promise.resolve(callback({ ipcMain: { _invokeHandlers: handlers } }, arg))
+    } as unknown as ElectronApplication
+
+    let heldRequestStarted = false
+    await installSshPortForwardSnapshotBarrier(app, 'target-1')
+    try {
+      const wrappedHandler = handlers.get('ssh:listPortForwards')
+      expect(wrappedHandler).toBeTypeOf('function')
+      if (!wrappedHandler) {
+        throw new Error('Wrapped handler unavailable')
+      }
+
+      heldRequestStarted = true
+      const firstRequest = Promise.resolve(wrappedHandler({}, { targetId: 'target-1' }))
+      await vi.waitFor(() => expect(originalHandler).toHaveBeenCalledOnce())
+      const laterRequest = Promise.resolve(wrappedHandler({}, { targetId: 'target-1' }))
+      await expect(laterRequest).resolves.toEqual(['later-snapshot'])
+      expect(await readSshPortForwardSnapshotBarrier(app)).toEqual({
+        captured: false,
+        released: false
+      })
+
+      resolveFirstSnapshot(['held-snapshot'])
+      await vi.waitFor(async () => {
+        expect(await readSshPortForwardSnapshotBarrier(app)).toEqual({
+          captured: true,
+          released: false
+        })
+      })
+      await releaseSshPortForwardSnapshotBarrier(app)
+      await expect(firstRequest).resolves.toEqual(['held-snapshot'])
+    } finally {
+      resolveFirstSnapshot(['cleanup-snapshot'])
+      if (heldRequestStarted) {
+        await releaseSshPortForwardSnapshotBarrier(app)
+      }
+      await restoreSshPortForwardSnapshotHandler(app)
+    }
+  })
+})
diff --git a/tests/e2e/helpers/ssh-port-forward-transport-evidence.ts b/tests/e2e/helpers/ssh-port-forward-transport-evidence.ts
new file mode 100644
index 00000000000..30fcc0e98d3
--- /dev/null
+++ b/tests/e2e/helpers/ssh-port-forward-transport-evidence.ts
@@ -0,0 +1,145 @@
+import { execFileSync } from 'node:child_process'
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { expect, type ElectronApplication, type Page } from '@stablyai/playwright-test'
+import {
+  execDockerSshRelayTargetCommand,
+  shellQuote,
+  type DockerSshRelayTarget
+} from './docker-ssh-relay-target'
+
+type CapturedSshState = {
+  status: string
+  providerEpoch?: string
+  connectionGeneration?: number
+}
+
+export async function trustDockerSshHost(
+  electronApp: ElectronApplication,
+  target: DockerSshRelayTarget
+): Promise<string> {
+  const sshDir = join(target.tempDir, '.ssh')
+  mkdirSync(sshDir, { recursive: true })
+  const knownHostsPath = join(sshDir, 'known_hosts')
+  const hostKeys = execFileSync('ssh-keyscan', ['-p', String(target.port), '127.0.0.1'], {
+    encoding: 'utf8'
+  })
+  writeFileSync(knownHostsPath, hostKeys)
+  const invocationLogPath = join(target.tempDir, 'system-ssh-invocations')
+  const wrapperPath = join(target.tempDir, 'verified-system-ssh')
+  writeFileSync(
+    wrapperPath,
+    [
+      '#!/bin/sh',
+      'kind=transport',
+      'for arg in "$@"; do',
+      '  if [ "$arg" = "-L" ]; then kind=forward; fi',
+      'done',
+      `printf '%s\\n' "$kind" >> ${shellQuote(invocationLogPath)}`,
+      `exec /usr/bin/ssh -o UserKnownHostsFile=${shellQuote(knownHostsPath)} -o StrictHostKeyChecking=yes "$@"`
+    ].join('\n')
+  )
+  chmodSync(wrapperPath, 0o755)
+  await electronApp.evaluate((_electron, path) => {
+    process.env.ORCA_SYSTEM_SSH_PATH = path
+  }, wrapperPath)
+  return invocationLogPath
+}
+
+export function readSystemSshInvocationKinds(invocationLogPath: string): string[] {
+  if (!existsSync(invocationLogPath)) {
+    return []
+  }
+  return readFileSync(invocationLogPath, 'utf8').split(/\r?\n/).filter(Boolean)
+}
+
+export function terminateDockerSshRelayConnectChannel(target: DockerSshRelayTarget): number {
+  const output = execDockerSshRelayTargetCommand(
+    target,
+    `
+count=0
+for proc in /proc/[0-9]*; do
+  [ -r "$proc/cmdline" ] || continue
+  argv=()
+  mapfile -d '' -t argv < "$proc/cmdline" 2>/dev/null || continue
+  [ "\${argv[1]##*/}" = relay.js ] || continue
+  mode=
+  for arg in "\${argv[@]:2}"; do
+    if [ "$arg" = --connect ]; then mode=connect; fi
+    if [ "$arg" = --detached ]; then mode=detached; fi
+  done
+  if [ "$mode" = connect ]; then
+    kill -TERM "\${proc##*/}"
+    count=$((count + 1))
+  fi
+done
+printf '%s' "$count"
+`
+  )
+  return Number(output)
+}
+
+export async function installSshStateCapture(page: Page, targetId: string): Promise<void> {
+  await page.evaluate((targetId) => {
+    const scope = window as typeof window & {
+      __sshLifecycleStates?: CapturedSshState[]
+      __sshLifecycleStateUnsubscribe?: () => void
+    }
+    scope.__sshLifecycleStateUnsubscribe?.()
+    scope.__sshLifecycleStates = []
+    scope.__sshLifecycleStateUnsubscribe = window.api.ssh.onStateChanged((event) => {
+      if (event.targetId === targetId) {
+        scope.__sshLifecycleStates?.push(event.state)
+      }
+    })
+  }, targetId)
+}
+
+export async function readSshStateCapture(page: Page): Promise<CapturedSshState[]> {
+  return page.evaluate(
+    () =>
+      (
+        window as typeof window & {
+          __sshLifecycleStates?: CapturedSshState[]
+        }
+      ).__sshLifecycleStates ?? []
+  )
+}
+
+export async function forceDockerSshRelayChannelReconnect(
+  page: Page,
+  target: DockerSshRelayTarget,
+  targetId: string
+): Promise<void> {
+  await installSshStateCapture(page, targetId)
+  const authority = await page.evaluate(
+    (targetId) => window.__store?.getState().sshConnectionStates.get(targetId),
+    targetId
+  )
+  expect(authority).toMatchObject({
+    status: 'connected',
+    providerEpoch: expect.any(String),
+    connectionGeneration: expect.any(Number)
+  })
+  expect(terminateDockerSshRelayConnectChannel(target)).toBeGreaterThan(0)
+  await expect
+    .poll(
+      async () => {
+        const states = await readSshStateCapture(page)
+        const current = await page.evaluate(
+          (targetId) => window.__store?.getState().sshConnectionStates.get(targetId),
+          targetId
+        )
+        return (
+          states.some((state) => state.status === 'reconnecting') &&
+          states.some((state) => state.status === 'connected') &&
+          current?.status === 'connected' &&
+          (current.providerEpoch !== authority?.providerEpoch ||
+            current.connectionGeneration !== authority?.connectionGeneration)
+        )
+      },
+      { timeout: 30_000, message: 'in-place relay channel did not reconnect' }
+    )
+    .toBe(true)
+}
diff --git a/tests/e2e/ssh-port-forward-lifecycle.spec.ts b/tests/e2e/ssh-port-forward-lifecycle.spec.ts
new file mode 100644
index 00000000000..fff647120b8
--- /dev/null
+++ b/tests/e2e/ssh-port-forward-lifecycle.spec.ts
@@ -0,0 +1,370 @@
+import { createServer } from 'node:net'
+
+import { test, expect } from './helpers/orca-app'
+import { waitForActiveWorktree, waitForSessionReady } from './helpers/store'
+import {
+  cleanupDockerSshRelayTarget,
+  startDockerSshRelayTarget,
+  type DockerSshRelayTarget
+} from './helpers/docker-ssh-relay-target'
+import {
+  connectDockerSshRelayTarget,
+  reconnectDockerSshRelayTarget
+} from './helpers/docker-ssh-relay-connection'
+import {
+  installSshPortForwardSnapshotBarrier,
+  readSshPortForwardSnapshotBarrier,
+  releaseSshPortForwardSnapshotBarrier,
+  reserveLocalPort,
+  restoreSshPortForwardSnapshotHandler
+} from './helpers/ssh-port-forward-snapshot-barrier'
+import {
+  addPortForward,
+  expectForwardEvidence,
+  forwardPortFromPanel,
+  installLifecycleWarningCapture,
+  installRendererForwardCapture,
+  openPortsPanel,
+  readLifecycleWarnings,
+  readPortForwardEvidence,
+  readRemoteListenerIdentity,
+  requestForward,
+  restoreLifecycleWarningCapture,
+  startRemoteHttpListener
+} from './helpers/ssh-port-forward-lifecycle-evidence'
+import {
+  forceDockerSshRelayChannelReconnect,
+  readSshStateCapture,
+  readSystemSshInvocationKinds,
+  trustDockerSshHost
+} from './helpers/ssh-port-forward-transport-evidence'
+
+const RUN_DOCKER_SSH = process.env.ORCA_E2E_SSH_DOCKER === '1'
+const FORCE_SYSTEM_SSH = process.env.ORCA_SSH_FORCE_SYSTEM_TRANSPORT === '1'
+const REMOTE_PORT = 7860
+const REFRESH_BARRIER_PORT = 7861
+const SCAN_REFRESH_PORT = 7862
+
+test.describe('Docker SSH port-forward lifecycle', () => {
+  test.skip(!RUN_DOCKER_SSH, 'Set ORCA_E2E_SSH_DOCKER=1 to run Docker-backed SSH tests.')
+  test.skip(process.platform === 'win32', 'Docker SSH lifecycle uses POSIX process inspection.')
+
+  test('keeps a user-forwarded listener live across scan refresh @headful', async ({
+    electronApp,
+    orcaPage
+  }, testInfo) => {
+    test.slow()
+    let target: DockerSshRelayTarget | null = null
+    const localPortReservation = await reserveLocalPort()
+    const unrelatedLocalPortReservation = await reserveLocalPort()
+    const localPort = localPortReservation.port
+    const unrelatedLocalPort = unrelatedLocalPortReservation.port
+    const marker = `ORCA_FORWARD_${Date.now()}`
+    const unrelatedMarker = `${marker}_UNRELATED`
+    try {
+      target = startDockerSshRelayTarget(testInfo)
+      const systemSshInvocationLogPath = await trustDockerSshHost(electronApp, target)
+      await installLifecycleWarningCapture(electronApp)
+      await waitForSessionReady(orcaPage)
+      await waitForActiveWorktree(orcaPage)
+      const remote = await connectDockerSshRelayTarget(orcaPage, target)
+      const remotePid = startRemoteHttpListener(target, REMOTE_PORT, marker)
+      const unrelatedRemotePid = startRemoteHttpListener(
+        target,
+        REFRESH_BARRIER_PORT,
+        unrelatedMarker
+      )
+      await openPortsPanel(orcaPage)
+
+      await expect
+        .poll(
+          () =>
+            orcaPage.evaluate(
+              ({ targetId, port }) =>
+                window.api.ssh
+                  .listDetectedPorts({ targetId })
+                  .then((ports) => ports.find((entry) => entry.port === port)?.pid ?? null),
+              { targetId: remote.targetId, port: REMOTE_PORT }
+            ),
+          { timeout: 45_000, message: 'remote HTTP listener was not detected' }
+        )
+        .toBe(remotePid)
+      await expect(orcaPage.getByText(`:${REMOTE_PORT}`, { exact: true })).toBeVisible()
+      await expect
+        .poll(
+          () =>
+            orcaPage.evaluate(
+              ({ targetId, port }) =>
+                window.api.ssh
+                  .listDetectedPorts({ targetId })
+                  .then((ports) => ports.some((entry) => entry.port === port)),
+              { targetId: remote.targetId, port: REFRESH_BARRIER_PORT }
+            ),
+          { timeout: 45_000, message: 'scan-refresh barrier listener was not detected' }
+        )
+        .toBe(true)
+      await expect(orcaPage.getByText(`:${REFRESH_BARRIER_PORT}`, { exact: true })).toBeVisible()
+
+      await installSshPortForwardSnapshotBarrier(electronApp, remote.targetId)
+      await orcaPage.evaluate(() => window.dispatchEvent(new Event('beforeunload')))
+      await orcaPage.reload()
+      await waitForSessionReady(orcaPage, 60_000)
+      await expect
+        .poll(() => waitForActiveWorktree(orcaPage), { timeout: 60_000 })
+        .toBe(remote.worktreeId)
+      await expect
+        .poll(
+          () =>
+            orcaPage.evaluate(
+              (targetId) => window.__store?.getState().sshConnectionStates.get(targetId)?.status,
+              remote.targetId
+            ),
+          { timeout: 60_000, message: 'renderer did not restore the connected SSH target' }
+        )
+        .toBe('connected')
+      await expect
+        .poll(() => readSshPortForwardSnapshotBarrier(electronApp), {
+          timeout: 30_000,
+          message: 'renderer hydration did not capture an empty Forwarded snapshot'
+        })
+        .toEqual({ captured: true, released: false })
+
+      await installRendererForwardCapture(orcaPage)
+      await openPortsPanel(orcaPage)
+      await localPortReservation.release()
+      await forwardPortFromPanel(orcaPage, localPort, REMOTE_PORT)
+      await expect(orcaPage.getByText('Forwarded', { exact: true })).toBeVisible()
+      await expect(
+        orcaPage.getByText(`:${localPort} → :${REMOTE_PORT}`, { exact: true })
+      ).toBeVisible()
+      await expect.poll(() => requestForward(localPort)).toContain(marker)
+      await expectForwardEvidence(orcaPage, remote.targetId, [
+        { localPort, remotePort: REMOTE_PORT }
+      ])
+      if (FORCE_SYSTEM_SSH) {
+        await expect
+          .poll(() => readSystemSshInvocationKinds(systemSshInvocationLogPath))
+          .toContain('forward')
+      } else {
+        expect(readSystemSshInvocationKinds(systemSshInvocationLogPath)).not.toContain('forward')
+      }
+
+      await releaseSshPortForwardSnapshotBarrier(electronApp)
+      const postHydrationRoundTripForwards = await orcaPage.evaluate(
+        (targetId) => window.api.ssh.listPortForwards({ targetId }),
+        remote.targetId
+      )
+      expect(postHydrationRoundTripForwards).toContainEqual(
+        expect.objectContaining({ localPort, remotePort: REMOTE_PORT })
+      )
+      await expect(orcaPage.getByText(`:${REFRESH_BARRIER_PORT}`, { exact: true })).toBeVisible()
+      const staleSnapshotEvidence = await readPortForwardEvidence(orcaPage, remote.targetId)
+      const staleSnapshotIdentity = readRemoteListenerIdentity(target, REMOTE_PORT)
+      const staleSnapshotWarnings = await readLifecycleWarnings(electronApp)
+      expect(staleSnapshotEvidence.managerForwards).toContainEqual(
+        expect.objectContaining({ localPort, remotePort: REMOTE_PORT })
+      )
+      expect(staleSnapshotEvidence.persistedForwards).toContainEqual(
+        expect.objectContaining({ localPort, remotePort: REMOTE_PORT })
+      )
+      await expect(requestForward(localPort)).resolves.toContain(marker)
+      expect(staleSnapshotIdentity).toMatchObject({
+        pid: remotePid,
+        executable: expect.stringContaining('/node'),
+        command: expect.stringContaining(String(REMOTE_PORT))
+      })
+      expect(staleSnapshotWarnings.filter((message) => message.includes('Port forward'))).toEqual(
+        []
+      )
+      await expect(
+        orcaPage.getByText(`:${localPort} → :${REMOTE_PORT}`, { exact: true })
+      ).toBeVisible()
+      await expectForwardEvidence(orcaPage, remote.targetId, [
+        { localPort, remotePort: REMOTE_PORT }
+      ])
+      await restoreSshPortForwardSnapshotHandler(electronApp)
+
+      startRemoteHttpListener(target, SCAN_REFRESH_PORT, `${marker}_SCAN_REFRESH`)
+      await expect
+        .poll(
+          () =>
+            orcaPage.evaluate(
+              ({ targetId, port }) =>
+                window.api.ssh
+                  .listDetectedPorts({ targetId })
+                  .then((ports) => ports.some((entry) => entry.port === port)),
+              { targetId: remote.targetId, port: SCAN_REFRESH_PORT }
+            ),
+          { timeout: 45_000, message: 'scan-refresh listener was not detected in main' }
+        )
+        .toBe(true)
+      await expect(orcaPage.getByText(`:${SCAN_REFRESH_PORT}`, { exact: true })).toBeVisible()
+
+      await unrelatedLocalPortReservation.release()
+      const unrelatedForward = await addPortForward(orcaPage, {
+        targetId: remote.targetId,
+        localPort: unrelatedLocalPort,
+        remotePort: REFRESH_BARRIER_PORT,
+        label: 'unrelated-listener'
+      })
+      await expectForwardEvidence(orcaPage, remote.targetId, [
+        { localPort, remotePort: REMOTE_PORT },
+        { localPort: unrelatedLocalPort, remotePort: REFRESH_BARRIER_PORT }
+      ])
+      await expect.poll(() => requestForward(unrelatedLocalPort)).toContain(unrelatedMarker)
+
+      await forceDockerSshRelayChannelReconnect(orcaPage, target, remote.targetId)
+      await expectForwardEvidence(orcaPage, remote.targetId, [
+        { localPort, remotePort: REMOTE_PORT },
+        { localPort: unrelatedLocalPort, remotePort: REFRESH_BARRIER_PORT }
+      ])
+      await expect.poll(() => requestForward(localPort)).toContain(marker)
+      await expect.poll(() => requestForward(unrelatedLocalPort)).toContain(unrelatedMarker)
+
+      const authorityBeforeTransportReconnect = await orcaPage.evaluate(
+        (targetId) => window.__store?.getState().sshConnectionStates.get(targetId),
+        remote.targetId
+      )
+      await reconnectDockerSshRelayTarget(orcaPage, remote.targetId)
+      await expect
+        .poll(
+          async () => {
+            const state = await orcaPage.evaluate(
+              (targetId) => window.__store?.getState().sshConnectionStates.get(targetId),
+              remote.targetId
+            )
+            return (
+              state?.status === 'connected' &&
+              (state.providerEpoch !== authorityBeforeTransportReconnect?.providerEpoch ||
+                state.connectionGeneration !==
+                  authorityBeforeTransportReconnect?.connectionGeneration)
+            )
+          },
+          { timeout: 30_000, message: 'renderer did not observe the reconnected SSH authority' }
+        )
+        .toBe(true)
+      await expectForwardEvidence(orcaPage, remote.targetId, [
+        { localPort, remotePort: REMOTE_PORT },
+        { localPort: unrelatedLocalPort, remotePort: REFRESH_BARRIER_PORT }
+      ])
+      await expect.poll(() => requestForward(localPort)).toContain(marker)
+      await expect.poll(() => requestForward(unrelatedLocalPort)).toContain(unrelatedMarker)
+      await expect(
+        orcaPage.getByText(`:${localPort} → :${REMOTE_PORT}`, { exact: true })
+      ).toBeVisible()
+      await expect(
+        orcaPage.getByText(`:${unrelatedLocalPort} → :${REFRESH_BARRIER_PORT}`, { exact: true })
+      ).toBeVisible()
+
+      const collisionServer = createServer()
+      await new Promise<void>((resolve, reject) => {
+        collisionServer.once('error', reject)
+        collisionServer.listen(0, '127.0.0.1', resolve)
+      })
+      const collisionAddress = collisionServer.address()
+      if (!collisionAddress || typeof collisionAddress === 'string') {
+        throw new Error('Unable to reserve a collision port')
+      }
+      try {
+        const collisionResult = await orcaPage.evaluate(
+          async ({ targetId, localPort, remotePort }) => {
+            try {
+              await window.api.ssh.addPortForward({
+                targetId,
+                localPort,
+                remoteHost: '127.0.0.1',
+                remotePort,
+                label: 'collision'
+              })
+              return { ok: true, message: '' }
+            } catch (error) {
+              return { ok: false, message: error instanceof Error ? error.message : String(error) }
+            }
+          },
+          {
+            targetId: remote.targetId,
+            localPort: collisionAddress.port,
+            remotePort: REMOTE_PORT
+          }
+        )
+        expect(collisionResult).toMatchObject({ ok: false })
+        expect(collisionResult.message).toMatch(/in use|EADDRINUSE/i)
+      } finally {
+        await new Promise<void>((resolve, reject) =>
+          collisionServer.close((error) => (error ? reject(error) : resolve()))
+        )
+      }
+      await expectForwardEvidence(orcaPage, remote.targetId, [
+        { localPort, remotePort: REMOTE_PORT },
+        { localPort: unrelatedLocalPort, remotePort: REFRESH_BARRIER_PORT }
+      ])
+
+      const primaryRow = orcaPage
+        .getByText(`:${localPort} → :${REMOTE_PORT}`, { exact: true })
+        .locator('../../..')
+      await primaryRow.getByTitle('Remove').click()
+      await expect(
+        orcaPage.getByText(`:${localPort} → :${REMOTE_PORT}`, { exact: true })
+      ).not.toBeVisible()
+      await expectForwardEvidence(orcaPage, remote.targetId, [
+        { localPort: unrelatedLocalPort, remotePort: REFRESH_BARRIER_PORT }
+      ])
+      await expect(requestForward(localPort)).rejects.toThrow()
+      await expect.poll(() => requestForward(unrelatedLocalPort)).toContain(unrelatedMarker)
+
+      const evidence = await readPortForwardEvidence(orcaPage, remote.targetId)
+      const identity = readRemoteListenerIdentity(target, REMOTE_PORT)
+      const unrelatedIdentity = readRemoteListenerIdentity(target, REFRESH_BARRIER_PORT)
+      const warnings = await readLifecycleWarnings(electronApp)
+      const relayReconnectStates = await readSshStateCapture(orcaPage)
+      testInfo.annotations.push({
+        type: 'ssh-port-forward-evidence',
+        description: JSON.stringify({
+          evidence,
+          identity,
+          unrelatedIdentity,
+          removedForwardLocalPort: localPort,
+          unrelatedForward,
+          relayReconnectStates,
+          staleSnapshotEvidence,
+          systemSshInvocations: readSystemSshInvocationKinds(systemSshInvocationLogPath),
+          warnings
+        })
+      })
+
+      expect(identity).toMatchObject({
+        pid: remotePid,
+        executable: expect.stringContaining('/node'),
+        command: expect.stringContaining(String(REMOTE_PORT))
+      })
+      expect(unrelatedIdentity).toMatchObject({
+        pid: unrelatedRemotePid,
+        executable: expect.stringContaining('/node'),
+        command: expect.stringContaining(String(REFRESH_BARRIER_PORT))
+      })
+      expect(evidence.rendererForwards).not.toContainEqual(
+        expect.objectContaining({ localPort, remotePort: REMOTE_PORT })
+      )
+      expect(evidence.managerForwards).not.toContainEqual(
+        expect.objectContaining({ localPort, remotePort: REMOTE_PORT })
+      )
+      expect(evidence.persistedForwards).not.toContainEqual(
+        expect.objectContaining({ localPort, remotePort: REMOTE_PORT })
+      )
+      expect(evidence.events.at(-1)?.forwards).toContainEqual(
+        expect.objectContaining({
+          localPort: unrelatedLocalPort,
+          remotePort: REFRESH_BARRIER_PORT
+        })
+      )
+      await expect(requestForward(unrelatedLocalPort)).resolves.toContain(unrelatedMarker)
+      expect(warnings.filter((message) => message.includes('Port forward'))).toEqual([])
+    } finally {
+      await restoreSshPortForwardSnapshotHandler(electronApp).catch(() => undefined)
+      await restoreLifecycleWarningCapture(electronApp).catch(() => undefined)
+      await localPortReservation.release().catch(() => undefined)
+      await unrelatedLocalPortReservation.release().catch(() => undefined)
+      cleanupDockerSshRelayTarget(target)
+    }
+  })
+})

From 336cef3185cf725cc12ab77da9158407ddc7a3de Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Fri, 31 Jul 2026 00:39:34 -0700
Subject: [PATCH 04/23] [P1] fix(sidebar): drop onto the indicated board
 position in virtualized lanes (#11688)

The sidebar->board drop translation still read the mounted DOM cards, while
getCardDropTarget now indexes the lane's virtual layout, so a searched and
scrolled lane resolved the drop to the wrong full-lane position.

Co-authored-by: Orca <help@stably.ai>
---
 .../workspace-kanban-sidebar-drop.test.ts     | 153 ++++++++++++++++++
 .../sidebar/workspace-kanban-sidebar-drop.ts  |  71 ++++----
 .../workspace-kanban-virtual-lane-layout.ts   |  10 ++
 3 files changed, 204 insertions(+), 30 deletions(-)

diff --git a/src/renderer/src/components/sidebar/workspace-kanban-sidebar-drop.test.ts b/src/renderer/src/components/sidebar/workspace-kanban-sidebar-drop.test.ts
index 08f627cc0b4..5a4a3d62b4c 100644
--- a/src/renderer/src/components/sidebar/workspace-kanban-sidebar-drop.test.ts
+++ b/src/renderer/src/components/sidebar/workspace-kanban-sidebar-drop.test.ts
@@ -210,6 +210,91 @@ function appendBoard(): { board: HTMLElement; lane: HTMLElement; firstCard: HTML
   return { board, lane, firstCard }
 }
 
+const VIRTUAL_CARD_PITCH = 44
+const VIRTUAL_CARD_HEIGHT = 36
+// Scrolled past the head of the lane, so the mounted window starts mid-list.
+const VIRTUAL_SPACER_TOP = -350
+
+// A virtualized lane: only `windowRange` of the view is mounted, and the layout
+// registration carries the whole view — exactly what the virtualizer publishes.
+function appendVirtualBoard(args: {
+  fullLaneIds: readonly string[]
+  viewIds: readonly string[]
+  windowRange: readonly [number, number]
+  publishFullIds: boolean
+}): { lane: HTMLElement; unregister: () => void } {
+  const board = document.createElement('div')
+  board.setAttribute('data-workspace-board-selection-surface', '')
+  setRect(board, { left: 0, top: 0, right: 320, bottom: 240, width: 320, height: 240 })
+
+  const lane = document.createElement('section')
+  lane.setAttribute('data-workspace-status-drop-target', '')
+  lane.dataset.workspaceStatus = 'doing'
+  setRect(lane, { left: 0, top: 0, right: 200, bottom: 220, width: 200, height: 220 })
+  if (args.publishFullIds) {
+    lane.dataset.workspaceLaneFullIds = serializeWorkspaceLaneFullIds([...args.fullLaneIds]) ?? ''
+  }
+
+  const laneScroll = document.createElement('div')
+  laneScroll.setAttribute('data-workspace-board-lane-scroll', '')
+  setRect(laneScroll, { left: 0, top: 0, right: 200, bottom: 220, width: 200, height: 220 })
+
+  const totalSize = args.viewIds.length * VIRTUAL_CARD_PITCH
+  const spacer = document.createElement('div')
+  setRect(spacer, {
+    left: 8,
+    top: VIRTUAL_SPACER_TOP,
+    right: 192,
+    bottom: VIRTUAL_SPACER_TOP + totalSize,
+    width: 184,
+    height: totalSize
+  })
+
+  for (let index = args.windowRange[0]; index <= args.windowRange[1]; index++) {
+    const worktreeId = args.viewIds[index]!
+    const card = document.createElement('div')
+    card.setAttribute('data-workspace-board-card-id', worktreeId)
+    card.dataset.workspaceBoardCardId = worktreeId
+    card.dataset.workspaceBoardCardIndex = String(index)
+    const top = VIRTUAL_SPACER_TOP + index * VIRTUAL_CARD_PITCH
+    setRect(card, {
+      left: 8,
+      top,
+      right: 192,
+      bottom: top + VIRTUAL_CARD_HEIGHT,
+      width: 184,
+      height: VIRTUAL_CARD_HEIGHT
+    })
+    setVisible(card)
+    spacer.append(card)
+  }
+
+  laneScroll.append(spacer)
+  lane.append(laneScroll)
+  board.append(lane)
+  document.body.append(board)
+  setElementFromPoint(lane)
+
+  const unregister = registerWorkspaceKanbanVirtualLaneLayout({
+    scrollElement: laneScroll,
+    spacerElement: spacer,
+    getItemIds: () => args.viewIds,
+    getMeasurements: () =>
+      args.viewIds.map((_, index) => ({
+        index,
+        start: index * VIRTUAL_CARD_PITCH,
+        end: index * VIRTUAL_CARD_PITCH + VIRTUAL_CARD_HEIGHT
+      }))
+  })
+  return { lane, unregister }
+}
+
+// 40-member lane under a search that matches every other card.
+function searchedVirtualLaneIds(): { fullLaneIds: string[]; viewIds: string[] } {
+  const fullLaneIds = Array.from({ length: 40 }, (_, index) => `doing-${index}`)
+  return { fullLaneIds, viewIds: fullLaneIds.filter((_, index) => index % 2 === 0) }
+}
+
 function worktree(args: {
   id: string
   workspaceStatus: string
@@ -356,6 +441,74 @@ describe('workspace kanban sidebar drop DOM bridge', () => {
     expect(resolveWorkspaceKanbanSidebarFullLaneDropIndex('doing', 2)).toBe(4)
   })
 
+  it('lands a virtualized searched lane drop where the indicator pointed', () => {
+    const { fullLaneIds, viewIds } = searchedVirtualLaneIds()
+    const { unregister } = appendVirtualBoard({
+      fullLaneIds,
+      viewIds,
+      windowRange: [8, 17],
+      publishFullIds: true
+    })
+
+    const target = getWorkspaceKanbanSidebarDropTarget(24, 210)
+    // The indicator sits between the mounted cards for view items 12 and 13,
+    // whose full-lane neighbours are doing-24 and doing-26.
+    expect(target).toMatchObject({ status: 'doing', dropIndex: 13, dropIndicatorY: 218 })
+    expect(resolveWorkspaceKanbanSidebarFullLaneDropIndex('doing', target.dropIndex)).toBe(26)
+
+    unregister()
+  })
+
+  it('translates virtualized searched lane drops above and below the mounted window', () => {
+    const { fullLaneIds, viewIds } = searchedVirtualLaneIds()
+    const { unregister } = appendVirtualBoard({
+      fullLaneIds,
+      viewIds,
+      windowRange: [8, 17],
+      publishFullIds: true
+    })
+
+    expect(resolveWorkspaceKanbanSidebarFullLaneDropIndex('doing', 0)).toBe(0)
+    expect(resolveWorkspaceKanbanSidebarFullLaneDropIndex('doing', 3)).toBe(6)
+    expect(resolveWorkspaceKanbanSidebarFullLaneDropIndex('doing', 19)).toBe(38)
+    expect(resolveWorkspaceKanbanSidebarFullLaneDropIndex('doing', 20)).toBe(39)
+
+    unregister()
+  })
+
+  it('passes a virtualized unfiltered lane drop index through untranslated', () => {
+    const { fullLaneIds } = searchedVirtualLaneIds()
+    const { unregister } = appendVirtualBoard({
+      fullLaneIds,
+      viewIds: fullLaneIds,
+      windowRange: [8, 17],
+      publishFullIds: false
+    })
+
+    expect(getWorkspaceKanbanSidebarDropGroups()).toEqual([
+      { key: 'doing', worktreeIds: fullLaneIds }
+    ])
+    expect(resolveWorkspaceKanbanSidebarFullLaneDropIndex('doing', 13)).toBe(13)
+
+    unregister()
+  })
+
+  it('still counts unlaid-out cards as lane members without a virtual layout', () => {
+    const { lane } = appendBoard()
+    const secondCard = lane.querySelectorAll<HTMLElement>('[data-workspace-board-card-id]')[1]!
+    secondCard.remove()
+    const hiddenCard = document.createElement('div')
+    hiddenCard.setAttribute('data-workspace-board-card-id', 'doing-hidden')
+    hiddenCard.dataset.workspaceBoardCardId = 'doing-hidden'
+    lane.append(hiddenCard, secondCard)
+    setElementFromPoint(lane)
+
+    expect(getWorkspaceKanbanSidebarDropGroups()).toEqual([
+      { key: 'doing', worktreeIds: ['doing-a', 'doing-hidden', 'doing-b'] }
+    ])
+    expect(resolveWorkspaceKanbanSidebarFullLaneDropIndex('doing', 1)).toBe(2)
+  })
+
   it('passes the drop index through for a lane it cannot find', () => {
     appendBoard()
 
diff --git a/src/renderer/src/components/sidebar/workspace-kanban-sidebar-drop.ts b/src/renderer/src/components/sidebar/workspace-kanban-sidebar-drop.ts
index 363038bd529..8475d91cdd8 100644
--- a/src/renderer/src/components/sidebar/workspace-kanban-sidebar-drop.ts
+++ b/src/renderer/src/components/sidebar/workspace-kanban-sidebar-drop.ts
@@ -23,9 +23,11 @@ import {
   updateCardDropIndicator,
   type WorkspaceKanbanCardDropTarget
 } from './workspace-kanban-card-pointer-drag-dom'
+import { getWorkspaceKanbanVirtualLaneItemIds } from './workspace-kanban-virtual-lane-layout'
 
 const BOARD_SELECTOR = '[data-workspace-board-selection-surface]'
 const BOARD_SHEET_SELECTOR = '[data-workspace-board-sheet]'
+const LANE_SCROLL_SELECTOR = '[data-workspace-board-lane-scroll]'
 const EXTERNAL_DRAG_TARGET_ATTR = 'data-workspace-board-external-drag-target'
 
 let externalDragTargetElement: HTMLElement | null = null
@@ -53,24 +55,33 @@ function getLaneCardIds(lane: HTMLElement): HTMLElement[] {
   return Array.from(lane.querySelectorAll<HTMLElement>(CARD_SELECTOR))
 }
 
-// Mirrors getCardDropTarget's card scan so both sides share one index space.
-// The offsetParent read forces layout, so callers pass the card list they
-// already collected rather than re-querying.
-function toRenderedCardIds(cards: readonly HTMLElement[]): string[] {
-  return cards
-    .filter((card) => card.offsetParent !== null)
-    .flatMap((card) => card.dataset.workspaceBoardCardId ?? [])
-}
-
-// Why: board search hides non-matching cards, so the rendered card scan is a
-// filtered lane. Lanes publish their full membership for exactly this reader.
-// The fallback is the unfiltered card list — a lane member the browser is not
-// laying out is still a member for manual-order purposes.
-function toLaneFullWorktreeIds(lane: HTMLElement, cards: readonly HTMLElement[]): string[] {
-  return (
-    parseWorkspaceLaneFullIds(lane.dataset.workspaceLaneFullIds) ??
-    cards.flatMap((card) => card.dataset.workspaceBoardCardId ?? [])
-  )
+/**
+ * `viewIds` is the lane in the index space `getCardDropTarget` reports, and
+ * `fullLaneIds` is the lane's whole membership. Board search hides non-matching
+ * cards, so lanes publish their full membership for exactly this reader.
+ *
+ * Why the virtual layout first: lanes virtualize, so the mounted cards are a
+ * window rather than the lane view, and `getCardDropTarget` indexes the same
+ * virtual layout. The DOM scan is only the fallback for a lane the virtualizer
+ * never claimed — there the unfiltered card list is the full lane, since a card
+ * the browser is not laying out is still a member for manual-order purposes.
+ */
+function toLaneDropIds(lane: HTMLElement): { fullLaneIds: string[]; viewIds: string[] } {
+  const publishedFullLaneIds = parseWorkspaceLaneFullIds(lane.dataset.workspaceLaneFullIds)
+  const laneScroll = lane.querySelector<HTMLElement>(LANE_SCROLL_SELECTOR)
+  const virtualItemIds = laneScroll ? getWorkspaceKanbanVirtualLaneItemIds(laneScroll) : null
+  if (virtualItemIds) {
+    const viewIds = [...virtualItemIds]
+    return { fullLaneIds: publishedFullLaneIds ?? viewIds, viewIds }
+  }
+  const cards = getLaneCardIds(lane)
+  return {
+    fullLaneIds:
+      publishedFullLaneIds ?? cards.flatMap((card) => card.dataset.workspaceBoardCardId ?? []),
+    viewIds: cards
+      .filter((card) => card.offsetParent !== null)
+      .flatMap((card) => card.dataset.workspaceBoardCardId ?? [])
+  }
 }
 
 function getStatusDropTargetElement(
@@ -128,7 +139,7 @@ export function getWorkspaceKanbanSidebarDropGroups(): WorktreeDragGroup[] {
     if (!status) {
       return []
     }
-    return [{ key: status, worktreeIds: toLaneFullWorktreeIds(lane, getLaneCardIds(lane)) }]
+    return [{ key: status, worktreeIds: toLaneDropIds(lane).fullLaneIds }]
   })
 }
 
@@ -144,26 +155,26 @@ export function getWorkspaceKanbanSidebarDropTarget(
 }
 
 /**
- * Translates a tracked drop index — which counts *rendered* cards, matching the
- * drop indicator — onto the full lane that `getWorkspaceKanbanSidebarDropGroups`
- * reports. Call this once, at the commit boundary: a tracked target can be
- * committed after the pointer has left the lane, so translating earlier would
- * miss that path.
+ * Translates a tracked drop index — which counts the lane's *view* items,
+ * matching the drop indicator — onto the full lane that
+ * `getWorkspaceKanbanSidebarDropGroups` reports. Call this once, at the commit
+ * boundary: a tracked target can be committed after the pointer has left the
+ * lane, so translating earlier would miss that path.
  */
 export function resolveWorkspaceKanbanSidebarFullLaneDropIndex(
   status: WorkspaceStatus,
-  renderedDropIndex: number
+  viewDropIndex: number
 ): number {
   const board = getWorkspaceKanbanBoardElement()
   const lane = board ? getStatusDropTargetElement(board, status) : null
   if (!lane) {
-    return renderedDropIndex
+    return viewDropIndex
   }
-  const cards = getLaneCardIds(lane)
+  const { fullLaneIds, viewIds } = toLaneDropIds(lane)
   return resolveFullLaneDropIndex({
-    fullLaneIds: toLaneFullWorktreeIds(lane, cards),
-    renderedIds: toRenderedCardIds(cards),
-    filteredDropIndex: renderedDropIndex
+    fullLaneIds,
+    renderedIds: viewIds,
+    filteredDropIndex: viewDropIndex
   })
 }
 
diff --git a/src/renderer/src/components/sidebar/workspace-kanban-virtual-lane-layout.ts b/src/renderer/src/components/sidebar/workspace-kanban-virtual-lane-layout.ts
index e142b3617d6..4d7b2897fcd 100644
--- a/src/renderer/src/components/sidebar/workspace-kanban-virtual-lane-layout.ts
+++ b/src/renderer/src/components/sidebar/workspace-kanban-virtual-lane-layout.ts
@@ -44,6 +44,16 @@ export function registerWorkspaceKanbanVirtualLaneLayout(args: {
   }
 }
 
+/**
+ * The lane's item ids in the index space `resolveWorkspaceKanbanVirtualLaneDropIndex`
+ * reports — every item in the lane view, not just the mounted virtual window.
+ */
+export function getWorkspaceKanbanVirtualLaneItemIds(
+  scrollElement: HTMLElement
+): readonly string[] | null {
+  return virtualLaneLayouts.get(scrollElement)?.getItemIds() ?? null
+}
+
 export function getWorkspaceKanbanVirtualLaneItemRects(
   scrollElement: HTMLElement
 ): WorkspaceKanbanVirtualLaneItemRect[] | null {

From 451baa1bc47f2ae4fd3cd2654e4199398612a151 Mon Sep 17 00:00:00 2001
From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com>
Date: Fri, 31 Jul 2026 00:39:44 -0700
Subject: [PATCH 05/23] fix(mobile): clear state after closing final tab
 (#11637)

* fix(mobile): clear state after closing final tab

* fix(mobile): clear terminal on empty snapshots

* fix(mobile): preserve terminal during transient empty snapshot
---
 .../app/h/[hostId]/session/[worktreeId].tsx   |  8 +++--
 .../mobile-session-last-tab-close.test.ts     | 29 +++++++++++++++++++
 2 files changed, 35 insertions(+), 2 deletions(-)
 create mode 100644 mobile/src/session/mobile-session-last-tab-close.test.ts

diff --git a/mobile/app/h/[hostId]/session/[worktreeId].tsx b/mobile/app/h/[hostId]/session/[worktreeId].tsx
index 6a7bfc3a54f..4ec0e564a79 100644
--- a/mobile/app/h/[hostId]/session/[worktreeId].tsx
+++ b/mobile/app/h/[hostId]/session/[worktreeId].tsx
@@ -1894,6 +1894,7 @@ export default function SessionScreen() {
         setActiveHandle(active.terminal)
         subscribeToTerminal(active.terminal)
       } else if (active) {
+        // Why: an empty snapshot can transiently omit a live terminal; explicit close clears it on RPC success.
         const previous = activeHandleRef.current
         if (previous) {
           unsubscribeTerminal(previous)
@@ -4133,6 +4134,7 @@ export default function SessionScreen() {
         reason: 'user'
       })
       if (response.ok) {
+        const remainingTabs = sessionTabsRef.current.filter((candidate) => candidate.id !== tab.id)
         if (tab.type === 'browser' && tab.browserPageId === pendingBrowserFocusPageIdRef.current) {
           pendingBrowserFocusPageIdRef.current = null
         }
@@ -4143,14 +4145,16 @@ export default function SessionScreen() {
           initializedHandlesRef.current.delete(terminalHandle)
           clearTerminalLiveInputDefault(terminalHandle)
         }
-        setSessionTabs((prev) => prev.filter((candidate) => candidate.id !== tab.id))
+        sessionTabsRef.current = remainingTabs
+        setSessionTabs(remainingTabs)
         // Why: tombstone the closed tab and rely on the snapshot, not a blind refetch that often re-added the not-yet-closed tab.
         closedTabTombstonesRef.current.set(tab.id, Date.now() + 10_000)
         // Why: bulk close re-activates the anchor before awaiting each close;
         // the render-synced ref sees that switch while this closure would not,
         // so comparing against the ref keeps the anchor from being nulled out.
-        if (activeSessionTabIdRef.current === tab.id) {
+        if (activeSessionTabIdRef.current === tab.id || remainingTabs.length === 0) {
           activeSessionTabTypeRef.current = null
+          activeSessionTabIdRef.current = null
           setActiveSessionTabId(null)
           activeHandleRef.current = null
           setActiveHandle(null)
diff --git a/mobile/src/session/mobile-session-last-tab-close.test.ts b/mobile/src/session/mobile-session-last-tab-close.test.ts
new file mode 100644
index 00000000000..7bd6ad179fc
--- /dev/null
+++ b/mobile/src/session/mobile-session-last-tab-close.test.ts
@@ -0,0 +1,29 @@
+import { readFileSync } from 'node:fs'
+import { describe, expect, it } from 'vitest'
+
+const sessionRouteSource = readFileSync(
+  new URL('../../app/h/[hostId]/session/[worktreeId].tsx', import.meta.url),
+  'utf8'
+)
+
+describe('mobile session last-tab close', () => {
+  it('preserves terminal identity while an empty snapshot may be transient', () => {
+    const start = sessionRouteSource.indexOf('const applySessionTabs = useCallback')
+    const end = sessionRouteSource.indexOf('const readMarkdownTab', start)
+    const block = sessionRouteSource.slice(start, end)
+
+    expect(block).toContain('} else if (active) {')
+  })
+
+  it('clears stale active identity when closing leaves no tabs', () => {
+    const start = sessionRouteSource.indexOf('async function handleCloseSessionTab')
+    const end = sessionRouteSource.indexOf('const bulkCloseActions', start)
+    const block = sessionRouteSource.slice(start, end)
+
+    expect(block).toContain(
+      'activeSessionTabIdRef.current === tab.id || remainingTabs.length === 0'
+    )
+    expect(block).toContain('activeSessionTabIdRef.current = null')
+    expect(block).toContain('activeHandleRef.current = null')
+  })
+})

From 4f00b21186daabb219a05cfe16c9e0b9ba8a96e1 Mon Sep 17 00:00:00 2001
From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com>
Date: Fri, 31 Jul 2026 00:40:11 -0700
Subject: [PATCH 06/23] fix(mobile): restore Codex chat session identity
 (#11636)

* fix(mobile): restore Codex chat session identity

* fix(mobile): reconcile native chat session ownership
---
 src/main/runtime/orca-runtime.test.ts | 122 ++++++++++++++++++++++++++
 src/main/runtime/orca-runtime.ts      |  42 ++++++++-
 2 files changed, 161 insertions(+), 3 deletions(-)

diff --git a/src/main/runtime/orca-runtime.test.ts b/src/main/runtime/orca-runtime.test.ts
index 6c137a4dcf0..153f7840760 100644
--- a/src/main/runtime/orca-runtime.test.ts
+++ b/src/main/runtime/orca-runtime.test.ts
@@ -22157,6 +22157,128 @@ describe('OrcaRuntimeService', () => {
     ])
   })
 
+  it.each([
+    {
+      behavior: 'fills a missing renderer session',
+      hookAgentType: 'codex',
+      hookOffset: 0,
+      rendererSessionId: null,
+      expectedSessionId: 'hook-session'
+    },
+    {
+      behavior: 'replaces a stale renderer session at the same event timestamp',
+      hookAgentType: 'codex',
+      hookOffset: 0,
+      rendererSessionId: 'stale-renderer-session',
+      expectedSessionId: 'hook-session'
+    },
+    {
+      behavior: 'preserves a renderer session newer than the hook row',
+      hookAgentType: 'codex',
+      hookOffset: -1,
+      rendererSessionId: 'newer-renderer-session',
+      expectedSessionId: 'newer-renderer-session'
+    },
+    {
+      behavior: 'rejects a hook session owned by another agent',
+      hookAgentType: 'claude',
+      hookOffset: 1,
+      rendererSessionId: null,
+      expectedSessionId: null
+    }
+  ] as const)(
+    '$behavior',
+    async ({ hookAgentType, hookOffset, rendererSessionId, expectedSessionId }) => {
+      const leafId = '11111111-1111-4111-8111-111111111111'
+      const paneKey = `codex-tab:${leafId}`
+      const providerSession = {
+        key: 'session_id' as const,
+        id: 'hook-session'
+      }
+      const now = Date.now()
+      const runtime = new OrcaRuntimeService(store, undefined, {
+        getAgentStatusSnapshot: () => [
+          {
+            paneKey,
+            state: 'done',
+            prompt: '',
+            agentType: hookAgentType,
+            connectionId: null,
+            receivedAt: now + hookOffset,
+            stateStartedAt: now + hookOffset,
+            tabId: 'codex-tab',
+            worktreeId: TEST_WORKTREE_ID,
+            providerSession
+          }
+        ]
+      })
+      runtime.attachWindow(1)
+      runtime.syncWindowGraph(1, {
+        tabs: [],
+        leaves: [],
+        mobileSessionTabs: [
+          {
+            worktree: TEST_WORKTREE_ID,
+            publicationEpoch: 'epoch-1',
+            snapshotVersion: 1,
+            activeGroupId: null,
+            activeTabId: `codex-tab::${leafId}`,
+            activeTabType: 'terminal',
+            tabs: [
+              {
+                type: 'terminal',
+                id: `codex-tab::${leafId}`,
+                parentTabId: 'codex-tab',
+                leafId,
+                title: 'Codex',
+                launchAgent: 'codex',
+                agentStatus: {
+                  state: 'working',
+                  prompt: 'Reply with MOBILE QA OK and nothing else.',
+                  updatedAt: now,
+                  stateStartedAt: now,
+                  agentType: 'codex',
+                  paneKey,
+                  stateHistory: [],
+                  ...(rendererSessionId
+                    ? {
+                        providerSession: {
+                          key: 'session_id' as const,
+                          id: rendererSessionId
+                        }
+                      }
+                    : {})
+                },
+                isActive: true
+              }
+            ]
+          }
+        ]
+      })
+
+      const result = await runtime.listMobileSessionTabs(`id:${TEST_WORKTREE_ID}`)
+
+      expect(result.tabs[0]).toEqual(
+        expect.objectContaining({
+          type: 'terminal',
+          agentStatus: expect.objectContaining({
+            state: 'working',
+            prompt: 'Reply with MOBILE QA OK and nothing else.',
+            agentType: 'codex'
+          })
+        })
+      )
+      if (expectedSessionId) {
+        expect(result.tabs[0]).toHaveProperty('agentStatus.providerSession', {
+          key: 'session_id',
+          id: expectedSessionId
+        })
+      } else {
+        expect(result.tabs[0]).not.toHaveProperty('agentStatus.providerSession')
+      }
+    }
+  )
+
   it('preserves authoritative OMP identity for Pi-compatible remote terminal snapshots', async () => {
     const runtime = new OrcaRuntimeService(store)
     const leafId = '11111111-1111-4111-8111-111111111111'
diff --git a/src/main/runtime/orca-runtime.ts b/src/main/runtime/orca-runtime.ts
index d6bc500632f..abc82437657 100644
--- a/src/main/runtime/orca-runtime.ts
+++ b/src/main/runtime/orca-runtime.ts
@@ -69,7 +69,8 @@ import {
 import {
   hasCompatibleAgentTitleIdentity,
   normalizeCompatibleAgentStatusEntryForOwner,
-  normalizeCompatibleAgentTitleForOwner
+  normalizeCompatibleAgentTitleForOwner,
+  resolveCompatibleAgentTypeForOwner
 } from '../../shared/agent-title-owner'
 import { resolvePaneAgentOwner } from '../../shared/pane-agent-owner'
 import {
@@ -28674,6 +28675,9 @@ export class OrcaRuntimeService {
       const retainedAgentStatus = tab.agentStatus
         ? null
         : this.getFreshRetainedAgentStatusForMobileTab(paneKey, liveLeafPty ?? mobileStatusPty, tab)
+      const hookAgentStatus = tab.agentStatus
+        ? this.getHookAgentRowForPane(getHookRowsForPane(paneKey))
+        : null
       const leafTitle = leaf
         ? getLatestAgentCandidateTitle(
             { title: leaf.paneTitle, updatedAt: leaf.paneTitleUpdatedAt },
@@ -28691,7 +28695,11 @@ export class OrcaRuntimeService {
       const ownerAgent =
         resolvePaneAgentOwner({
           launchAgent,
-          hookAgent: tab.agentStatus?.agentType ?? retainedAgentStatus?.payload.agentType ?? null
+          hookAgent:
+            tab.agentStatus?.agentType ??
+            hookAgentStatus?.agentType ??
+            retainedAgentStatus?.payload.agentType ??
+            null
         }) ??
         liveLeafPty?.foregroundAgent ??
         pty?.foregroundAgent ??
@@ -28702,8 +28710,32 @@ export class OrcaRuntimeService {
       )
       const liveTitleEvidence = leafTitle ?? ptyTitle
       const liveTitleEvidenceClassification = classifyAgentTitle(liveTitleEvidence)
+      // Why: renderer status can precede hook session identity, leaving native chat with no transcript address.
+      const rendererStatusAgent =
+        resolveCompatibleAgentTypeForOwner(tab.agentStatus?.agentType, ownerAgent) ??
+        ownerAgent ??
+        undefined
+      const hookSessionAgent = resolveCompatibleAgentTypeForOwner(
+        hookAgentStatus?.providerSessionAgentType,
+        ownerAgent
+      )
+      const hookSessionMatchesRenderer =
+        !rendererStatusAgent || !hookSessionAgent || rendererStatusAgent === hookSessionAgent
+      const hookProviderSession =
+        hookAgentStatus?.providerSession &&
+        hookSessionMatchesRenderer &&
+        (!tab.agentStatus?.providerSession ||
+          (hookAgentStatus.providerSessionReceivedAt ?? -1) >= tab.agentStatus.updatedAt)
+          ? hookAgentStatus.providerSession
+          : tab.agentStatus?.providerSession
       const normalizedTabAgentStatus = tab.agentStatus
-        ? normalizeCompatibleAgentStatusEntryForOwner(tab.agentStatus, ownerAgent)
+        ? normalizeCompatibleAgentStatusEntryForOwner(
+            {
+              ...tab.agentStatus,
+              ...(hookProviderSession ? { providerSession: hookProviderSession } : {})
+            },
+            ownerAgent
+          )
         : null
       // Why: keep rich hook status on a live prompt/tool (authoritative even under a non-agent title), else interactivePrompt is lost.
       const hasLiveAgentSignal =
@@ -28942,6 +28974,8 @@ export class OrcaRuntimeService {
    *  read would keep offering native chat for what is now a plain shell. */
   private getHookAgentRowForPane(rows: readonly AgentStatusIpcPayload[]): {
     providerSession: AgentProviderSessionMetadata | null
+    providerSessionAgentType: string | null
+    providerSessionReceivedAt: number | null
     agentType: string | null
   } {
     let session: AgentStatusIpcPayload | null = null
@@ -28967,6 +29001,8 @@ export class OrcaRuntimeService {
     }
     return {
       providerSession: session?.providerSession ?? null,
+      providerSessionAgentType: session?.agentType ?? null,
+      providerSessionReceivedAt: session?.receivedAt ?? null,
       agentType: agent?.agentType ?? null
     }
   }

From 48e52540d1a8ac720611ec04fd566bb03e515e09 Mon Sep 17 00:00:00 2001
From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com>
Date: Fri, 31 Jul 2026 00:51:39 -0700
Subject: [PATCH 07/23] fix(macos): verify Full Disk Access and re-arm notices
 (#11716)

* fix(macos): verify full disk access status

* perf(macos): keep full disk probe off main thread
---
 src/main/ipc/developer-permissions.test.ts    | 23 +++++++
 src/main/ipc/developer-permissions.ts         | 21 +------
 .../macos-full-disk-access-status.test.ts     | 63 +++++++++++++++++++
 src/main/macos-full-disk-access-status.ts     | 44 +++++++++++++
 src/main/macos-tcc-prompt-notice.test.ts      | 38 +++++++++--
 src/main/macos-tcc-prompt-notice.ts           | 26 ++++++--
 6 files changed, 188 insertions(+), 27 deletions(-)
 create mode 100644 src/main/macos-full-disk-access-status.test.ts
 create mode 100644 src/main/macos-full-disk-access-status.ts

diff --git a/src/main/ipc/developer-permissions.test.ts b/src/main/ipc/developer-permissions.test.ts
index ccb119d0e5c..78c8d6e0be0 100644
--- a/src/main/ipc/developer-permissions.test.ts
+++ b/src/main/ipc/developer-permissions.test.ts
@@ -6,6 +6,7 @@ const {
   askForMediaAccessMock,
   getMediaAccessStatusMock,
   isTrustedAccessibilityClientMock,
+  getMacosFullDiskAccessStatusMock,
   execFileMock,
   createSocketMock,
   socketMock,
@@ -28,6 +29,7 @@ const {
     askForMediaAccessMock: vi.fn(),
     getMediaAccessStatusMock: vi.fn(),
     isTrustedAccessibilityClientMock: vi.fn(),
+    getMacosFullDiskAccessStatusMock: vi.fn(),
     execFileMock: vi.fn(),
     createSocketMock: vi.fn(() => socketMock),
     socketMock,
@@ -59,6 +61,10 @@ vi.mock('node:child_process', () => ({
   execFile: execFileMock
 }))
 
+vi.mock('../macos-full-disk-access-status', () => ({
+  getMacosFullDiskAccessStatus: getMacosFullDiskAccessStatusMock
+}))
+
 import { registerDeveloperPermissionHandlers } from './developer-permissions'
 
 describe('registerDeveloperPermissionHandlers', () => {
@@ -72,6 +78,8 @@ describe('registerDeveloperPermissionHandlers', () => {
     askForMediaAccessMock.mockReset()
     getMediaAccessStatusMock.mockReset()
     isTrustedAccessibilityClientMock.mockReset()
+    getMacosFullDiskAccessStatusMock.mockReset()
+    getMacosFullDiskAccessStatusMock.mockResolvedValue('denied')
     execFileMock.mockReset()
     execFileMock.mockImplementation((...args: unknown[]) => {
       const callback = args.at(-1)
@@ -119,6 +127,21 @@ describe('registerDeveloperPermissionHandlers', () => {
     return call[1] as (_event: unknown, args: { id: string }) => Promise<unknown>
   }
 
+  it('returns the Full Disk Access read-probe status', async () => {
+    getMacosFullDiskAccessStatusMock.mockResolvedValue('granted')
+    registerDeveloperPermissionHandlers()
+
+    const call = handleMock.mock.calls.find(
+      (registration: unknown[]) => registration[0] === 'developerPermissions:getStatus'
+    )
+    const handler = call?.[1] as (() => Promise<unknown>) | undefined
+
+    await expect(handler?.()).resolves.toContainEqual({
+      id: 'full-disk-access',
+      status: 'granted'
+    })
+  })
+
   it('clears the local-network prompt fallback timer when UDP send settles first', async () => {
     registerDeveloperPermissionHandlers()
 
diff --git a/src/main/ipc/developer-permissions.ts b/src/main/ipc/developer-permissions.ts
index d0d079bd093..dc1171b8c7d 100644
--- a/src/main/ipc/developer-permissions.ts
+++ b/src/main/ipc/developer-permissions.ts
@@ -1,9 +1,7 @@
 import { execFile } from 'node:child_process'
 import dgram from 'node:dgram'
-import { access } from 'node:fs/promises'
-import { homedir } from 'node:os'
-import path from 'node:path'
 import { ipcMain, shell, systemPreferences } from 'electron'
+import { getMacosFullDiskAccessStatus } from '../macos-full-disk-access-status'
 import type {
   DeveloperPermissionId,
   DeveloperPermissionRequestResult,
@@ -50,21 +48,6 @@ function getMediaStatus(mediaType: 'microphone' | 'camera' | 'screen'): Develope
   }
 }
 
-async function getFullDiskAccessStatus(): Promise<DeveloperPermissionStatus> {
-  const unsupported = unsupportedOffMac()
-  if (unsupported) {
-    return unsupported
-  }
-  try {
-    // Why: Safari bookmarks are TCC-protected, so read access is a practical
-    // Full Disk Access signal without touching user project contents.
-    await access(path.join(homedir(), 'Library', 'Safari', 'Bookmarks.plist'))
-    return 'granted'
-  } catch {
-    return 'unknown'
-  }
-}
-
 function getAccessibilityStatus(): DeveloperPermissionStatus {
   const unsupported = unsupportedOffMac()
   if (unsupported) {
@@ -165,7 +148,7 @@ async function getPermissionState(id: DeveloperPermissionId): Promise<DeveloperP
     case 'accessibility':
       return { id, status: getAccessibilityStatus() }
     case 'full-disk-access':
-      return { id, status: await getFullDiskAccessStatus() }
+      return { id, status: await getMacosFullDiskAccessStatus() }
     case 'automation':
     case 'local-network':
       return { id, status: unsupportedOffMac() ?? 'unknown' }
diff --git a/src/main/macos-full-disk-access-status.test.ts b/src/main/macos-full-disk-access-status.test.ts
new file mode 100644
index 00000000000..978390c3932
--- /dev/null
+++ b/src/main/macos-full-disk-access-status.test.ts
@@ -0,0 +1,63 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { join } from 'node:path'
+import {
+  getMacosFullDiskAccessStatus,
+  probeMacosFullDiskAccess
+} from './macos-full-disk-access-status'
+
+const originalPlatform = process.platform
+const homeDirectory = join('Users', 'tester')
+const databasePath = join(
+  homeDirectory,
+  'Library',
+  'Application Support',
+  'com.apple.TCC',
+  'TCC.db'
+)
+
+function fileSystemError(code: string): NodeJS.ErrnoException {
+  return Object.assign(new Error(code), { code })
+}
+
+afterEach(() => {
+  Object.defineProperty(process, 'platform', { configurable: true, value: originalPlatform })
+})
+
+describe('probeMacosFullDiskAccess', () => {
+  it('reports granted only when the TCC database opens for reading', async () => {
+    const readProbe = vi.fn().mockResolvedValue(undefined)
+
+    await expect(probeMacosFullDiskAccess({ homeDirectory, readProbe })).resolves.toBe('granted')
+    expect(readProbe).toHaveBeenCalledWith(databasePath)
+  })
+
+  it.each(['EACCES', 'EPERM'])('reports denied for %s', async (code) => {
+    await expect(
+      probeMacosFullDiskAccess({
+        homeDirectory,
+        readProbe: async () => {
+          throw fileSystemError(code)
+        }
+      })
+    ).resolves.toBe('denied')
+  })
+
+  it.each(['ENOENT', 'ENOTDIR', 'EBUSY'])('keeps %s failures unknown', async (code) => {
+    await expect(
+      probeMacosFullDiskAccess({
+        homeDirectory,
+        readProbe: async () => {
+          throw fileSystemError(code)
+        }
+      })
+    ).resolves.toBe('unknown')
+  })
+})
+
+describe('getMacosFullDiskAccessStatus', () => {
+  it('is unsupported off macOS', async () => {
+    Object.defineProperty(process, 'platform', { configurable: true, value: 'linux' })
+
+    await expect(getMacosFullDiskAccessStatus()).resolves.toBe('unsupported')
+  })
+})
diff --git a/src/main/macos-full-disk-access-status.ts b/src/main/macos-full-disk-access-status.ts
new file mode 100644
index 00000000000..aea18b95677
--- /dev/null
+++ b/src/main/macos-full-disk-access-status.ts
@@ -0,0 +1,44 @@
+import { open } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import type { DeveloperPermissionStatus } from '../shared/developer-permissions-types'
+
+type ReadProbe = (filePath: string) => Promise<void>
+
+async function openForRead(filePath: string): Promise<void> {
+  const handle = await open(filePath, 'r')
+  await handle.close()
+}
+
+function errorCode(error: unknown): string | undefined {
+  return error instanceof Error && 'code' in error
+    ? (error as NodeJS.ErrnoException).code
+    : undefined
+}
+
+export async function probeMacosFullDiskAccess({
+  homeDirectory = homedir(),
+  readProbe = openForRead
+}: {
+  homeDirectory?: string
+  readProbe?: ReadProbe
+} = {}): Promise<DeveloperPermissionStatus> {
+  const databasePath = join(
+    homeDirectory,
+    'Library',
+    'Application Support',
+    'com.apple.TCC',
+    'TCC.db'
+  )
+  try {
+    await readProbe(databasePath)
+    return 'granted'
+  } catch (error) {
+    const code = errorCode(error)
+    return code === 'EACCES' || code === 'EPERM' ? 'denied' : 'unknown'
+  }
+}
+
+export async function getMacosFullDiskAccessStatus(): Promise<DeveloperPermissionStatus> {
+  return process.platform === 'darwin' ? probeMacosFullDiskAccess() : 'unsupported'
+}
diff --git a/src/main/macos-tcc-prompt-notice.test.ts b/src/main/macos-tcc-prompt-notice.test.ts
index 1c268a7e240..e8745b67c61 100644
--- a/src/main/macos-tcc-prompt-notice.test.ts
+++ b/src/main/macos-tcc-prompt-notice.test.ts
@@ -30,6 +30,7 @@ vi.mock('node:fs', async (importOriginal) => ({
 
 const {
   TCC_PROMPT_NOTICE_THRESHOLD,
+  TCC_PROMPT_NOTICE_VERSION,
   TCC_PROMPT_WATCH_START_FALLBACK_MS,
   acknowledgePendingTccPromptNotice,
   consumePendingTccPromptNotice,
@@ -67,7 +68,11 @@ describe('tcc prompt notice threshold', () => {
     handleTccPromptForTests()
     expect(writeFileAtomically).toHaveBeenCalledTimes(1)
     const [, contents] = writeFileAtomically.mock.calls[0] as [string, string]
-    expect(JSON.parse(contents)).toMatchObject({ promptCount: 1, notified: false })
+    expect(JSON.parse(contents)).toMatchObject({
+      noticeVersion: TCC_PROMPT_NOTICE_VERSION,
+      promptCount: 1,
+      notified: false
+    })
   })
 
   it('never fires again once dismissed, even past the threshold', () => {
@@ -303,9 +308,9 @@ describe('tcc prompt notice threshold', () => {
   })
 
   it.each([
-    { promptCount: 2, notified: false },
-    { promptCount: 1, notified: true }
-  ])('requires a fresh detection for a legacy tally: $promptCount/$notified', (persisted) => {
+    { promptCount: 2, notified: false, acknowledgedAfterClose: false },
+    { promptCount: 1, notified: true, acknowledgedAfterClose: true }
+  ])('re-arms a legacy tally after a fresh detection: $promptCount/$notified', (persisted) => {
     const platform = Object.getOwnPropertyDescriptor(process, 'platform')
     Object.defineProperty(process, 'platform', { configurable: true, value: 'darwin' })
     readTallyFile.mockReturnValue(JSON.stringify({ ...persisted, dismissed: false }))
@@ -329,11 +334,35 @@ describe('tcc prompt notice threshold', () => {
     }
   })
 
+  it('preserves a legacy permanent opt-out', () => {
+    const platform = Object.getOwnPropertyDescriptor(process, 'platform')
+    Object.defineProperty(process, 'platform', { configurable: true, value: 'darwin' })
+    readTallyFile.mockReturnValue(
+      JSON.stringify({
+        promptCount: 1,
+        notified: true,
+        dismissed: true,
+        acknowledgedAfterClose: true
+      })
+    )
+    try {
+      const mainWindow = createWindowStub()
+      initTccPromptNotice(mainWindow as never)
+
+      expect(watchStart).not.toHaveBeenCalled()
+      expect(mainWindow.webContents.send).not.toHaveBeenCalled()
+      expect(consumePendingTccPromptNotice(1)).toBeNull()
+    } finally {
+      Object.defineProperty(process, 'platform', platform!)
+    }
+  })
+
   it('replays an unclosed notice from the new delivery contract', () => {
     const platform = Object.getOwnPropertyDescriptor(process, 'platform')
     Object.defineProperty(process, 'platform', { configurable: true, value: 'darwin' })
     readTallyFile.mockReturnValue(
       JSON.stringify({
+        noticeVersion: TCC_PROMPT_NOTICE_VERSION,
         promptCount: 1,
         notified: false,
         dismissed: false,
@@ -359,6 +388,7 @@ describe('tcc prompt notice threshold', () => {
     Object.defineProperty(process, 'platform', { configurable: true, value: 'darwin' })
     readTallyFile.mockReturnValue(
       JSON.stringify({
+        noticeVersion: TCC_PROMPT_NOTICE_VERSION,
         promptCount: 1,
         notified: true,
         dismissed: false,
diff --git a/src/main/macos-tcc-prompt-notice.ts b/src/main/macos-tcc-prompt-notice.ts
index 9d7dea359d0..c51367d8c6a 100644
--- a/src/main/macos-tcc-prompt-notice.ts
+++ b/src/main/macos-tcc-prompt-notice.ts
@@ -14,6 +14,9 @@ import { MacosTccPromptWatch } from './macos-tcc-prompt-watch'
 /** Why: the first detected dialog identifies an affected user; the notice remains one-time. */
 export const TCC_PROMPT_NOTICE_THRESHOLD = 1
 
+/** Why: re-arm users who may have trusted the former false-positive Full Disk Access badge. */
+export const TCC_PROMPT_NOTICE_VERSION = 2
+
 /** Why: preserve detection when Electron never emits `ready-to-show` without competing with startup. */
 export const TCC_PROMPT_WATCH_START_FALLBACK_MS = 10_000
 
@@ -28,6 +31,7 @@ export type TccPromptNoticeClaim = TccPromptNoticePayload & {
 }
 
 type TccPromptTally = {
+  noticeVersion: number
   promptCount: number
   notified: boolean
   dismissed: boolean
@@ -35,6 +39,7 @@ type TccPromptTally = {
 }
 
 const EMPTY_TALLY: TccPromptTally = {
+  noticeVersion: TCC_PROMPT_NOTICE_VERSION,
   promptCount: 0,
   notified: false,
   dismissed: false,
@@ -57,15 +62,28 @@ function loadTally(): TccPromptTally {
   try {
     const parsed = JSON.parse(readFileSync(tallyPath(), 'utf-8')) as Partial<TccPromptTally>
     const dismissed = parsed.dismissed === true
-    if (!dismissed && typeof parsed.acknowledgedAfterClose !== 'boolean') {
-      // Why: a legacy tally only proves a past prompt, not that Full Disk Access is still missing.
+    if (dismissed) {
+      return {
+        noticeVersion: TCC_PROMPT_NOTICE_VERSION,
+        promptCount: typeof parsed.promptCount === 'number' ? parsed.promptCount : 0,
+        notified: true,
+        dismissed: true,
+        acknowledgedAfterClose: true
+      }
+    }
+    if (parsed.noticeVersion !== TCC_PROMPT_NOTICE_VERSION) {
+      return { ...EMPTY_TALLY }
+    }
+    if (typeof parsed.acknowledgedAfterClose !== 'boolean') {
+      // Why: an incomplete tally proves only a past prompt, not that access is still missing.
       return { ...EMPTY_TALLY }
     }
     const acknowledgedAfterClose = parsed.acknowledgedAfterClose === true
     return {
+      noticeVersion: TCC_PROMPT_NOTICE_VERSION,
       promptCount: typeof parsed.promptCount === 'number' ? parsed.promptCount : 0,
-      notified: parsed.notified === true && (dismissed || acknowledgedAfterClose),
-      dismissed,
+      notified: parsed.notified === true && acknowledgedAfterClose,
+      dismissed: false,
       acknowledgedAfterClose
     }
   } catch {

From f23b3308a5eb23855b4d7f4e676e1405568b4a99 Mon Sep 17 00:00:00 2001
From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com>
Date: Fri, 31 Jul 2026 00:54:40 -0700
Subject: [PATCH 08/23] fix(mobile): route external mouse click and drag to the
 terminal (#11473)

* fix(mobile): route external mouse click and drag to the terminal

The terminal WebView suppresses mousedown/click at capture so xterm's own
mouse handling stays inert (its onData bytes are dropped by the mobile
bridge). That left hardware mouse clicks and drags with no path at all:
touch taps reached mouse-aware TUIs and drove selection, while a Bluetooth
mouse or trackpad click did nothing (#8818; wheel half landed in #11247).

Add a pointer-event router on the terminal surface (pointerType 'mouse',
left button only) that mirrors touch semantics:

- plain click: same pipeline as a touch tap (links/file paths first, then
  tracking-mode press+release reports, else keyboard focus), and a click
  on an active selection dismisses it like touch does
- drag with mouse tracking: press at the anchor, per-cell motion reports
  (drag/any modes), release on pointerup or pointercancel
- drag without tracking: character-anchored selection reusing the touch
  handle-drag plumbing (edge scroll, handles, copy pill)

Widen the RN gesture-input grammar to pass left-drag motion reports
(SGR button 32, default-encoding byte 64) through the existing
validation and rate limiting.

Mock server: echo the subscribe viewport and serialize scrollback so the
session screen leaves the resubscribe loop, serve the session-tabs
subscribe stream, and add a MOCK_TUI=1 mouse-tracking scenario plus a
[SEND] byte log - the rig used to reproduce and verify this fix on an
Android emulator.

Fixes #8818

* fix(mobile): capture the mouse pointer and clear stale gestures on pointerdown

A drag leaving the terminal surface dropped pointermove/pointerup without
pointer capture, stranding the gesture; a pointerup lost outside the
WebView could leave a tracked press latched until the next gesture.

* fix(mobile): end mouse gestures whose pointerup never reached the surface

Capture the mouse pointer on pointerdown so a drag that leaves the surface
keeps delivering pointermove/pointerup; when capture is unavailable and the
release is lost anyway, synthesize the release from the next buttons==0
pointermove or the next pointerdown, so a tracking TUI is never left with
the left button latched down.

* fix(mock-server): clear the terminal stream interval on resubscribe and unsubscribe

* fix(mobile): synthesize the lost-pointerup release at the pointer's current cell

* test(mobile): split terminal mouse click and drag coverage

* test(mobile): satisfy changed-line quality checks

* fix(mobile): cancel stale mock terminal callbacks

* refactor(mobile): extract mouse report cell mapping
---
 mobile/scripts/mock-server-rpc-handlers.ts    |  60 +----
 .../mock-server-session-tabs-fixture.ts       |  24 +-
 mobile/scripts/mock-server-terminal-stream.ts | 132 ++++++++++
 ...erver-terminal-stream-cancellation.test.ts |  74 ++++++
 .../terminal/terminal-gesture-input.test.ts   |  16 ++
 mobile/src/terminal/terminal-gesture-input.ts |   6 +-
 mobile/src/terminal/terminal-webview-html.ts  |  33 +--
 ...minal-webview-mouse-click-drag-injected.ts | 199 ++++++++++++++
 .../terminal-webview-mouse-click.test.ts      |  90 +++++++
 .../terminal-webview-mouse-drag.test.ts       |  87 ++++++
 ...inal-webview-mouse-report-cell-injected.ts |  29 ++
 .../terminal-webview-mouse-test-harness.ts    | 248 ++++++++++++++++++
 12 files changed, 919 insertions(+), 79 deletions(-)
 create mode 100644 mobile/scripts/mock-server-terminal-stream.ts
 create mode 100644 mobile/src/terminal/mock-server-terminal-stream-cancellation.test.ts
 create mode 100644 mobile/src/terminal/terminal-webview-mouse-click-drag-injected.ts
 create mode 100644 mobile/src/terminal/terminal-webview-mouse-click.test.ts
 create mode 100644 mobile/src/terminal/terminal-webview-mouse-drag.test.ts
 create mode 100644 mobile/src/terminal/terminal-webview-mouse-report-cell-injected.ts
 create mode 100644 mobile/src/terminal/terminal-webview-mouse-test-harness.ts

diff --git a/mobile/scripts/mock-server-rpc-handlers.ts b/mobile/scripts/mock-server-rpc-handlers.ts
index c5aebf054b4..5971b9dee94 100644
--- a/mobile/scripts/mock-server-rpc-handlers.ts
+++ b/mobile/scripts/mock-server-rpc-handlers.ts
@@ -13,11 +13,7 @@ import { handleMockGitRequest } from './mock-server-git-state'
 import { handleMockAccountRequest } from './mock-server-account-rpc'
 import { handleMockNativeChatRequest } from './mock-server-native-chat-scenario'
 import { handleMockSessionTabsRequest } from './mock-server-session-tabs-fixture'
-import {
-  createMockTerminals,
-  FAKE_SCROLLBACK,
-  STREAMING_CHUNKS
-} from './mock-server-terminal-fixtures'
+import { handleMockTerminalRequest } from './mock-server-terminal-stream'
 import { createMockRepos, createMockWorktrees, readScenarioNumber } from './mobile-lag-scenario'
 
 const MOCK_REPO_COUNT = readScenarioNumber('MOCK_REPO_COUNT', 2)
@@ -64,6 +60,8 @@ export type RpcResponse = {
   _meta: { runtimeId: string }
 }
 
+export type RpcRespond = (response: RpcResponse, shouldSend?: () => boolean) => void
+
 export const mockScenarioSummary = {
   repoCount: FAKE_REPOS.length,
   worktreeCount: fakeWorktrees.length,
@@ -111,13 +109,18 @@ export function handleRequest(
   send: (response: RpcResponse) => void,
   ws: WebSocket
 ): void {
-  const respond = (response: RpcResponse) => {
+  const respond: RpcRespond = (response, shouldSend) => {
+    const deliver = () => {
+      if (shouldSend?.() !== false) {
+        send(response)
+      }
+    }
     const delay = responseDelayFor(request.method)
     if (delay > 0) {
-      setTimeout(() => send(response), delay)
+      setTimeout(deliver, delay)
       return
     }
-    send(response)
+    deliver()
   }
 
   // Each returns false for methods it does not own; first owner wins.
@@ -126,7 +129,8 @@ export function handleRequest(
     handleMockFilePreviewRequest(request, respond, success, error) ||
     handleMockAccountRequest(request, respond, success, error) ||
     handleMockNativeChatRequest(request, respond, success, error, ws) ||
-    handleMockSessionTabsRequest(request, respond, success, terminalListWorktreeId)
+    handleMockSessionTabsRequest(request, respond, success, terminalListWorktreeId) ||
+    handleMockTerminalRequest(request, respond, success, ws, terminalListWorktreeId)
   ) {
     return
   }
@@ -279,44 +283,6 @@ export function handleRequest(
       break
     }
 
-    case 'terminal.list': {
-      const terminals = createMockTerminals(terminalListWorktreeId(request.params?.worktree))
-      respond(
-        success(request.id, {
-          terminals,
-          totalCount: terminals.length,
-          truncated: false
-        })
-      )
-      break
-    }
-
-    case 'terminal.subscribe': {
-      respond(success(request.id, { type: 'scrollback', lines: FAKE_SCROLLBACK, truncated: false }))
-
-      let chunkIndex = 0
-      const interval = setInterval(() => {
-        if (chunkIndex >= STREAMING_CHUNKS.length || ws.readyState !== ws.OPEN) {
-          clearInterval(interval)
-          if (ws.readyState === ws.OPEN) {
-            respond(success(request.id, { type: 'end' }))
-          }
-          return
-        }
-        respond(success(request.id, { type: 'data', chunk: STREAMING_CHUNKS[chunkIndex] }, true))
-        chunkIndex++
-      }, 500)
-      break
-    }
-
-    case 'terminal.send':
-      respond(success(request.id, { send: { handle: 'term-1', ok: true } }))
-      break
-
-    case 'terminal.unsubscribe':
-      respond(success(request.id, { unsubscribed: true }))
-      break
-
     case 'files.open':
     case 'files.openDiff':
       respond(
diff --git a/mobile/scripts/mock-server-session-tabs-fixture.ts b/mobile/scripts/mock-server-session-tabs-fixture.ts
index fbc94c2829e..f4a5bd1da1c 100644
--- a/mobile/scripts/mock-server-session-tabs-fixture.ts
+++ b/mobile/scripts/mock-server-session-tabs-fixture.ts
@@ -60,10 +60,24 @@ export function handleMockSessionTabsRequest(
   // absent or `id:`-prefixed selector means.
   resolveWorktreeId: (selector: unknown) => string | undefined
 ): boolean {
-  if (request.method !== 'session.tabs.list') {
-    return false
+  if (request.method === 'session.tabs.list') {
+    const worktreeId = resolveWorktreeId(request.params?.worktree) ?? 'mock'
+    respond(success(request.id, createMockSessionTabs(worktreeId)))
+    return true
   }
-  const worktreeId = resolveWorktreeId(request.params?.worktree) ?? 'mock'
-  respond(success(request.id, createMockSessionTabs(worktreeId)))
-  return true
+  if (request.method === 'session.tabs.subscribe') {
+    // Without a live stream the client's health loop keeps invalidating list
+    // fetches mid-flight (barrier bump on the failed probe), so the session
+    // screen never leaves 'Loading tabs'. snapshot then updated => 'live'.
+    const worktreeId = resolveWorktreeId(request.params?.worktree) ?? 'mock'
+    const snapshot = createMockSessionTabs(worktreeId)
+    respond(success(request.id, { type: 'snapshot', ...snapshot }, true))
+    respond(success(request.id, { type: 'updated', ...snapshot }, true))
+    return true
+  }
+  if (request.method === 'session.tabs.unsubscribe') {
+    respond(success(request.id, { unsubscribed: true }))
+    return true
+  }
+  return false
 }
diff --git a/mobile/scripts/mock-server-terminal-stream.ts b/mobile/scripts/mock-server-terminal-stream.ts
new file mode 100644
index 00000000000..f747ec59b21
--- /dev/null
+++ b/mobile/scripts/mock-server-terminal-stream.ts
@@ -0,0 +1,132 @@
+import type { WebSocket } from 'ws'
+import type { RpcRequest, RpcRespond, RpcResponse } from './mock-server-rpc-handlers'
+import {
+  createMockTerminals,
+  FAKE_SCROLLBACK,
+  STREAMING_CHUNKS
+} from './mock-server-terminal-fixtures'
+
+// Why: the client resubscribes on every viewport change; without cancellation
+// each resubscribe would stack another interval streaming under a dead request.
+type TerminalStream = { interval: ReturnType<typeof setInterval> | null }
+const terminalStreams = new WeakMap<WebSocket, Map<string, TerminalStream>>()
+
+function clearTerminalStream(ws: WebSocket, terminal: string): void {
+  const perTerminal = terminalStreams.get(ws)
+  const stream = perTerminal?.get(terminal)
+  if (stream) {
+    stopTerminalStreamInterval(stream)
+    perTerminal?.delete(terminal)
+  }
+}
+
+function beginTerminalStream(ws: WebSocket, terminal: string): TerminalStream {
+  clearTerminalStream(ws, terminal)
+  let perTerminal = terminalStreams.get(ws)
+  if (!perTerminal) {
+    perTerminal = new Map()
+    terminalStreams.set(ws, perTerminal)
+  }
+  const stream = { interval: null }
+  perTerminal.set(terminal, stream)
+  return stream
+}
+
+function isCurrentTerminalStream(ws: WebSocket, terminal: string, stream: TerminalStream): boolean {
+  return terminalStreams.get(ws)?.get(terminal) === stream && ws.readyState === ws.OPEN
+}
+
+function stopTerminalStreamInterval(stream: TerminalStream): void {
+  if (stream.interval !== null) {
+    clearInterval(stream.interval)
+    stream.interval = null
+  }
+}
+
+/** Terminal list/stream/input backend for the mock server. Returns false for
+ *  methods it does not own. */
+export function handleMockTerminalRequest(
+  request: RpcRequest,
+  respond: RpcRespond,
+  success: (id: string, result: unknown, streaming?: boolean) => RpcResponse,
+  ws: WebSocket,
+  // Shared with `session.tabs.list` so both surfaces agree on which worktree an
+  // absent or `id:`-prefixed selector means.
+  resolveWorktreeId: (selector: unknown) => string | undefined
+): boolean {
+  switch (request.method) {
+    case 'terminal.list': {
+      const terminals = createMockTerminals(resolveWorktreeId(request.params?.worktree))
+      respond(
+        success(request.id, {
+          terminals,
+          totalCount: terminals.length,
+          truncated: false
+        })
+      )
+      return true
+    }
+
+    case 'terminal.subscribe': {
+      const terminal = String(request.params?.terminal ?? 'term-1')
+      const stream = beginTerminalStream(ws, terminal)
+      const isCurrent = () => isCurrentTerminalStream(ws, terminal, stream)
+      // Why: the client resubscribes until scrollback echoes its viewport dims;
+      // the legacy `lines` shape left the session screen in that loop forever.
+      const viewport = request.params?.viewport as { cols?: number; rows?: number } | undefined
+      // MOCK_TUI=1 arms SGR drag mouse tracking (1002/1006) inside the scrollback
+      // itself so every xterm re-init re-enters the mode - used by mouse/touch
+      // input repros (#8818).
+      const tuiPreamble =
+        process.env.MOCK_TUI === '1'
+          ? '\x1b[?1002h\x1b[?1006h[mock] mouse tracking ON (1002/1006)\r\n'
+          : ''
+      respond(
+        success(request.id, {
+          type: 'scrollback',
+          cols: viewport?.cols ?? 80,
+          rows: viewport?.rows ?? 24,
+          serialized: FAKE_SCROLLBACK.replace(/\n/g, '\r\n') + tuiPreamble,
+          truncated: false
+        }),
+        isCurrent
+      )
+
+      let chunkIndex = 0
+      stream.interval = setInterval(() => {
+        if (!isCurrent()) {
+          stopTerminalStreamInterval(stream)
+          return
+        }
+        if (chunkIndex >= STREAMING_CHUNKS.length) {
+          // Why: no `end` event - a live terminal stream stays open, and `end`
+          // makes the client tear the subscription down and blank the pane.
+          stopTerminalStreamInterval(stream)
+          return
+        }
+        respond(
+          success(request.id, { type: 'data', chunk: STREAMING_CHUNKS[chunkIndex] }, true),
+          isCurrent
+        )
+        chunkIndex++
+      }, 500)
+      return true
+    }
+
+    case 'terminal.send':
+      // Input-routing repros (#8818) assert on the exact bytes reaching the host.
+      console.log(
+        `[SEND] terminal=${String(request.params?.terminal)} text=${JSON.stringify(request.params?.text)}`
+      )
+      respond(success(request.id, { send: { handle: 'term-1', ok: true } }))
+      return true
+
+    case 'terminal.unsubscribe':
+      clearTerminalStream(ws, String(request.params?.terminal ?? 'term-1'))
+      respond(success(request.id, { unsubscribed: true }))
+      return true
+
+    default:
+      return false
+  }
+}
diff --git a/mobile/src/terminal/mock-server-terminal-stream-cancellation.test.ts b/mobile/src/terminal/mock-server-terminal-stream-cancellation.test.ts
new file mode 100644
index 00000000000..66e4900fe7c
--- /dev/null
+++ b/mobile/src/terminal/mock-server-terminal-stream-cancellation.test.ts
@@ -0,0 +1,74 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { WebSocket } from 'ws'
+import { handleMockTerminalRequest } from '../../scripts/mock-server-terminal-stream'
+import {
+  handleRequest,
+  type RpcRequest,
+  type RpcRespond,
+  type RpcResponse
+} from '../../scripts/mock-server-rpc-handlers'
+
+type DeferredResponse = {
+  response: RpcResponse
+  shouldSend?: () => boolean
+}
+
+function success(id: string, result: unknown, streaming?: boolean): RpcResponse {
+  return {
+    id,
+    ok: true,
+    result,
+    ...(streaming ? { streaming: true as const } : {}),
+    _meta: { runtimeId: 'test' }
+  }
+}
+
+function request(id: string, method: string): RpcRequest {
+  return { id, method, params: { terminal: 'term-1', viewport: { cols: 80, rows: 24 } } }
+}
+
+describe('mock terminal stream cancellation', () => {
+  afterEach(() => {
+    vi.useRealTimers()
+    vi.unstubAllEnvs()
+  })
+
+  it('invalidates delayed frames after resubscribe and unsubscribe', () => {
+    vi.useFakeTimers()
+    const ws = { OPEN: 1, readyState: 1 } as unknown as WebSocket
+    const deferred: DeferredResponse[] = []
+    const respond: RpcRespond = (response, shouldSend) => {
+      deferred.push({ response, shouldSend })
+    }
+    const handle = (rpcRequest: RpcRequest) =>
+      handleMockTerminalRequest(rpcRequest, respond, success, ws, () => 'wt')
+
+    expect(handle(request('old', 'terminal.subscribe'))).toBe(true)
+    vi.advanceTimersByTime(500)
+    expect(deferred.filter(({ response }) => response.id === 'old')).toHaveLength(2)
+
+    expect(handle(request('new', 'terminal.subscribe'))).toBe(true)
+    const oldResponses = deferred.filter(({ response }) => response.id === 'old')
+    const newResponses = deferred.filter(({ response }) => response.id === 'new')
+    expect(oldResponses.every(({ shouldSend }) => shouldSend?.() === false)).toBe(true)
+    expect(newResponses.every(({ shouldSend }) => shouldSend?.() === true)).toBe(true)
+
+    expect(handle(request('stop', 'terminal.unsubscribe'))).toBe(true)
+    expect(newResponses.every(({ shouldSend }) => shouldSend?.() === false)).toBe(true)
+  })
+
+  it('drops queued delayed frames after stream cancellation', () => {
+    vi.useFakeTimers()
+    vi.stubEnv('MOCK_RPC_DELAY_TERMINAL_SUBSCRIBE_MS', '1000')
+    const ws = { OPEN: 1, readyState: 1 } as unknown as WebSocket
+    const send = vi.fn<(response: RpcResponse) => void>()
+
+    handleRequest(request('old', 'terminal.subscribe'), send, ws)
+    vi.advanceTimersByTime(500)
+    handleRequest(request('new', 'terminal.subscribe'), send, ws)
+    handleRequest(request('stop', 'terminal.unsubscribe'), send, ws)
+
+    vi.advanceTimersByTime(1000)
+    expect(send.mock.calls.map(([response]) => response.id)).toEqual(['stop'])
+  })
+})
diff --git a/mobile/src/terminal/terminal-gesture-input.test.ts b/mobile/src/terminal/terminal-gesture-input.test.ts
index a120d569db9..a920f37a7a3 100644
--- a/mobile/src/terminal/terminal-gesture-input.test.ts
+++ b/mobile/src/terminal/terminal-gesture-input.test.ts
@@ -27,6 +27,22 @@ describe('isTerminalGestureInput', () => {
     expect(isTerminalGestureInput(`${ESC}[<0;9999;9999M${ESC}[<0;9999;9999m`)).toBe(true)
   })
 
+  it('accepts SGR left-drag motion sequences but rejects a motion release', () => {
+    expect(isTerminalGestureInput(`${ESC}[<32;10;5M${ESC}[<32;11;5M`)).toBe(true)
+    expect(countTerminalGestureInputSequences(`${ESC}[<32;10;5M${ESC}[<32;11;5M`)).toBe(2)
+    expect(isTerminalGestureInput(`${ESC}[<0;10;5M${ESC}[<32;11;5M${ESC}[<0;11;5m`)).toBe(true)
+    expect(isTerminalGestureInput(`${ESC}[<32;10;5m`)).toBe(false)
+  })
+
+  it('accepts default-encoding left-drag motion sequences', () => {
+    expect(isTerminalGestureInput(`${ESC}[M${String.fromCharCode(64, 43, 38)}`)).toBe(true)
+    expect(
+      isTerminalGestureInput(
+        `${ESC}[M${String.fromCharCode(32, 33, 33)}${ESC}[M${String.fromCharCode(64, 34, 33)}${ESC}[M${String.fromCharCode(35, 34, 33)}`
+      )
+    ).toBe(true)
+  })
+
   it('accepts repeated default mouse wheel sequences', () => {
     expect(
       isTerminalGestureInput(
diff --git a/mobile/src/terminal/terminal-gesture-input.ts b/mobile/src/terminal/terminal-gesture-input.ts
index 6b84c4824fe..6af8a2367f9 100644
--- a/mobile/src/terminal/terminal-gesture-input.ts
+++ b/mobile/src/terminal/terminal-gesture-input.ts
@@ -1,8 +1,9 @@
 const ESC = '\x1b'
 const MAX_TERMINAL_GESTURE_INPUT_LENGTH = 2048
 const MAX_TERMINAL_GESTURE_INPUT_SEQUENCES = 32
+// Buttons: 0 left press/release, 32 left-drag motion, 64/65 wheel.
 const SGR_MOUSE_GESTURE_SEQUENCE_RE = new RegExp(
-  `^${ESC}\\[<(0|64|65);([0-9]{1,4});([0-9]{1,4})([Mm])$`
+  `^${ESC}\\[<(0|32|64|65);([0-9]{1,4});([0-9]{1,4})([Mm])$`
 )
 
 function isDefaultMouseGestureSequence(bytes: string, offset: number): number | null {
@@ -12,8 +13,9 @@ function isDefaultMouseGestureSequence(bytes: string, offset: number): number |
   const button = bytes.charCodeAt(offset + 3)
   const col = bytes.charCodeAt(offset + 4)
   const row = bytes.charCodeAt(offset + 5)
+  // Buttons: 32 left press, 35 release, 64 left-drag motion, 96/97 wheel.
   if (
-    (button === 32 || button === 35 || button === 96 || button === 97) &&
+    (button === 32 || button === 35 || button === 64 || button === 96 || button === 97) &&
     col >= 33 &&
     col <= 126 &&
     row >= 33 &&
diff --git a/mobile/src/terminal/terminal-webview-html.ts b/mobile/src/terminal/terminal-webview-html.ts
index e8409cb3bee..a7715e4f564 100644
--- a/mobile/src/terminal/terminal-webview-html.ts
+++ b/mobile/src/terminal/terminal-webview-html.ts
@@ -11,6 +11,8 @@ import { TERMINAL_WEBVIEW_THEME_JS } from './terminal-webview-theme-injected'
 import { TERMINAL_QUERY_REPLY_JS } from './terminal-webview-query-reply-injected'
 import { URL_TAP_WEBVIEW_JS } from './terminal-webview-url-tap'
 import { TERMINAL_WEBGL_RECOVERY_JS } from './terminal-webview-webgl-recovery-injected'
+import { TERMINAL_MOUSE_CLICK_DRAG_JS } from './terminal-webview-mouse-click-drag-injected'
+import { TERMINAL_MOUSE_REPORT_CELL_JS } from './terminal-webview-mouse-report-cell-injected'
 import { TERMINAL_WHEEL_SCROLL_JS } from './terminal-webview-wheel-scroll-injected'
 
 const DEFAULT_TERMINAL_THEME: RuntimeMobileTerminalTheme['theme'] = {
@@ -1153,31 +1155,7 @@ ${TERMINAL_WEBGL_RECOVERY_JS}
     return { col: col, row: viewportRow + viewportY };
   }
 
-  function viewportToMouseReportCell(clientX, clientY) {
-    if (!term) return null;
-    var cellW = getCellWidth();
-    var cellH = getCellHeight();
-    if (cellW <= 0 || cellH <= 0) return null;
-    if (typeof clientX !== 'number') clientX = window.innerWidth / 2;
-    if (typeof clientY !== 'number') clientY = window.innerHeight / 2;
-    var total = getTotalScale();
-    if (total <= 0) total = 1;
-    var sx = (clientX - panX) / total;
-    var sy = (clientY - panY) / total;
-    var maxX = Math.max(0, term.cols * cellW - 1);
-    var maxY = Math.max(0, term.rows * cellH - 1);
-    if (sx < 0) sx = 0;
-    if (sx > maxX) sx = maxX;
-    if (sy < 0) sy = 0;
-    if (sy > maxY) sy = maxY;
-    var col = Math.floor(sx / cellW);
-    var row = Math.floor(sy / cellH);
-    if (col < 0) col = 0;
-    if (col > term.cols - 1) col = term.cols - 1;
-    if (row < 0) row = 0;
-    if (row > term.rows - 1) row = term.rows - 1;
-    return { col: col, row: row, x: Math.floor(sx), y: Math.floor(sy) };
-  }
+  ${TERMINAL_MOUSE_REPORT_CELL_JS}
 
   function isAlternateBufferActive() {
     try {
@@ -1648,6 +1626,10 @@ ${TERMINAL_WEBGL_RECOVERY_JS}
   // terminal-webview-wheel-scroll-injected.ts (extracted for max-lines).
   ${TERMINAL_WHEEL_SCROLL_JS}
 
+  // External mouse click/drag: see
+  // terminal-webview-mouse-click-drag-injected.ts (extracted for max-lines).
+  ${TERMINAL_MOUSE_CLICK_DRAG_JS}
+
   btnCopy.addEventListener('click', function(e) {
     e.preventDefault();
     e.stopPropagation();
@@ -1705,6 +1687,7 @@ ${TERMINAL_WEBGL_RECOVERY_JS}
     targetSurface.addEventListener('click', function(e) { e.preventDefault(); e.stopPropagation(); }, true);
 
     attachSurfaceWheelHandler(targetSurface);
+    attachSurfaceMouseClickDragHandler(targetSurface);
 
     targetSurface.addEventListener('touchstart', function(e) {
       if (dispatcherShouldBlockSurface()) return;
diff --git a/mobile/src/terminal/terminal-webview-mouse-click-drag-injected.ts b/mobile/src/terminal/terminal-webview-mouse-click-drag-injected.ts
new file mode 100644
index 00000000000..bc9c12aa016
--- /dev/null
+++ b/mobile/src/terminal/terminal-webview-mouse-click-drag-injected.ts
@@ -0,0 +1,199 @@
+// Indirect-pointer (external mouse / trackpad) click and drag for the terminal
+// surface, injected into XTERM_HTML. Extracted from terminal-webview-html.ts to
+// keep that file within its max-lines budget. Companion to
+// terminal-webview-wheel-scroll-injected.ts, which owns the wheel half (#11247);
+// this owns the click/drag half of #8818. Closes over host-IIFE state/functions:
+// term, ESC, sel, selMode, selectionOverlay, TAP_SLOP, getMouseTrackingMode,
+// viewportToCell, viewportToMouseReportCell, isSafeSgrMouseCoordinate,
+// sgrMouseMode, sgrMousePixelsMode, notify, notifyTerminalSurfaceTap,
+// cancelSelect, applyXtermSelection, repositionOverlay, handleDragMove,
+// stopEdgeScroll, and dispatcherShouldBlockSurface.
+//
+// Why pointer events: a hardware mouse on Android/iPadOS raises pointer events
+// with pointerType 'mouse' and NO touch events, while a finger raises
+// pointerType 'touch' plus the touch events the document dispatcher owns. The
+// capture-phase mousedown/click suppression in attachSurfaceEventHandlers stays:
+// it is what keeps xterm's own mouse handling inert (its onData output is
+// dropped by the mobile bridge), and pointer events are unaffected by it.
+export const TERMINAL_MOUSE_CLICK_DRAG_JS = `
+  var mouseGesture = null;
+
+  // One report per transition, built with the same encoding ladder as
+  // buildMouseClickInput: SGR pixels (1016) > SGR (1006) > default. Returns ''
+  // when the mode does not report this transition (x10 has no release, only
+  // drag/any report motion) or the cell is not encodable.
+  function buildMouseButtonReport(kind, clientX, clientY) {
+    var mouseTrackingMode = getMouseTrackingMode();
+    if (mouseTrackingMode === 'none') return '';
+    if (kind === 'motion' && mouseTrackingMode !== 'drag' && mouseTrackingMode !== 'any') return '';
+    if (kind === 'release' && mouseTrackingMode === 'x10') return '';
+    var cell = viewportToMouseReportCell(clientX, clientY);
+    if (!cell) return '';
+    var sgrButton = kind === 'motion' ? 32 : 0;
+    var sgrFinal = kind === 'release' ? 'm' : 'M';
+    if (sgrMousePixelsMode) {
+      if (!isSafeSgrMouseCoordinate(cell.x) || !isSafeSgrMouseCoordinate(cell.y)) return '';
+      return ESC + '[<' + sgrButton + ';' + cell.x + ';' + cell.y + sgrFinal;
+    }
+    if (sgrMouseMode) {
+      // Why: xterm increments zero-based mouse cells before encoding reports.
+      var sgrCol = cell.col + 1;
+      var sgrRow = cell.row + 1;
+      if (!isSafeSgrMouseCoordinate(sgrCol) || !isSafeSgrMouseCoordinate(sgrRow)) return '';
+      return ESC + '[<' + sgrButton + ';' + sgrCol + ';' + sgrRow + sgrFinal;
+    }
+    var button = kind === 'motion' ? 64 : kind === 'release' ? 35 : 32;
+    var col = cell.col + 1 + 32;
+    var row = cell.row + 1 + 32;
+    // Why: non-SGR mouse bytes above ASCII are not preserved reliably through
+    // the mobile JSON/RPC string path; drop instead of corrupting input.
+    if (col > 126 || row > 126) return '';
+    return ESC + '[M' + String.fromCharCode(button) + String.fromCharCode(col) + String.fromCharCode(row);
+  }
+
+  function mouseReportCellKey(clientX, clientY) {
+    var cell = viewportToMouseReportCell(clientX, clientY);
+    return cell ? cell.col + ',' + cell.row : null;
+  }
+
+  function abandonMouseGesture() {
+    var gesture = mouseGesture;
+    mouseGesture = null;
+    if (!gesture) return;
+    if (gesture.mode === 'tracking') {
+      // Why: the press report already went to the TUI; a lost pointer must not
+      // leave the button latched down on the far side.
+      var release = buildMouseButtonReport('release', gesture.lastX, gesture.lastY);
+      if (release) notify({ type: 'terminal-input', bytes: release });
+    } else if (gesture.mode === 'selecting') {
+      if (sel) sel.activeHandle = null;
+      stopEdgeScroll();
+    }
+  }
+
+  function beginMouseDrag(gesture) {
+    gesture.moved = true;
+    if (getMouseTrackingMode() !== 'none') {
+      gesture.mode = 'tracking';
+      gesture.lastCellKey = mouseReportCellKey(gesture.startX, gesture.startY);
+      var press = buildMouseButtonReport('press', gesture.startX, gesture.startY);
+      if (press) notify({ type: 'terminal-input', bytes: press });
+      return;
+    }
+    var anchor = viewportToCell(gesture.startX, gesture.startY);
+    if (!anchor) {
+      gesture.mode = 'cancelled';
+      return;
+    }
+    // Why: mouse drags select character-anchored ranges like desktop terminals,
+    // not the word-seeded long-press selection; reuse the touch handle-drag
+    // plumbing (edge scroll included) by acting as a live 'end' handle.
+    gesture.mode = 'selecting';
+    selMode = 'select';
+    sel = { anchor: anchor, focus: anchor, activeHandle: 'end' };
+    selectionOverlay.classList.add('active');
+    notify({ type: 'set-select-mode', enabled: true });
+    applyXtermSelection();
+    repositionOverlay();
+  }
+
+  function attachSurfaceMouseClickDragHandler(targetSurface) {
+    targetSurface.addEventListener('pointerdown', function(e) {
+      if (e.pointerType !== 'mouse' || e.button !== 0) return;
+      if (dispatcherShouldBlockSurface() || !term) return;
+      // Why: a pointerup lost outside the WebView must not leave the previous
+      // gesture latched (tracking press with no release) when the next one lands.
+      if (mouseGesture) abandonMouseGesture();
+      // Why: mouse pointers have no implicit capture; without it a drag that
+      // leaves the surface drops pointermove/pointerup and strands the gesture.
+      try {
+        if (targetSurface.setPointerCapture) targetSurface.setPointerCapture(e.pointerId);
+      } catch (err) {}
+      mouseGesture = {
+        startX: e.clientX, startY: e.clientY,
+        lastX: e.clientX, lastY: e.clientY,
+        lastCellKey: null,
+        moved: false,
+        mode: 'pending',
+        dismissedSelection: false
+      };
+      if (selMode === 'select') {
+        // Why: touch parity — pressing outside the pill dismisses the current
+        // selection; the same press may still start a new drag selection.
+        cancelSelect();
+        mouseGesture.dismissedSelection = true;
+      }
+    }, true);
+
+    targetSurface.addEventListener('pointermove', function(e) {
+      var gesture = mouseGesture;
+      if (e.pointerType !== 'mouse' || !gesture || gesture.mode === 'cancelled') return;
+      if (!term) return;
+      gesture.lastX = e.clientX;
+      gesture.lastY = e.clientY;
+      if ((e.buttons & 1) === 0) {
+        // Why: a pointerup lost outside the WebView (capture unavailable) must
+        // end the gesture here, or a tracked press stays latched at the TUI.
+        // Coordinates first, so the synthesized release lands where the
+        // pointer re-entered rather than at the previous cell.
+        abandonMouseGesture();
+        return;
+      }
+      if (!gesture.moved) {
+        var dx = Math.abs(e.clientX - gesture.startX);
+        var dy = Math.abs(e.clientY - gesture.startY);
+        if (dx + dy <= TAP_SLOP) return;
+        beginMouseDrag(gesture);
+      }
+      if (gesture.mode === 'tracking') {
+        // Why: one motion report per cell keeps drags bounded by grid size, not
+        // by pointermove cadence, so the RN rate limiter is never the bottleneck.
+        var cellKey = mouseReportCellKey(e.clientX, e.clientY);
+        if (cellKey && cellKey !== gesture.lastCellKey) {
+          gesture.lastCellKey = cellKey;
+          var motion = buildMouseButtonReport('motion', e.clientX, e.clientY);
+          if (motion) notify({ type: 'terminal-input', bytes: motion });
+        }
+      } else if (gesture.mode === 'selecting') {
+        handleDragMove('end', e.clientX, e.clientY);
+      }
+    }, true);
+
+    targetSurface.addEventListener('pointerup', function(e) {
+      var gesture = mouseGesture;
+      if (e.pointerType !== 'mouse' || !gesture || e.button !== 0) return;
+      mouseGesture = null;
+      if (gesture.mode === 'cancelled' || !term) return;
+      if (gesture.mode === 'tracking') {
+        var release = buildMouseButtonReport('release', e.clientX, e.clientY);
+        if (release) notify({ type: 'terminal-input', bytes: release });
+        return;
+      }
+      if (gesture.mode === 'selecting') {
+        if (sel) sel.activeHandle = null;
+        stopEdgeScroll();
+        repositionOverlay();
+        return;
+      }
+      if (dispatcherShouldBlockSurface()) return;
+      // Why: a dismissing tap only clears the selection (touch parity); it must
+      // not also open a link or focus the keyboard underneath.
+      if (gesture.dismissedSelection) return;
+      // Plain click == touch tap: links and file paths win, then tracking-mode
+      // click reports, then keyboard focus.
+      notifyTerminalSurfaceTap(e.clientX, e.clientY);
+    }, true);
+
+    targetSurface.addEventListener('pointercancel', function(e) {
+      if (e.pointerType !== 'mouse') return;
+      abandonMouseGesture();
+    }, true);
+
+    // Why: Android input injection can pair a mouse-flavored pointerdown with
+    // real touch events (SOURCE_MOUSE + TOOL_TYPE_FINGER). If touch arrives,
+    // the document touch dispatcher owns the gesture.
+    targetSurface.addEventListener('touchstart', function() {
+      if (mouseGesture) abandonMouseGesture();
+    }, true);
+  }
+`
diff --git a/mobile/src/terminal/terminal-webview-mouse-click.test.ts b/mobile/src/terminal/terminal-webview-mouse-click.test.ts
new file mode 100644
index 00000000000..bb2494b62e7
--- /dev/null
+++ b/mobile/src/terminal/terminal-webview-mouse-click.test.ts
@@ -0,0 +1,90 @@
+// @vitest-environment happy-dom
+import { describe, expect, it } from 'vitest'
+import { ESC, useTerminalMouseWebViewHarness } from './terminal-webview-mouse-test-harness'
+
+describe('terminal WebView external mouse click', () => {
+  const mouse = useTerminalMouseWebViewHarness()
+
+  it('reports a mouse click to a click-tracking TUI the way a touch tap does (#8818)', () => {
+    mouse.boot()
+    mouse.activeTerminal().modes.mouseTrackingMode = 'vt200'
+
+    mouse.mouseClick(40, 60)
+
+    // Default (non-SGR) encoding: press (32=' ') then release (35='#'), each
+    // ESC [ M btn col row. Cell bytes depend on the fit scale, not on routing.
+    const bytes = mouse.terminalInputBytes()
+    expect(bytes).toHaveLength(12)
+    expect(bytes.slice(0, 4)).toBe(`${ESC}[M `)
+    expect(bytes.slice(6, 10)).toBe(`${ESC}[M#`)
+    expect(bytes.slice(4, 6)).toBe(bytes.slice(10, 12))
+  })
+
+  it('dismisses an existing selection with a click without focusing the keyboard', () => {
+    mouse.boot()
+    mouse.mouseDrag(40, 60, 160, 90)
+    mouse.clearPostedMessages()
+
+    mouse.mouseClick(240, 200)
+
+    const messages = mouse.postedMessages()
+    expect(messages.filter((message) => message.type === 'set-select-mode')).toEqual([
+      { type: 'set-select-mode', enabled: false }
+    ])
+    expect(messages.filter((message) => message.type === 'terminal-tap')).toEqual([])
+    expect(document.getElementById('selection-overlay')?.classList.contains('active')).toBe(false)
+  })
+
+  it('routes a plain mouse click to the tap pipeline for keyboard focus', () => {
+    mouse.boot()
+
+    mouse.mouseClick(40, 60)
+
+    const messages = mouse.postedMessages()
+    expect(messages.filter((message) => message.type === 'terminal-tap')).toHaveLength(1)
+    expect(mouse.terminalInputBytes()).toBe('')
+  })
+
+  it('ignores non-mouse pointers and non-left buttons', () => {
+    mouse.boot()
+    mouse.activeTerminal().modes.mouseTrackingMode = 'vt200'
+
+    mouse.dispatchPointer('pointerdown', {
+      pointerType: 'touch',
+      x: 40,
+      y: 60,
+      button: 0,
+      buttons: 1
+    })
+    mouse.dispatchPointer('pointerup', {
+      pointerType: 'touch',
+      x: 40,
+      y: 60,
+      button: 0,
+      buttons: 0
+    })
+    mouse.dispatchPointer('pointerdown', { x: 40, y: 60, button: 2, buttons: 2 })
+    mouse.dispatchPointer('pointerup', { x: 40, y: 60, button: 2, buttons: 0 })
+
+    expect(mouse.terminalInputBytes()).toBe('')
+    expect(mouse.postedMessages().filter((message) => message.type === 'terminal-tap')).toEqual([])
+  })
+
+  it('lets the touch dispatcher own a gesture when touch events follow pointerdown', () => {
+    mouse.boot()
+    mouse.activeTerminal().modes.mouseTrackingMode = 'vt200'
+
+    mouse.dispatchPointer('pointerdown', { x: 40, y: 60, button: 0, buttons: 1 })
+    const touchStart = new Event('touchstart', { bubbles: true })
+    // Why: the document tap dispatcher reads touches[0]; happy-dom's plain Event lacks it.
+    Object.defineProperty(touchStart, 'touches', {
+      value: [{ identifier: 7, clientX: 40, clientY: 60 }]
+    })
+    mouse.terminalSurface().dispatchEvent(touchStart)
+    mouse.dispatchPointer('pointerup', { x: 40, y: 60, button: 0, buttons: 0 })
+
+    // Why: Android SOURCE_MOUSE injections can pair a mouse pointerdown with
+    // real touch events; double-handling would double the click report.
+    expect(mouse.terminalInputBytes()).toBe('')
+  })
+})
diff --git a/mobile/src/terminal/terminal-webview-mouse-drag.test.ts b/mobile/src/terminal/terminal-webview-mouse-drag.test.ts
new file mode 100644
index 00000000000..e4fac512873
--- /dev/null
+++ b/mobile/src/terminal/terminal-webview-mouse-drag.test.ts
@@ -0,0 +1,87 @@
+// @vitest-environment happy-dom
+import { describe, expect, it } from 'vitest'
+import {
+  DEFAULT_MOUSE_REPORT_RE,
+  ESC,
+  useTerminalMouseWebViewHarness
+} from './terminal-webview-mouse-test-harness'
+
+describe('terminal WebView external mouse drag', () => {
+  const mouse = useTerminalMouseWebViewHarness()
+
+  it('sends press, per-cell motion, and release for a drag-tracking mouse drag', () => {
+    mouse.boot()
+    mouse.activeTerminal().modes.mouseTrackingMode = 'drag'
+
+    mouse.mouseDrag(40, 60, 160, 60)
+
+    const reports = mouse.terminalInputBytes().match(DEFAULT_MOUSE_REPORT_RE) ?? []
+    expect(reports.length).toBeGreaterThanOrEqual(3)
+    expect(reports[0]?.charCodeAt(3)).toBe(32)
+    for (const motion of reports.slice(1, -1)) {
+      expect(motion.charCodeAt(3)).toBe(64)
+    }
+    expect(reports.at(-1)?.charCodeAt(3)).toBe(35)
+    // Motion reports are deduped per cell, so a horizontal drag advances columns.
+    const motionCols = reports.slice(1, -1).map((report) => report.charCodeAt(4))
+    expect(new Set(motionCols).size).toBe(motionCols.length)
+  })
+
+  it('does not report motion or release for an x10 click-only TUI drag', () => {
+    mouse.boot()
+    mouse.activeTerminal().modes.mouseTrackingMode = 'x10'
+
+    mouse.mouseDrag(40, 60, 160, 60)
+
+    // x10 reports presses only; the press goes out at drag start, no motion or release follows.
+    const bytes = mouse.terminalInputBytes()
+    expect(bytes.slice(0, 4)).toBe(`${ESC}[M `)
+    expect(bytes).toHaveLength(6)
+  })
+
+  it('selects character-anchored text on a mouse drag outside tracking mode', () => {
+    mouse.boot()
+    // Why: init itself emits a set-select-mode reset; only the drag matters here.
+    mouse.clearPostedMessages()
+
+    mouse.mouseDrag(40, 60, 160, 90)
+
+    expect(mouse.terminalInputBytes()).toBe('')
+    expect(mouse.selectionSpy()).toHaveBeenCalled()
+    expect(document.getElementById('selection-overlay')?.classList.contains('active')).toBe(true)
+    const modes = mouse.postedMessages().filter((message) => message.type === 'set-select-mode')
+    expect(modes).toEqual([{ type: 'set-select-mode', enabled: true }])
+  })
+
+  it('releases a tracked drag when the button state shows the pointerup was lost', () => {
+    mouse.boot()
+    mouse.activeTerminal().modes.mouseTrackingMode = 'drag'
+
+    mouse.dispatchPointer('pointerdown', { x: 40, y: 60, button: 0, buttons: 1 })
+    mouse.dispatchPointer('pointermove', { x: 160, y: 60, button: 0, buttons: 1 })
+    // Pointer re-enters with the button already up — the pointerup never arrived.
+    mouse.dispatchPointer('pointermove', { x: 200, y: 60, button: 0, buttons: 0 })
+
+    const reports = mouse.terminalInputBytes().match(DEFAULT_MOUSE_REPORT_RE) ?? []
+    expect(reports.at(-1)?.charCodeAt(3)).toBe(35)
+
+    mouse.clearPostedMessages()
+    mouse.dispatchPointer('pointermove', { x: 240, y: 60, button: 0, buttons: 1 })
+
+    // The lost pointerup ended the gesture; a later unrelated move must not emit motion.
+    expect(mouse.terminalInputBytes()).toBe('')
+  })
+
+  it('releases a tracked drag when the pointer is cancelled mid-gesture', () => {
+    mouse.boot()
+    mouse.activeTerminal().modes.mouseTrackingMode = 'drag'
+
+    mouse.dispatchPointer('pointerdown', { x: 40, y: 60, button: 0, buttons: 1 })
+    mouse.dispatchPointer('pointermove', { x: 160, y: 60, button: 0, buttons: 1 })
+    mouse.dispatchPointer('pointercancel', { x: 160, y: 60 })
+
+    const reports = mouse.terminalInputBytes().match(DEFAULT_MOUSE_REPORT_RE) ?? []
+    // Press went to the TUI, so the cancel must not leave the button latched.
+    expect(reports.at(-1)?.charCodeAt(3)).toBe(35)
+  })
+})
diff --git a/mobile/src/terminal/terminal-webview-mouse-report-cell-injected.ts b/mobile/src/terminal/terminal-webview-mouse-report-cell-injected.ts
new file mode 100644
index 00000000000..14baeeaf325
--- /dev/null
+++ b/mobile/src/terminal/terminal-webview-mouse-report-cell-injected.ts
@@ -0,0 +1,29 @@
+// Mouse-report coordinate mapping injected into XTERM_HTML. Closes over term,
+// panX/panY, getCellWidth/Height, and getTotalScale.
+export const TERMINAL_MOUSE_REPORT_CELL_JS = `
+  function viewportToMouseReportCell(clientX, clientY) {
+    if (!term) return null;
+    var cellW = getCellWidth();
+    var cellH = getCellHeight();
+    if (cellW <= 0 || cellH <= 0) return null;
+    if (typeof clientX !== 'number') clientX = window.innerWidth / 2;
+    if (typeof clientY !== 'number') clientY = window.innerHeight / 2;
+    var total = getTotalScale();
+    if (total <= 0) total = 1;
+    var sx = (clientX - panX) / total;
+    var sy = (clientY - panY) / total;
+    var maxX = Math.max(0, term.cols * cellW - 1);
+    var maxY = Math.max(0, term.rows * cellH - 1);
+    if (sx < 0) sx = 0;
+    if (sx > maxX) sx = maxX;
+    if (sy < 0) sy = 0;
+    if (sy > maxY) sy = maxY;
+    var col = Math.floor(sx / cellW);
+    var row = Math.floor(sy / cellH);
+    if (col < 0) col = 0;
+    if (col > term.cols - 1) col = term.cols - 1;
+    if (row < 0) row = 0;
+    if (row > term.rows - 1) row = term.rows - 1;
+    return { col: col, row: row, x: Math.floor(sx), y: Math.floor(sy) };
+  }
+`
diff --git a/mobile/src/terminal/terminal-webview-mouse-test-harness.ts b/mobile/src/terminal/terminal-webview-mouse-test-harness.ts
new file mode 100644
index 00000000000..29500d3c710
--- /dev/null
+++ b/mobile/src/terminal/terminal-webview-mouse-test-harness.ts
@@ -0,0 +1,248 @@
+import { runInThisContext } from 'node:vm'
+import { afterEach, beforeEach, vi, type Mock } from 'vitest'
+import { XTERM_HTML } from './terminal-webview-html'
+
+function iifeSource(): string {
+  const start = XTERM_HTML.indexOf('(function() {')
+  const end = XTERM_HTML.lastIndexOf('})();')
+  return XTERM_HTML.slice(start, end + '})();'.length)
+}
+
+function bodyMarkup(): string {
+  const start = XTERM_HTML.indexOf('<body>') + '<body>'.length
+  const end = XTERM_HTML.indexOf('<script>', start)
+  return XTERM_HTML.slice(start, end)
+}
+
+type BufferState = {
+  baseY: number
+  type: 'alternate' | 'normal'
+  viewportY: number
+}
+
+type TerminalStub = ReturnType<typeof makeTerminal>
+type RegisteredEventListener = {
+  listener: EventListenerOrEventListenerObject
+  options?: boolean | AddEventListenerOptions
+  type: string
+}
+
+type PointerEventType = 'pointerdown' | 'pointermove' | 'pointerup' | 'pointercancel'
+type PointerEventInit = {
+  button?: number
+  buttons?: number
+  pointerType?: string
+  x?: number
+  y?: number
+}
+type PostMessage = Mock<(data: string) => void>
+type Select = Mock<(col: number, row: number, len: number) => void>
+
+export const ESC = '\u001b'
+export const DEFAULT_MOUSE_REPORT_RE = new RegExp(`${ESC}\\[M[\\s\\S]{3}`, 'g')
+
+function makeTerminal(buffer: BufferState, select: Select) {
+  const terminal = {
+    cols: 40,
+    rows: 24,
+    options: { fontSize: 13 },
+    modes: { mouseTrackingMode: 'none' as string },
+    element: null as HTMLElement | null,
+    _core: {
+      _renderService: { dimensions: { css: { cell: { width: 8, height: 15 } } } }
+    },
+    buffer: {
+      active: {
+        get baseY() {
+          return buffer.baseY
+        },
+        get type() {
+          return buffer.type
+        },
+        get viewportY() {
+          return buffer.viewportY
+        },
+        cursorY: 0,
+        length: 1,
+        getLine: () => null
+      }
+    },
+    write(_data: string, callback?: () => void) {
+      callback?.()
+    },
+    open(surface: HTMLElement) {
+      terminal.element = surface
+    },
+    loadAddon() {},
+    resize(cols: number, rows: number) {
+      terminal.cols = cols
+      terminal.rows = rows
+    },
+    clear() {},
+    reset() {},
+    refresh() {},
+    selectAll() {},
+    clearSelection() {},
+    select,
+    scrollLines() {},
+    scrollToBottom() {},
+    scrollToLine() {},
+    attachCustomKeyEventHandler() {},
+    getSelection: () => '',
+    onData: () => ({ dispose() {} }),
+    onLineFeed: () => ({ dispose() {} }),
+    onScroll: () => ({ dispose() {} }),
+    onWriteParsed: () => ({ dispose() {} }),
+    dispose() {}
+  }
+  return terminal
+}
+
+function terminalSurface(): HTMLElement {
+  const surface = document.getElementById('terminal-surface')
+  if (!surface) {
+    throw new Error('terminal surface missing')
+  }
+  return surface
+}
+
+function dispatchPointer(type: PointerEventType, init: PointerEventInit = {}): void {
+  const event = new MouseEvent(type, {
+    bubbles: true,
+    cancelable: true,
+    clientX: init.x ?? 40,
+    clientY: init.y ?? 60,
+    button: init.button ?? 0,
+    buttons: init.buttons ?? 0
+  })
+  // Why: happy-dom's PointerEvent init drops pointerType; grafting it onto a
+  // MouseEvent exercises the same duck-typed reads the WebView handler does.
+  Object.defineProperty(event, 'pointerType', { value: init.pointerType ?? 'mouse' })
+  terminalSurface().dispatchEvent(event)
+}
+
+function mouseClick(x: number, y: number): void {
+  dispatchPointer('pointerdown', { x, y, button: 0, buttons: 1 })
+  dispatchPointer('pointerup', { x, y, button: 0, buttons: 0 })
+}
+
+function mouseDrag(x1: number, y1: number, x2: number, y2: number): void {
+  dispatchPointer('pointerdown', { x: x1, y: y1, button: 0, buttons: 1 })
+  const midX = Math.round((x1 + x2) / 2)
+  const midY = Math.round((y1 + y2) / 2)
+  dispatchPointer('pointermove', { x: midX, y: midY, button: 0, buttons: 1 })
+  dispatchPointer('pointermove', { x: x2, y: y2, button: 0, buttons: 1 })
+  dispatchPointer('pointerup', { x: x2, y: y2, button: 0, buttons: 0 })
+}
+
+function postedMessages(postMessage: PostMessage): Record<string, unknown>[] {
+  return postMessage.mock.calls.map(([raw]) => JSON.parse(String(raw)) as Record<string, unknown>)
+}
+
+function terminalInputBytes(postMessage: PostMessage): string {
+  return postedMessages(postMessage)
+    .filter((message) => message.type === 'terminal-input')
+    .map((message) => (message.bytes as string) ?? '')
+    .join('')
+}
+
+export function useTerminalMouseWebViewHarness() {
+  let animationFrames: (() => void)[]
+  let buffer: BufferState
+  let postMessage: PostMessage
+  let registeredDocumentListeners: RegisteredEventListener[]
+  let registeredWindowListeners: RegisteredEventListener[]
+  let select: Select
+  let terminals: TerminalStub[]
+
+  function boot(): void {
+    document.body.innerHTML = bodyMarkup()
+    runInThisContext(iifeSource())
+    window.dispatchEvent(
+      new MessageEvent('message', {
+        data: JSON.stringify({ type: 'init', cols: 40, rows: 24, initialData: '' })
+      })
+    )
+    // Why: init commits the replacement surface on the next animation frame.
+    while (animationFrames.length > 0) {
+      animationFrames.shift()?.()
+    }
+  }
+
+  function activeTerminal(): TerminalStub {
+    const terminal = terminals.at(-1)
+    if (!terminal) {
+      throw new Error('terminal missing')
+    }
+    return terminal
+  }
+
+  beforeEach(() => {
+    animationFrames = []
+    buffer = { baseY: 0, type: 'normal', viewportY: 0 }
+    registeredDocumentListeners = []
+    registeredWindowListeners = []
+    select = vi.fn<(col: number, row: number, len: number) => void>()
+    terminals = []
+    const addDocumentEventListener = document.addEventListener.bind(document)
+    vi.spyOn(document, 'addEventListener').mockImplementation(((
+      type: string,
+      listener: EventListenerOrEventListenerObject,
+      options?: boolean | AddEventListenerOptions
+    ) => {
+      registeredDocumentListeners.push({ type, listener, options })
+      addDocumentEventListener(type, listener, options)
+    }) as typeof document.addEventListener)
+    const addWindowEventListener = window.addEventListener.bind(window)
+    vi.spyOn(window, 'addEventListener').mockImplementation(((
+      type: string,
+      listener: EventListenerOrEventListenerObject,
+      options?: boolean | AddEventListenerOptions
+    ) => {
+      registeredWindowListeners.push({ type, listener, options })
+      addWindowEventListener(type, listener, options)
+    }) as typeof window.addEventListener)
+    vi.stubGlobal('requestAnimationFrame', (callback: () => void) => {
+      animationFrames.push(callback)
+      return animationFrames.length
+    })
+    vi.stubGlobal('cancelAnimationFrame', () => {})
+    Object.defineProperty(window, 'innerWidth', { value: 381, configurable: true })
+    Object.defineProperty(window, 'innerHeight', { value: 612, configurable: true })
+    postMessage = vi.fn<(data: string) => void>()
+    const webWindow = window as unknown as {
+      Terminal: new () => TerminalStub
+      ReactNativeWebView: { postMessage: (data: string) => void }
+    }
+    webWindow.Terminal = function () {
+      const terminal = makeTerminal(buffer, select)
+      terminals.push(terminal)
+      return terminal
+    } as unknown as new () => TerminalStub
+    webWindow.ReactNativeWebView = { postMessage }
+  })
+
+  afterEach(() => {
+    for (const { type, listener, options } of registeredDocumentListeners) {
+      document.removeEventListener(type, listener as EventListener, options)
+    }
+    for (const { type, listener, options } of registeredWindowListeners) {
+      window.removeEventListener(type, listener as EventListener, options)
+    }
+    vi.restoreAllMocks()
+    vi.unstubAllGlobals()
+  })
+
+  return {
+    activeTerminal,
+    boot,
+    clearPostedMessages: () => postMessage.mockClear(),
+    dispatchPointer,
+    mouseClick,
+    mouseDrag,
+    postedMessages: () => postedMessages(postMessage),
+    selectionSpy: () => select,
+    terminalInputBytes: () => terminalInputBytes(postMessage),
+    terminalSurface
+  }
+}

From 9d473c8c5bc78d77ccd89b8e74e39d7565cd22c5 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Fri, 31 Jul 2026 01:01:35 -0700
Subject: [PATCH 09/23] fix(windows): stop rejecting .cmd spawns under Program
 Files (x86) (#11686)

The move of hasUnsafeWindowsBatchSyntax into src/shared/windows-batch-spawn.ts
silently added `(` and `)` to the cmd.exe denylist, so every .cmd shim or
argument path containing parentheses became unspawnable across nine call sites.
Parentheses only group commands and cannot chain one without a separator the
guard already rejects, so they are dropped again.

The rejected character set is now the single source for the user-facing error
strings, and `orca account add` translates the sentinel into a real message.

Co-authored-by: Orca <help@stably.ai>
---
 src/cli/handlers/account.test.ts         | 35 ++++++++++++++-
 src/cli/handlers/account.ts              | 26 ++++++++++-
 src/cli/handlers/skills.ts               |  5 ++-
 src/cli/skills.test.ts                   | 21 +++++++++
 src/main/skills/skill-update-run.test.ts | 22 ++++++++++
 src/main/skills/skill-update-run.ts      | 11 ++---
 src/main/win32-utils.test.ts             | 55 +++++++++++++++++++++---
 src/main/win32-utils.ts                  |  1 +
 src/shared/windows-batch-spawn.ts        | 16 ++++++-
 9 files changed, 174 insertions(+), 18 deletions(-)

diff --git a/src/cli/handlers/account.test.ts b/src/cli/handlers/account.test.ts
index d39a5f33293..8642df27ea4 100644
--- a/src/cli/handlers/account.test.ts
+++ b/src/cli/handlers/account.test.ts
@@ -49,7 +49,11 @@ vi.mock('../../shared/node-cli-command-resolution', () => ({
 import { ACCOUNT_HANDLERS } from './account'
 import type { HandlerContext } from '../dispatch'
 import type { RuntimeClient } from '../runtime-client'
-import { getCmdExePath } from '../../shared/windows-batch-spawn'
+import {
+  getCmdExePath,
+  WINDOWS_BATCH_UNSAFE_ARGUMENTS_ERROR,
+  WINDOWS_BATCH_UNSAFE_CHARACTERS_LABEL
+} from '../../shared/windows-batch-spawn'
 import { ACCOUNT_IMPORT_RUNTIME_CAPABILITY } from '../../shared/protocol-version'
 
 function successfulChild(): EventEmitter {
@@ -168,6 +172,35 @@ describe('account CLI handlers', () => {
     )
   })
 
+  it('launches a Windows shim installed under Program Files (x86)', async () => {
+    Object.defineProperty(process, 'platform', { configurable: true, value: 'win32' })
+    const shim = 'C:\\Program Files (x86)\\nodejs\\codex.cmd'
+    resolveCliCommandMock.mockReturnValue(shim)
+
+    await ACCOUNT_HANDLERS['account add'](context('codex'))
+
+    expect(spawnMock).toHaveBeenCalledWith(
+      getCmdExePath(),
+      ['/d', '/c', shim, 'login', '--device-auth'],
+      expect.anything()
+    )
+  })
+
+  it('explains an unspawnable Windows shim path instead of leaking the error sentinel', async () => {
+    Object.defineProperty(process, 'platform', { configurable: true, value: 'win32' })
+    resolveCliCommandMock.mockReturnValue('C:\\Users\\A&B\\codex.cmd')
+
+    const error = await ACCOUNT_HANDLERS['account add'](context('codex')).catch(
+      (thrown: unknown) => thrown
+    )
+
+    expect(spawnMock).not.toHaveBeenCalled()
+    const message = error instanceof Error ? error.message : String(error)
+    expect(message).not.toBe(WINDOWS_BATCH_UNSAFE_ARGUMENTS_ERROR)
+    expect(message).toContain('C:\\Users\\A&B\\codex.cmd')
+    expect(message).toContain(WINDOWS_BATCH_UNSAFE_CHARACTERS_LABEL)
+  })
+
   it('adds version-manager Node paths to the login child environment', async () => {
     const nodeBin = '/home/test/.nvm/versions/node/v22.0.0/bin'
     getVersionManagerBinPathsMock.mockReturnValue([nodeBin])
diff --git a/src/cli/handlers/account.ts b/src/cli/handlers/account.ts
index 0ad19aa240d..fd2c7b20402 100644
--- a/src/cli/handlers/account.ts
+++ b/src/cli/handlers/account.ts
@@ -16,7 +16,11 @@ import {
   getVersionManagerBinPaths,
   resolveCliCommand
 } from '../../shared/node-cli-command-resolution'
-import { getSpawnArgsForWindows } from '../../shared/windows-batch-spawn'
+import {
+  getSpawnArgsForWindows,
+  UnsafeWindowsBatchArgumentsError,
+  WINDOWS_BATCH_UNSAFE_CHARACTERS_LABEL
+} from '../../shared/windows-batch-spawn'
 import { ACCOUNT_IMPORT_RUNTIME_CAPABILITY } from '../../shared/protocol-version'
 import type { RuntimeStatus } from '../../shared/runtime-types'
 import type { ClaudeRateLimitAccountsState, CodexRateLimitAccountsState } from '../../shared/types'
@@ -86,7 +90,25 @@ async function runAgentLoginInTerminal(
 ): Promise<void> {
   await new Promise<void>((resolvePromise, rejectPromise) => {
     const resolvedCommand = resolveCliCommand(command)
-    const { spawnCmd, spawnArgs } = getSpawnArgsForWindows(resolvedCommand, args)
+    let spawnCmd: string
+    let spawnArgs: string[]
+    try {
+      ;({ spawnCmd, spawnArgs } = getSpawnArgsForWindows(resolvedCommand, args))
+    } catch (error) {
+      // Why: the bare sentinel message reaches the user verbatim otherwise, with
+      // nothing naming the path or the characters that made it unspawnable.
+      rejectPromise(
+        error instanceof UnsafeWindowsBatchArgumentsError
+          ? new RuntimeClientError(
+              'invalid_environment',
+              `Cannot run \`${command}\` from "${resolvedCommand}": the path contains characters ` +
+                `cmd.exe would reinterpret. Install it somewhere without ` +
+                `${WINDOWS_BATCH_UNSAFE_CHARACTERS_LABEL} in the path.`
+            )
+          : error
+      )
+      return
+    }
     const env = addAgentNodePaths({ ...stripElectronRunAsNode(process.env), ...extraEnv })
     const child = spawn(spawnCmd, spawnArgs, {
       // Why: JSON mode reserves stdout for the response envelope while keeping
diff --git a/src/cli/handlers/skills.ts b/src/cli/handlers/skills.ts
index 7c911ea1751..4e8db5dbdae 100644
--- a/src/cli/handlers/skills.ts
+++ b/src/cli/handlers/skills.ts
@@ -12,7 +12,8 @@ import {
 } from '../../shared/tui-agent-detection-commands'
 import {
   getSpawnArgsForWindows,
-  UnsafeWindowsBatchArgumentsError
+  UnsafeWindowsBatchArgumentsError,
+  WINDOWS_BATCH_UNSAFE_CHARACTERS_LABEL
 } from '../../shared/windows-batch-spawn'
 import { isSkillsCliAgentKeyShaped, toSkillsCliAgentKeys } from '../../shared/skills-cli-agent-keys'
 import {
@@ -134,7 +135,7 @@ function runNpxSkills(args: string[]): Promise<number> {
         new RuntimeClientError(
           'invalid_environment',
           `Cannot run npx from "${resolved}": the path contains characters cmd.exe would ` +
-            'reinterpret. Install Node.js somewhere without & | < > ^ " % ! in the path.'
+            `reinterpret. Install Node.js somewhere without ${WINDOWS_BATCH_UNSAFE_CHARACTERS_LABEL} in the path.`
         )
       )
       return
diff --git a/src/cli/skills.test.ts b/src/cli/skills.test.ts
index 11caa30d704..c7fbb6b1b7e 100644
--- a/src/cli/skills.test.ts
+++ b/src/cli/skills.test.ts
@@ -2,6 +2,7 @@ import { EventEmitter } from 'node:events'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { delimiter } from 'node:path'
 import type * as CodexCliCommandModule from '../shared/node-cli-command-resolution'
+import { WINDOWS_BATCH_UNSAFE_CHARACTERS_LABEL } from '../shared/windows-batch-spawn'
 
 const {
   detectCommandsMock,
@@ -689,6 +690,26 @@ describe('orca skills CLI', () => {
     expect(spawnMock).not.toHaveBeenCalled()
     expect(process.exitCode).toBe(1)
     expect(String(errorSpy.mock.calls[0]?.[0])).toContain('cmd.exe would reinterpret')
+    // Why: remediation advice that names the wrong characters is unactionable.
+    expect(String(errorSpy.mock.calls[0]?.[0])).toContain(WINDOWS_BATCH_UNSAFE_CHARACTERS_LABEL)
+  })
+
+  it('runs npx from a Program Files (x86) install instead of refusing it', async () => {
+    const child = createFakeChild()
+    spawnMock.mockReturnValue(child)
+    vi.spyOn(process, 'platform', 'get').mockReturnValue('win32')
+    vi.stubEnv('ComSpec', 'C:\\Windows\\System32\\cmd.exe')
+    const npx = 'C:\\Program Files (x86)\\nodejs\\npx.cmd'
+    resolveCliCommandMock.mockReturnValue(npx)
+    vi.spyOn(process.stderr, 'write').mockImplementation(() => true)
+
+    const resultPromise = main(['skills', 'install', '--skill', 'alpha'], '/tmp/repo')
+    await vi.waitFor(() => expect(spawnMock).toHaveBeenCalled())
+    child.emit('exit', 0, null)
+    await resultPromise
+
+    expect(spawnMock.mock.calls[0]?.[0]).toBe('C:\\Windows\\System32\\cmd.exe')
+    expect(spawnMock.mock.calls[0]?.[1]?.slice(0, 3)).toEqual(['/d', '/c', npx])
   })
 
   it('never puts the current directory on the child PATH when npx is unresolvable', async () => {
diff --git a/src/main/skills/skill-update-run.test.ts b/src/main/skills/skill-update-run.test.ts
index 0aeb31bf32e..7cc86402c9c 100644
--- a/src/main/skills/skill-update-run.test.ts
+++ b/src/main/skills/skill-update-run.test.ts
@@ -1,6 +1,10 @@
 import { EventEmitter } from 'node:events'
 import { describe, expect, it, vi } from 'vitest'
 import type { SkillUpdateRun } from '../../shared/skill-freshness'
+import {
+  getSpawnArgsForWindows,
+  WINDOWS_BATCH_UNSAFE_CHARACTERS_LABEL
+} from '../../shared/windows-batch-spawn'
 import { CANCEL_RELEASE_TIMEOUT_MS, SkillUpdateRunner } from './skill-update-run'
 
 class FakeChild extends EventEmitter {
@@ -293,6 +297,24 @@ describe('SkillUpdateRunner', () => {
     expect(run.state).toBe('error')
     expect(run.state === 'error' && run.failedNames).toEqual(['orca-cli'])
     expect(states.at(-1)?.state).toBe('error')
+    // Why: the message used to name a character set the guard no longer matches.
+    expect(run.state === 'error' && run.message).toContain(WINDOWS_BATCH_UNSAFE_CHARACTERS_LABEL)
+  })
+
+  it('spawns npx from a Program Files (x86) install instead of refusing it', () => {
+    const platform = vi.spyOn(process, 'platform', 'get').mockReturnValue('win32')
+    try {
+      const npx = 'C:\\Program Files (x86)\\nodejs\\npx.cmd'
+      const { runner, spawnCalls } = makeRunner({
+        resolveCommand: () => npx,
+        buildSpawnArgs: getSpawnArgsForWindows
+      })
+
+      expect(runner.start(['orca-cli']).started).toBe(true)
+      expect(spawnCalls[0]?.args.slice(0, 3)).toEqual(['/d', '/c', npx])
+    } finally {
+      platform.mockRestore()
+    }
   })
 
   it('coalesces progress frames into one push instead of one per chunk', async () => {
diff --git a/src/main/skills/skill-update-run.ts b/src/main/skills/skill-update-run.ts
index 9083b24e43f..71365dd12c4 100644
--- a/src/main/skills/skill-update-run.ts
+++ b/src/main/skills/skill-update-run.ts
@@ -6,7 +6,7 @@ import {
 } from '../../shared/skill-freshness'
 import { resolveCliCommand } from '../codex-cli/command'
 import { killWithDescendantSweep } from '../pty-descendant-termination'
-import { getSpawnArgsForWindows } from '../win32-utils'
+import { getSpawnArgsForWindows, WINDOWS_BATCH_UNSAFE_CHARACTERS_LABEL } from '../win32-utils'
 
 // Why: `skills update` prints ANSI colour and \r + erase-line progress. We show
 // this log verbatim to the user but never parse it — `update` has no --json
@@ -101,9 +101,8 @@ export class SkillUpdateRunner {
       ;({ spawnCmd, spawnArgs } = buildSpawnArgs(npxCommand, npxArgs))
     } catch {
       // Why: the names are already canonical here, so this is the cmd.exe rail
-      // rejecting the resolved npx *path* — a profile directory containing `&`,
-      // `%` or `!` is enough. Publishing the failure keeps the dialog honest;
-      // returning a bare `started: false` would leave the button dead and silent.
+      // rejecting the resolved npx *path*. Publishing the failure keeps the dialog
+      // honest; a bare `started: false` would leave the button dead and silent.
       this.runToken += 1
       this.settling = false
       this.publish({
@@ -112,7 +111,9 @@ export class SkillUpdateRunner {
         finishedAt: this.deps.now(),
         output: '',
         failedNames: canonicalNames,
-        message: `Could not run ${npxCommand} safely from this location.`
+        message:
+          `Could not run ${npxCommand} safely from this location: its path contains one of ` +
+          `${WINDOWS_BATCH_UNSAFE_CHARACTERS_LABEL}, which cmd.exe would reinterpret.`
       })
       return { started: false, reason: 'unsafe-command-path' }
     }
diff --git a/src/main/win32-utils.test.ts b/src/main/win32-utils.test.ts
index 3f719e5ae34..4159d7d89b4 100644
--- a/src/main/win32-utils.test.ts
+++ b/src/main/win32-utils.test.ts
@@ -8,7 +8,8 @@ import {
   getSpawnArgsForWindows,
   isPermissionError,
   isWindowsBatchScript,
-  resolveWindowsCommand
+  resolveWindowsCommand,
+  WINDOWS_BATCH_UNSAFE_CHARACTERS_LABEL
 } from './win32-utils'
 
 function withPlatform<T>(platform: NodeJS.Platform, fn: () => T): T {
@@ -119,7 +120,7 @@ describe('getSpawnArgsForWindows', () => {
 
   it('rejects unsafe args for .cmd scripts on win32', () => {
     withPlatform('win32', () => {
-      for (const argument of ['hello & goodbye', 'close)', '(open']) {
+      for (const argument of ['hello & goodbye', 'a | b', 'x > y', '%PATH%', 'a\nb']) {
         expect(() => getSpawnArgsForWindows('C:\\tools\\agent.cmd', [argument])).toThrow(
           'UNSAFE_WINDOWS_BATCH_ARGUMENTS'
         )
@@ -129,11 +130,9 @@ describe('getSpawnArgsForWindows', () => {
 
   it('rejects unsafe command paths for .cmd scripts on win32', () => {
     withPlatform('win32', () => {
-      for (const command of ['C:\\bad&path\\agent.cmd', 'C:\\bad(path\\agent.cmd']) {
-        expect(() => getSpawnArgsForWindows(command, ['login'])).toThrow(
-          'UNSAFE_WINDOWS_BATCH_ARGUMENTS'
-        )
-      }
+      expect(() => getSpawnArgsForWindows('C:\\bad&path\\agent.cmd', ['login'])).toThrow(
+        'UNSAFE_WINDOWS_BATCH_ARGUMENTS'
+      )
     })
   })
 
@@ -144,6 +143,48 @@ describe('getSpawnArgsForWindows', () => {
       ).toEqual(['/d', '/c', 'C:\\tools\\agent.cmd', 'package,name;version'])
     })
   })
+
+  // Why: parentheses only group commands and cannot chain one without a separator
+  // the guard already rejects, so paren-bearing paths must stay spawnable.
+  it('spawns .cmd shims under Program Files (x86) and paren-bearing worktrees', () => {
+    withPlatform('win32', () => {
+      const npx = 'C:\\Program Files (x86)\\nodejs\\npx.cmd'
+      expect(getSpawnArgsForWindows(npx, ['C:\\dev\\app (fork)'])).toEqual({
+        spawnCmd: getCmdExePath(),
+        spawnArgs: ['/d', '/c', npx, 'C:\\dev\\app (fork)']
+      })
+      expect(getSpawnArgsForWindows('C:\\tools\\agent.cmd', ['close)', '(open']).spawnArgs).toEqual(
+        ['/d', '/c', 'C:\\tools\\agent.cmd', 'close)', '(open']
+      )
+    })
+  })
+
+  it('still rejects a paren-wrapped command chain', () => {
+    withPlatform('win32', () => {
+      expect(() => getSpawnArgsForWindows('C:\\tools\\agent.cmd', ['(x & calc.exe)'])).toThrow(
+        'UNSAFE_WINDOWS_BATCH_ARGUMENTS'
+      )
+    })
+  })
+
+  it('rejects exactly the characters the message advertises', () => {
+    withPlatform('win32', () => {
+      const advertised = WINDOWS_BATCH_UNSAFE_CHARACTERS_LABEL.split(' ')
+      expect(advertised.length).toBeGreaterThan(0)
+      for (const character of advertised) {
+        expect(() => getSpawnArgsForWindows('C:\\tools\\agent.cmd', [`a${character}b`])).toThrow(
+          'UNSAFE_WINDOWS_BATCH_ARGUMENTS'
+        )
+      }
+      // Why: anything not advertised must pass, or the message misleads the user.
+      for (const character of ['(', ')', ',', ';', '@', '#', '$', "'", '~', '=']) {
+        expect(advertised).not.toContain(character)
+        expect(() =>
+          getSpawnArgsForWindows('C:\\tools\\agent.cmd', [`a${character}b`])
+        ).not.toThrow()
+      }
+    })
+  })
 })
 
 describe('resolveWindowsCommand', () => {
diff --git a/src/main/win32-utils.ts b/src/main/win32-utils.ts
index 21f3a75853d..c1031c7c55e 100644
--- a/src/main/win32-utils.ts
+++ b/src/main/win32-utils.ts
@@ -7,6 +7,7 @@ export {
   getSpawnArgsForWindows,
   isWindowsBatchScript,
   WINDOWS_BATCH_UNSAFE_ARGUMENTS_ERROR,
+  WINDOWS_BATCH_UNSAFE_CHARACTERS_LABEL,
   UnsafeWindowsBatchArgumentsError
 } from '../shared/windows-batch-spawn'
 
diff --git a/src/shared/windows-batch-spawn.ts b/src/shared/windows-batch-spawn.ts
index cd20dff5c79..4afddccae73 100644
--- a/src/shared/windows-batch-spawn.ts
+++ b/src/shared/windows-batch-spawn.ts
@@ -21,8 +21,22 @@ export class UnsafeWindowsBatchArgumentsError extends Error {
   }
 }
 
+// Why: cmd.exe re-parses the command line, and these are the characters that can
+// start a new command or expand a variable out of an otherwise inert argument.
+// `(`/`)` are deliberately absent: they only group commands, and grouping cannot
+// chain anything without one of the separators below, so rejecting them merely
+// broke every `C:\Program Files (x86)\...` shim and paren-bearing worktree path.
+const WINDOWS_BATCH_UNSAFE_CHARACTERS = ['&', '|', '<', '>', '^', '"', '%', '!'] as const
+
+/** The rejected characters, spelled for error messages so they cannot drift from the guard. */
+export const WINDOWS_BATCH_UNSAFE_CHARACTERS_LABEL = WINDOWS_BATCH_UNSAFE_CHARACTERS.join(' ')
+
+const UNSAFE_WINDOWS_BATCH_SYNTAX = new RegExp(
+  `[${WINDOWS_BATCH_UNSAFE_CHARACTERS.map((character) => character.replace(/[\\^\]-]/, '\\$&')).join('')}\\r\\n]`
+)
+
 function hasUnsafeWindowsBatchSyntax(value: string): boolean {
-  return /[&|<>^"%!()\r\n]/.test(value)
+  return UNSAFE_WINDOWS_BATCH_SYNTAX.test(value)
 }
 
 export function getSpawnArgsForWindows(

From f0221cd419b0d62fe714a17a6502733fb43d5d79 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Fri, 31 Jul 2026 01:24:21 -0700
Subject: [PATCH 10/23] feat: show GPU acceleration in About panel (#11722)

---
 src/main/index.ts                             | 22 +++++++
 .../menu/gpu-acceleration-about-panel.test.ts | 60 +++++++++++++++++++
 src/main/menu/gpu-acceleration-about-panel.ts | 49 +++++++++++++++
 3 files changed, 131 insertions(+)
 create mode 100644 src/main/menu/gpu-acceleration-about-panel.test.ts
 create mode 100644 src/main/menu/gpu-acceleration-about-panel.ts

diff --git a/src/main/index.ts b/src/main/index.ts
index 59eeccbbad7..212f9e63659 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -87,6 +87,7 @@ import {
   registerAppMenu,
   rebuildAppMenu
 } from './menu/register-app-menu'
+import { createGpuAccelerationAboutPanelOptions } from './menu/gpu-acceleration-about-panel'
 import {
   checkForRemoteServerUpdate,
   checkForUpdatesFromMenu,
@@ -359,10 +360,30 @@ const gpuCrashFallbackTracker = new GpuCrashFallbackTracker({
   threshold: DEFAULT_GPU_CRASH_FALLBACK_THRESHOLD
 })
 let gpuFallbackActiveThisLaunch = false
+let gpuFeatureStatus: Electron.GPUFeatureStatus | null = null
 let localPtyStartupReady: Promise<void> = Promise.resolve()
 let localPtyProviderStartupReady: Promise<void> = Promise.resolve()
 const AGENT_STATE_CRASH_BREADCRUMB_MIN_INTERVAL_MS = 30_000
 const isServeMode = process.argv.includes('--serve')
+
+function updateGpuAccelerationAboutPanel(): void {
+  app.setAboutPanelOptions(
+    createGpuAccelerationAboutPanelOptions({
+      appName: app.name,
+      appVersion: app.getVersion(),
+      platform: process.platform,
+      gpuFallbackActive: gpuFallbackActiveThisLaunch,
+      gpuFeatureStatus
+    })
+  )
+}
+
+app.on('gpu-info-update', () => {
+  gpuFeatureStatus = app.getGPUFeatureStatus()
+  if (app.isReady()) {
+    updateGpuAccelerationAboutPanel()
+  }
+})
 if (isServeMode) {
   reserveServeStdoutForReadiness()
 }
@@ -1968,6 +1989,7 @@ void app.whenReady().then(async () => {
   electronApp.setAppUserModelId(devInstanceIdentity.appUserModelId)
   // Why: setName drives the macOS safeStorage Keychain item name; use the stable appName (not per-branch `name`) so dev branches share one key and don't re-prompt.
   app.setName(devInstanceIdentity.appName)
+  updateGpuAccelerationAboutPanel()
 
   // Why: managed WSL launchers live outside the Windows app bundle, so keep their launcher/bridge contract synced across app updates.
   managedWslCliReconciliationStatus = 'pending'
diff --git a/src/main/menu/gpu-acceleration-about-panel.test.ts b/src/main/menu/gpu-acceleration-about-panel.test.ts
new file mode 100644
index 00000000000..2102460feb3
--- /dev/null
+++ b/src/main/menu/gpu-acceleration-about-panel.test.ts
@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest'
+import {
+  createGpuAccelerationAboutPanelOptions,
+  describeGpuAcceleration
+} from './gpu-acceleration-about-panel'
+
+describe('GPU acceleration About panel', () => {
+  it.each([
+    ['enabled', 'Enabled'],
+    ['disabled_off', 'Disabled'],
+    ['disabled_software', 'Software rendering'],
+    ['unavailable_software', 'Software rendering'],
+    ['unavailable', 'Unavailable'],
+    ['undefined', 'Status unavailable']
+  ])('describes Chromium compositing status %s', (gpu_compositing, expected) => {
+    expect(describeGpuAcceleration({ gpu_compositing }, false)).toBe(expected)
+  })
+
+  it('gives Safe Graphics Mode precedence over Chromium status', () => {
+    expect(describeGpuAcceleration({ gpu_compositing: 'enabled' }, true)).toBe(
+      'Disabled (Safe Graphics Mode)'
+    )
+  })
+
+  it('reports status as unavailable until Chromium publishes GPU information', () => {
+    expect(describeGpuAcceleration(null, false)).toBe('Status unavailable')
+  })
+
+  it('uses the Linux-visible copyright field', () => {
+    expect(
+      createGpuAccelerationAboutPanelOptions({
+        appName: 'Orca',
+        appVersion: '1.2.3',
+        platform: 'linux',
+        gpuFallbackActive: false,
+        gpuFeatureStatus: { gpu_compositing: 'enabled' }
+      })
+    ).toEqual({
+      applicationName: 'Orca',
+      applicationVersion: '1.2.3',
+      copyright: 'GPU acceleration: Enabled'
+    })
+  })
+
+  it.each(['darwin', 'win32'] satisfies NodeJS.Platform[])('uses credits on %s', (platform) => {
+    expect(
+      createGpuAccelerationAboutPanelOptions({
+        appName: 'Orca',
+        appVersion: '1.2.3',
+        platform,
+        gpuFallbackActive: true,
+        gpuFeatureStatus: null
+      })
+    ).toEqual({
+      applicationName: 'Orca',
+      applicationVersion: '1.2.3',
+      credits: 'GPU acceleration: Disabled (Safe Graphics Mode)'
+    })
+  })
+})
diff --git a/src/main/menu/gpu-acceleration-about-panel.ts b/src/main/menu/gpu-acceleration-about-panel.ts
new file mode 100644
index 00000000000..340897ce2b9
--- /dev/null
+++ b/src/main/menu/gpu-acceleration-about-panel.ts
@@ -0,0 +1,49 @@
+export type GpuAccelerationAboutPanelOptions = {
+  appName: string
+  appVersion: string
+  platform: NodeJS.Platform
+  gpuFallbackActive: boolean
+  gpuFeatureStatus: Pick<Electron.GPUFeatureStatus, 'gpu_compositing'> | null
+}
+
+export function describeGpuAcceleration(
+  gpuFeatureStatus: Pick<Electron.GPUFeatureStatus, 'gpu_compositing'> | null,
+  gpuFallbackActive: boolean
+): string {
+  if (gpuFallbackActive) {
+    return 'Disabled (Safe Graphics Mode)'
+  }
+
+  const compositing = gpuFeatureStatus?.gpu_compositing.trim().toLowerCase()
+  if (!compositing || compositing === 'undefined') {
+    return 'Status unavailable'
+  }
+  if (compositing === 'enabled') {
+    return 'Enabled'
+  }
+  if (compositing.includes('software')) {
+    return 'Software rendering'
+  }
+  if (compositing.startsWith('disabled')) {
+    return 'Disabled'
+  }
+  if (compositing.startsWith('unavailable')) {
+    return 'Unavailable'
+  }
+  return `Unknown (${compositing})`
+}
+
+export function createGpuAccelerationAboutPanelOptions({
+  appName,
+  appVersion,
+  platform,
+  gpuFallbackActive,
+  gpuFeatureStatus
+}: GpuAccelerationAboutPanelOptions): Electron.AboutPanelOptionsOptions {
+  const status = `GPU acceleration: ${describeGpuAcceleration(gpuFeatureStatus, gpuFallbackActive)}`
+  return {
+    applicationName: appName,
+    applicationVersion: appVersion,
+    ...(platform === 'linux' ? { copyright: status } : { credits: status })
+  }
+}

From 0cc54b73d6f9b084aa7431796120ded2ef03b026 Mon Sep 17 00:00:00 2001
From: Jinwoo Hong <73622457+Jinwoo-H@users.noreply.github.com>
Date: Fri, 31 Jul 2026 01:54:09 -0700
Subject: [PATCH 11/23] fix(mobile): harden attachments and compact agent
 statuses (#11671)

Co-authored-by: OrcaWin <293788423+OrcaWin@users.noreply.github.com>
---
 .../src/components/WorktreeAgentList.test.tsx | 105 ++++++++++++++++++
 mobile/src/components/WorktreeAgentList.tsx   |  38 +++++--
 .../src/components/WorktreeAgentSummary.tsx   | 104 +++++++++++++++++
 .../session/mobile-clipboard-image.test.ts    |  25 +++++
 mobile/src/session/mobile-clipboard-image.ts  |  22 ++++
 .../mobile-image-base64-accumulator.test.ts   |  29 +++++
 .../mobile-image-base64-accumulator.ts        |  54 +++++++++
 .../mobile-image-source-picker.test.ts        |  94 +++++++++++++---
 .../src/session/mobile-image-source-picker.ts |  91 ++++++++++++---
 9 files changed, 521 insertions(+), 41 deletions(-)
 create mode 100644 mobile/src/components/WorktreeAgentList.test.tsx
 create mode 100644 mobile/src/components/WorktreeAgentSummary.tsx
 create mode 100644 mobile/src/session/mobile-image-base64-accumulator.test.ts
 create mode 100644 mobile/src/session/mobile-image-base64-accumulator.ts

diff --git a/mobile/src/components/WorktreeAgentList.test.tsx b/mobile/src/components/WorktreeAgentList.test.tsx
new file mode 100644
index 00000000000..036f5d35996
--- /dev/null
+++ b/mobile/src/components/WorktreeAgentList.test.tsx
@@ -0,0 +1,105 @@
+import { createElement } from 'react'
+import { act, create, type ReactTestRenderer } from 'react-test-renderer'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { RuntimeWorktreeAgentRow } from '../../../src/shared/runtime-types'
+import { WorktreeAgentList } from './WorktreeAgentList'
+
+vi.mock('react-native', () => ({
+  Pressable: 'Pressable',
+  StyleSheet: { create: <T,>(styles: T) => styles },
+  Text: 'Text',
+  View: 'View'
+}))
+vi.mock('lucide-react-native', () => ({
+  ChevronDown: 'ChevronDown',
+  ChevronRight: 'ChevronRight'
+}))
+vi.mock('./AgentStateDot', () => ({ AgentStateDot: () => null }))
+vi.mock('./MobileAgentIcon', () => ({ MobileAgentIcon: () => null }))
+vi.mock('./WorktreeAgentRow', () => ({ WorktreeAgentRow: 'WorktreeAgentRow' }))
+
+function agent(paneKey: string, parentPaneKey: string | null = null): RuntimeWorktreeAgentRow {
+  return {
+    paneKey,
+    parentPaneKey,
+    state: 'working',
+    agentType: 'codex',
+    prompt: `Prompt ${paneKey}`,
+    taskTitle: null,
+    displayName: null,
+    lastAssistantMessage: null,
+    toolName: null,
+    toolInput: null,
+    interrupted: false,
+    stateStartedAt: 1_000,
+    updatedAt: 1_000
+  }
+}
+
+describe('WorktreeAgentList', () => {
+  let renderer: ReactTestRenderer | null = null
+
+  beforeEach(() => {
+    globalThis.IS_REACT_ACT_ENVIRONMENT = true
+  })
+
+  afterEach(() => {
+    act(() => renderer?.unmount())
+    renderer = null
+  })
+
+  it('collapses multiple agents to their status icons by default', async () => {
+    const stopPropagation = vi.fn()
+    await act(async () => {
+      renderer = create(
+        createElement(WorktreeAgentList, {
+          agents: [agent('agent-1'), agent('agent-2'), agent('agent-3')],
+          now: 2_000,
+          unvisited: false
+        })
+      )
+    })
+
+    const summary = renderer!.root.findByType('Pressable')
+    expect(summary.props.accessibilityLabel).toBe('Expand 3 agents')
+    expect(summary.props.accessibilityState).toEqual({ expanded: false })
+    expect(renderer!.root.findAllByType('WorktreeAgentRow')).toHaveLength(0)
+
+    await act(async () => summary.props.onPress({ stopPropagation }))
+
+    expect(stopPropagation).toHaveBeenCalledTimes(1)
+    expect(renderer!.root.findByType('Pressable').props.accessibilityLabel).toBe(
+      'Collapse 3 agents'
+    )
+    expect(renderer!.root.findAllByType('WorktreeAgentRow')).toHaveLength(3)
+  })
+
+  it('keeps a single agent visible without a redundant disclosure control', async () => {
+    await act(async () => {
+      renderer = create(
+        createElement(WorktreeAgentList, {
+          agents: [agent('agent-1')],
+          now: 2_000,
+          unvisited: false
+        })
+      )
+    })
+
+    expect(renderer!.root.findAllByType('Pressable')).toHaveLength(0)
+    expect(renderer!.root.findAllByType('WorktreeAgentRow')).toHaveLength(1)
+  })
+
+  it('summarizes lineage by root agents like desktop', async () => {
+    await act(async () => {
+      renderer = create(
+        createElement(WorktreeAgentList, {
+          agents: [agent('parent-1'), agent('child-1', 'parent-1'), agent('parent-2')],
+          now: 2_000,
+          unvisited: false
+        })
+      )
+    })
+
+    expect(renderer!.root.findByType('Pressable').props.accessibilityLabel).toBe('Expand 2 agents')
+  })
+})
diff --git a/mobile/src/components/WorktreeAgentList.tsx b/mobile/src/components/WorktreeAgentList.tsx
index dc357ad685b..3abe97e00e1 100644
--- a/mobile/src/components/WorktreeAgentList.tsx
+++ b/mobile/src/components/WorktreeAgentList.tsx
@@ -1,8 +1,9 @@
-import { useMemo } from 'react'
+import { useMemo, useState } from 'react'
 import { StyleSheet, View } from 'react-native'
 import type { RuntimeWorktreeAgentRow } from '../../../src/shared/runtime-types'
-import { flattenAgentRowLineage } from '../worktree/agent-row-lineage'
+import { buildAgentRowLineageTree, flattenAgentRowLineage } from '../worktree/agent-row-lineage'
 import { WorktreeAgentRow } from './WorktreeAgentRow'
+import { WorktreeAgentSummary } from './WorktreeAgentSummary'
 
 type Props = {
   agents: RuntimeWorktreeAgentRow[]
@@ -14,20 +15,35 @@ type Props = {
 // a depth-indented WorktreeAgentRow per agent, mirroring the desktop sidebar's
 // WorktreeCardAgents.
 export function WorktreeAgentList({ agents, now, unvisited }: Props) {
-  // Why: rebuild the lineage tree only when the agent list changes, not on every
-  // re-render (the shared useNow tick re-renders this list every 30s).
   const nodes = useMemo(() => flattenAgentRowLineage(agents), [agents])
+  const summaryAgents = useMemo(() => {
+    const lineage = buildAgentRowLineageTree(agents)
+    return lineage.childrenByParentPaneKey.size > 0 ? lineage.rootRows : agents
+  }, [agents])
+  const [expanded, setExpanded] = useState(false)
+  const usesSummary = summaryAgents.length > 1
+
   return (
     <View style={styles.list}>
-      {nodes.map((node) => (
-        <WorktreeAgentRow
-          key={node.row.paneKey}
-          agent={node.row}
-          depth={node.depth}
+      {usesSummary ? (
+        <WorktreeAgentSummary
+          agents={summaryAgents}
+          expanded={expanded}
           now={now}
-          unvisited={unvisited}
+          onToggle={() => setExpanded((value) => !value)}
         />
-      ))}
+      ) : null}
+      {!usesSummary || expanded
+        ? nodes.map((node) => (
+            <WorktreeAgentRow
+              key={node.row.paneKey}
+              agent={node.row}
+              depth={node.depth}
+              now={now}
+              unvisited={unvisited}
+            />
+          ))
+        : null}
     </View>
   )
 }
diff --git a/mobile/src/components/WorktreeAgentSummary.tsx b/mobile/src/components/WorktreeAgentSummary.tsx
new file mode 100644
index 00000000000..76d3b8ff4b6
--- /dev/null
+++ b/mobile/src/components/WorktreeAgentSummary.tsx
@@ -0,0 +1,104 @@
+import { ChevronDown, ChevronRight } from 'lucide-react-native'
+import { Pressable, StyleSheet, Text, View } from 'react-native'
+import type { RuntimeWorktreeAgentRow } from '../../../src/shared/runtime-types'
+import { colors, radii, spacing } from '../theme/mobile-theme'
+import { agentDotState } from '../worktree/agent-row-display'
+import { AgentStateDot } from './AgentStateDot'
+import { MobileAgentIcon } from './MobileAgentIcon'
+
+const MAX_VISIBLE_AGENTS = 3
+
+type Props = {
+  agents: RuntimeWorktreeAgentRow[]
+  expanded: boolean
+  now: number
+  onToggle: () => void
+}
+
+export function WorktreeAgentSummary({ agents, expanded, now, onToggle }: Props) {
+  const visibleAgents = agents.slice(0, MAX_VISIBLE_AGENTS)
+  const hiddenCount = agents.length - visibleAgents.length
+  const subject = `${agents.length} agents`
+
+  return (
+    <Pressable
+      style={({ pressed }) => [
+        styles.summary,
+        !expanded && styles.summaryCollapsed,
+        pressed && styles.summaryPressed
+      ]}
+      accessibilityRole="button"
+      accessibilityLabel={`${expanded ? 'Collapse' : 'Expand'} ${subject}`}
+      accessibilityState={{ expanded }}
+      onPress={(event) => {
+        event.stopPropagation()
+        onToggle()
+      }}
+    >
+      {expanded ? (
+        <Text style={styles.expandedLabel}>{subject}</Text>
+      ) : (
+        <View style={styles.agentIcons}>
+          {visibleAgents.map((agent) => (
+            <View key={agent.paneKey} style={styles.agentStatus}>
+              <AgentStateDot state={agentDotState(agent, now)} />
+              {agent.agentType ? <MobileAgentIcon agentId={agent.agentType} size={13} /> : null}
+            </View>
+          ))}
+          {hiddenCount > 0 ? <Text style={styles.hiddenCount}>+{hiddenCount}</Text> : null}
+        </View>
+      )}
+      {expanded ? (
+        <ChevronDown size={12} color={colors.textMuted} />
+      ) : (
+        <ChevronRight size={12} color={colors.textMuted} />
+      )}
+    </Pressable>
+  )
+}
+
+const styles = StyleSheet.create({
+  summary: {
+    minHeight: 24,
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: spacing.xs,
+    paddingHorizontal: spacing.xs,
+    borderRadius: radii.button
+  },
+  summaryCollapsed: {
+    borderWidth: 1,
+    borderColor: colors.borderSubtle,
+    backgroundColor: colors.bgRaised
+  },
+  summaryPressed: {
+    opacity: 0.72
+  },
+  expandedLabel: {
+    flex: 1,
+    paddingLeft: spacing.xs,
+    fontSize: 11,
+    fontWeight: '500',
+    color: colors.textMuted
+  },
+  agentIcons: {
+    flex: 1,
+    minWidth: 0,
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: spacing.xs
+  },
+  agentStatus: {
+    height: 19,
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: 2,
+    paddingHorizontal: 3,
+    borderRadius: radii.button,
+    backgroundColor: colors.bgPanel
+  },
+  hiddenCount: {
+    fontSize: 10,
+    color: colors.textMuted
+  }
+})
diff --git a/mobile/src/session/mobile-clipboard-image.test.ts b/mobile/src/session/mobile-clipboard-image.test.ts
index c0cc283fe5c..cc563127631 100644
--- a/mobile/src/session/mobile-clipboard-image.test.ts
+++ b/mobile/src/session/mobile-clipboard-image.test.ts
@@ -8,6 +8,7 @@ import {
   saveMobileClipboardImageAsTempFile
 } from './mobile-clipboard-image'
 import type { RpcClient } from '../transport/rpc-client'
+import { LogicalClientCutoverError } from '../transport/stable-logical-rpc-client'
 import type { RpcFailure, RpcResponse, RpcSuccess } from '../transport/types'
 
 function ok(id: string, result: unknown): RpcSuccess {
@@ -124,6 +125,30 @@ describe('mobile clipboard image paste helpers', () => {
     })
   })
 
+  it('restarts the upload after a logical connection cutover', async () => {
+    const sendRequest = vi
+      .fn()
+      .mockResolvedValueOnce(ok('start-1', { uploadId: 'upload-1' }))
+      .mockRejectedValueOnce(new LogicalClientCutoverError())
+      .mockResolvedValueOnce(ok('abort-1', { aborted: true }))
+      .mockResolvedValueOnce(ok('start-2', { uploadId: 'upload-2' }))
+      .mockResolvedValueOnce(ok('append-2', { receivedBase64Length: 8 }))
+      .mockResolvedValueOnce(ok('commit-2', '/tmp/orca-paste-image.png'))
+
+    await expect(saveMobileClipboardImageAsTempFile({ sendRequest }, 'aGVsbG8=')).resolves.toBe(
+      '/tmp/orca-paste-image.png'
+    )
+
+    expect(sendRequest.mock.calls.map(([method]) => method)).toEqual([
+      'clipboard.startImageUpload',
+      'clipboard.appendImageUploadChunk',
+      'clipboard.abortImageUpload',
+      'clipboard.startImageUpload',
+      'clipboard.appendImageUploadChunk',
+      'clipboard.commitImageUpload'
+    ])
+  })
+
   it('brackets generated image paths before sending to the terminal', () => {
     expect(buildMobileImagePastePayload('/tmp/orca.png')).toBe('\x1b[200~/tmp/orca.png\x1b[201~')
     expect(buildMobileImagePastePayload('/tmp/\x1b.png')).toBe('\x1b[200~/tmp/\u241b.png\x1b[201~')
diff --git a/mobile/src/session/mobile-clipboard-image.ts b/mobile/src/session/mobile-clipboard-image.ts
index 3bc39749ac0..578dabefcb9 100644
--- a/mobile/src/session/mobile-clipboard-image.ts
+++ b/mobile/src/session/mobile-clipboard-image.ts
@@ -1,9 +1,11 @@
 import type { RpcClient } from '../transport/rpc-client'
+import { isLogicalClientCutoverError } from '../transport/stable-logical-rpc-client'
 import type { RpcFailure, RpcSuccess } from '../transport/types'
 
 export const MOBILE_CLIPBOARD_IMAGE_MAX_BASE64_CHARS = 24 * 1024 * 1024
 export const MOBILE_CLIPBOARD_IMAGE_UPLOAD_CHUNK_BASE64_CHARS = 512 * 1024
 export const MOBILE_CLIPBOARD_IMAGE_SINGLE_FRAME_FALLBACK_BASE64_CHARS = 256 * 1024
+const MOBILE_CLIPBOARD_IMAGE_UPLOAD_CUTOVER_MAX_RETRIES = 1
 // Why: PNG bytes don't scale exactly with pixel area, so undershoot the target on
 // each pass and let the bounded retry below converge instead of distorting in one shot.
 const MOBILE_CLIPBOARD_IMAGE_DOWNSCALE_SAFETY = 0.85
@@ -106,6 +108,26 @@ export async function saveMobileClipboardImageAsTempFile(
 ): Promise<string> {
   const contentBase64 = normalizeMobileClipboardImageBase64(imageData)
   const connectionId = args?.connectionId ?? null
+  for (let retry = 0; ; retry += 1) {
+    try {
+      return await uploadMobileClipboardImageTransaction(client, contentBase64, connectionId)
+    } catch (error) {
+      if (
+        !isLogicalClientCutoverError(error) ||
+        retry >= MOBILE_CLIPBOARD_IMAGE_UPLOAD_CUTOVER_MAX_RETRIES
+      ) {
+        throw error
+      }
+      // Why: upload replay can create only temp state; terminal input is sent after this returns.
+    }
+  }
+}
+
+async function uploadMobileClipboardImageTransaction(
+  client: Pick<RpcClient, 'sendRequest'>,
+  contentBase64: string,
+  connectionId: string | null
+): Promise<string> {
   const startResponse = await client.sendRequest('clipboard.startImageUpload', {
     expectedBase64Length: contentBase64.length,
     connectionId
diff --git a/mobile/src/session/mobile-image-base64-accumulator.test.ts b/mobile/src/session/mobile-image-base64-accumulator.test.ts
new file mode 100644
index 00000000000..c8e930d4bda
--- /dev/null
+++ b/mobile/src/session/mobile-image-base64-accumulator.test.ts
@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest'
+import { MobileImageBase64Accumulator } from './mobile-image-base64-accumulator'
+
+function decodeBase64(data: string): Uint8Array {
+  return Uint8Array.from(atob(data), (character) => character.charCodeAt(0))
+}
+
+describe('MobileImageBase64Accumulator', () => {
+  it('preserves bytes split across non-aligned source chunks', () => {
+    const accumulator = new MobileImageBase64Accumulator()
+    accumulator.append(new Uint8Array([1]))
+    accumulator.append(new Uint8Array([2, 3]))
+    accumulator.append(new Uint8Array([4, 5]))
+
+    expect(accumulator.finish()).toBe('AQIDBAU=')
+  })
+
+  it('preserves bytes across internal staging flushes', () => {
+    const bytes = new Uint8Array(256 * 1024 + 7)
+    bytes.forEach((_, index) => {
+      bytes[index] = index % 251
+    })
+    const accumulator = new MobileImageBase64Accumulator()
+    accumulator.append(bytes.subarray(0, 123_457))
+    accumulator.append(bytes.subarray(123_457))
+
+    expect(decodeBase64(accumulator.finish())).toEqual(bytes)
+  })
+})
diff --git a/mobile/src/session/mobile-image-base64-accumulator.ts b/mobile/src/session/mobile-image-base64-accumulator.ts
new file mode 100644
index 00000000000..b56150737ef
--- /dev/null
+++ b/mobile/src/session/mobile-image-base64-accumulator.ts
@@ -0,0 +1,54 @@
+const MOBILE_IMAGE_BASE64_BINARY_CHUNK_BYTES = 8190
+const MOBILE_IMAGE_BASE64_CHUNK_BYTES = 256 * 1024 - 1
+
+function encodeMobileImageBytes(bytes: Uint8Array): string {
+  const encoded: string[] = []
+  for (
+    let offset = 0;
+    offset < bytes.byteLength;
+    offset += MOBILE_IMAGE_BASE64_BINARY_CHUNK_BYTES
+  ) {
+    const end = Math.min(offset + MOBILE_IMAGE_BASE64_BINARY_CHUNK_BYTES, bytes.byteLength)
+    let binary = ''
+    for (let index = offset; index < end; index += 1) {
+      binary += String.fromCharCode(bytes[index]!)
+    }
+    encoded.push(btoa(binary))
+  }
+  return encoded.join('')
+}
+
+export class MobileImageBase64Accumulator {
+  private readonly staging = new Uint8Array(MOBILE_IMAGE_BASE64_CHUNK_BYTES)
+  private readonly encodedChunks: string[] = []
+  private stagingLength = 0
+
+  append(bytes: Uint8Array): void {
+    let offset = 0
+    while (offset < bytes.byteLength) {
+      const copied = Math.min(
+        this.staging.byteLength - this.stagingLength,
+        bytes.byteLength - offset
+      )
+      this.staging.set(bytes.subarray(offset, offset + copied), this.stagingLength)
+      this.stagingLength += copied
+      offset += copied
+      if (this.stagingLength === this.staging.byteLength) {
+        this.flushStaging()
+      }
+    }
+  }
+
+  finish(): string {
+    this.flushStaging()
+    return this.encodedChunks.join('')
+  }
+
+  private flushStaging(): void {
+    if (this.stagingLength === 0) {
+      return
+    }
+    this.encodedChunks.push(encodeMobileImageBytes(this.staging.subarray(0, this.stagingLength)))
+    this.stagingLength = 0
+  }
+}
diff --git a/mobile/src/session/mobile-image-source-picker.test.ts b/mobile/src/session/mobile-image-source-picker.test.ts
index a165e963329..fbdd9eb5dec 100644
--- a/mobile/src/session/mobile-image-source-picker.test.ts
+++ b/mobile/src/session/mobile-image-source-picker.test.ts
@@ -1,4 +1,5 @@
-import { describe, expect, it, vi } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { CLIPBOARD_IMAGE_MAX_SOURCE_BYTES } from '../../../src/shared/clipboard-image'
 
 vi.mock('expo-image-picker', () => ({
   requestMediaLibraryPermissionsAsync: vi.fn(),
@@ -7,6 +8,9 @@ vi.mock('expo-image-picker', () => ({
 vi.mock('expo-document-picker', () => ({
   getDocumentAsync: vi.fn()
 }))
+vi.mock('expo-file-system', () => ({
+  File: vi.fn()
+}))
 
 import { ImageLibraryPermissionError, pickMobileImage } from './mobile-image-source-picker'
 
@@ -15,17 +19,53 @@ const granted = { granted: true } as Awaited<
 >
 const denied = { granted: false } as typeof granted
 
+function fileFactory(
+  bytes: Uint8Array,
+  options?: { fileSize?: number; handleSize?: number | null; readError?: Error }
+) {
+  const close = vi.fn()
+  const chunks = [bytes]
+  const readBytes = vi.fn(() => {
+    if (options?.readError) {
+      throw options.readError
+    }
+    return chunks.shift() ?? new Uint8Array()
+  })
+  const open = vi.fn(() => ({
+    size: options?.handleSize ?? options?.fileSize ?? bytes.length,
+    readBytes,
+    close
+  }))
+  const createFile = vi.fn(() => ({ size: options?.fileSize ?? bytes.length, open }))
+  return { close, createFile, open }
+}
+
 describe('pickMobileImage', () => {
-  it('returns base64 from the photo library', async () => {
+  afterEach(() => vi.restoreAllMocks())
+
+  it('reads a photo URI without relying on React Native fetch', async () => {
+    const bytes = new Uint8Array([0, 1, 2, 3])
+    const file = fileFactory(bytes)
+    const launchLibrary = vi.fn().mockResolvedValue({
+      canceled: false,
+      assets: [{ uri: 'file:///x.jpg', fileSize: bytes.length }]
+    })
+    const fetchSpy = vi
+      .spyOn(globalThis, 'fetch')
+      .mockRejectedValue(new Error('Network request failed'))
     const result = await pickMobileImage('library', {
       requestLibraryPermission: vi.fn().mockResolvedValue(granted),
-      launchLibrary: vi.fn().mockResolvedValue({
-        canceled: false,
-        assets: [{ uri: 'file:///x.jpg', base64: 'AAAA' }]
-      })
+      launchLibrary,
+      createFile: file.createFile
     })
 
-    expect(result).toEqual({ base64: 'AAAA', uri: 'file:///x.jpg' })
+    expect(result).toEqual({
+      base64: Buffer.from(bytes).toString('base64'),
+      uri: 'file:///x.jpg'
+    })
+    expect(launchLibrary).toHaveBeenCalledWith(expect.objectContaining({ base64: false }))
+    expect(fetchSpy).not.toHaveBeenCalled()
+    expect(file.close).toHaveBeenCalledTimes(1)
   })
 
   it('throws when photo library permission is denied', async () => {
@@ -48,22 +88,21 @@ describe('pickMobileImage', () => {
 
   it('reads a picked file URI into base64 for the files source', async () => {
     const bytes = new Uint8Array([1, 2, 3, 4])
-    const fetchSpy = vi
-      .spyOn(globalThis, 'fetch')
-      .mockResolvedValue(new Response(bytes.buffer, { headers: { 'content-type': 'image/png' } }))
+    const file = fileFactory(bytes)
 
     const result = await pickMobileImage('files', {
       launchFiles: vi.fn().mockResolvedValue({
         canceled: false,
-        assets: [{ uri: 'file:///doc.png' }]
-      })
+        assets: [{ uri: 'file:///doc.png', size: bytes.length }]
+      }),
+      createFile: file.createFile
     })
 
     expect(result).toEqual({
       base64: Buffer.from(bytes).toString('base64'),
       uri: 'file:///doc.png'
     })
-    fetchSpy.mockRestore()
+    expect(file.close).toHaveBeenCalledTimes(1)
   })
 
   it('returns null when the files picker is cancelled', async () => {
@@ -73,4 +112,33 @@ describe('pickMobileImage', () => {
 
     expect(result).toBeNull()
   })
+
+  it('rejects an oversized asset before opening it', async () => {
+    const file = fileFactory(new Uint8Array([1]))
+    await expect(
+      pickMobileImage('files', {
+        launchFiles: vi.fn().mockResolvedValue({
+          canceled: false,
+          assets: [{ uri: 'file:///huge.png', size: CLIPBOARD_IMAGE_MAX_SOURCE_BYTES + 1 }]
+        }),
+        createFile: file.createFile
+      })
+    ).rejects.toThrow('Clipboard image is too large')
+    expect(file.createFile).not.toHaveBeenCalled()
+    expect(file.open).not.toHaveBeenCalled()
+  })
+
+  it('closes the file handle when reading fails', async () => {
+    const file = fileFactory(new Uint8Array(), { fileSize: 4, readError: new Error('read failed') })
+    await expect(
+      pickMobileImage('files', {
+        launchFiles: vi.fn().mockResolvedValue({
+          canceled: false,
+          assets: [{ uri: 'file:///broken.png', size: 4 }]
+        }),
+        createFile: file.createFile
+      })
+    ).rejects.toThrow('read failed')
+    expect(file.close).toHaveBeenCalledTimes(1)
+  })
 })
diff --git a/mobile/src/session/mobile-image-source-picker.ts b/mobile/src/session/mobile-image-source-picker.ts
index 7f510494618..bf9c529cc25 100644
--- a/mobile/src/session/mobile-image-source-picker.ts
+++ b/mobile/src/session/mobile-image-source-picker.ts
@@ -1,8 +1,12 @@
-// Why: import from 'buffer' (the npm polyfill), not 'node:buffer' — Metro
-// can't resolve Node's builtin in a React Native bundle.
-import { Buffer } from 'buffer'
 import * as DocumentPicker from 'expo-document-picker'
+import { File as FsFile } from 'expo-file-system'
 import * as ImagePicker from 'expo-image-picker'
+import {
+  CLIPBOARD_IMAGE_MAX_SOURCE_BYTES,
+  assertClipboardImageBase64LengthWithinLimit,
+  assertClipboardImageByteLengthWithinLimit
+} from '../../../src/shared/clipboard-image'
+import { MobileImageBase64Accumulator } from './mobile-image-base64-accumulator'
 
 export type MobileImageSource = 'library' | 'files'
 
@@ -21,18 +25,68 @@ export class ImageLibraryPermissionError extends Error {
   }
 }
 
-// Why: expo-document-picker returns a file URI, not base64. Read it through
-// fetch + Buffer so we match the base64 contract the upload pipeline expects
-// without pulling in expo-file-system.
-async function readUriAsBase64(uri: string): Promise<string> {
-  const response = await fetch(uri)
-  const bytes = new Uint8Array(await response.arrayBuffer())
-  return Buffer.from(bytes).toString('base64')
+const MOBILE_IMAGE_READ_CHUNK_BYTES = 256 * 1024
+
+type MobileImageFileHandle = {
+  readonly size: number | null
+  readBytes(length: number): Uint8Array
+  close(): void
+}
+
+type MobileImageFile = {
+  readonly size: number
+  open(): MobileImageFileHandle
+}
+
+export type MobileImageFileFactory = (uri: string) => MobileImageFile
+
+function defaultMobileImageFileFactory(uri: string): MobileImageFile {
+  return new FsFile(uri)
+}
+
+async function readUriAsBase64(
+  uri: string,
+  declaredSize: number | undefined,
+  createFile: MobileImageFileFactory
+): Promise<string> {
+  if (typeof declaredSize === 'number' && Number.isFinite(declaredSize)) {
+    assertClipboardImageByteLengthWithinLimit(declaredSize)
+  }
+
+  const file = createFile(uri)
+  assertClipboardImageByteLengthWithinLimit(file.size)
+  const handle = file.open()
+  try {
+    if (handle.size !== null) {
+      assertClipboardImageByteLengthWithinLimit(handle.size)
+    }
+    const accumulator = new MobileImageBase64Accumulator()
+    let bytesRead = 0
+    while (bytesRead <= CLIPBOARD_IMAGE_MAX_SOURCE_BYTES) {
+      const requested = Math.min(
+        MOBILE_IMAGE_READ_CHUNK_BYTES,
+        CLIPBOARD_IMAGE_MAX_SOURCE_BYTES - bytesRead + 1
+      )
+      const bytes = handle.readBytes(requested)
+      if (bytes.byteLength === 0) {
+        break
+      }
+      bytesRead += bytes.byteLength
+      assertClipboardImageByteLengthWithinLimit(bytesRead)
+      accumulator.append(bytes)
+    }
+    const base64 = accumulator.finish()
+    assertClipboardImageBase64LengthWithinLimit(base64.length)
+    return base64
+  } finally {
+    handle.close()
+  }
 }
 
 async function pickFromLibrary(
   requestPermission: typeof ImagePicker.requestMediaLibraryPermissionsAsync = ImagePicker.requestMediaLibraryPermissionsAsync,
-  launch: typeof ImagePicker.launchImageLibraryAsync = ImagePicker.launchImageLibraryAsync
+  launch: typeof ImagePicker.launchImageLibraryAsync = ImagePicker.launchImageLibraryAsync,
+  createFile: MobileImageFileFactory = defaultMobileImageFileFactory
 ): Promise<PickedMobileImage | null> {
   const permission = await requestPermission()
   // Why: `granted` covers full + limited iOS access; only a hard denial blocks us.
@@ -41,7 +95,7 @@ async function pickFromLibrary(
   }
   const result = await launch({
     mediaTypes: ['images'],
-    base64: true,
+    base64: false,
     allowsMultipleSelection: false,
     quality: 1
   })
@@ -49,7 +103,7 @@ async function pickFromLibrary(
     return null
   }
   const asset = result.assets[0]
-  const base64 = asset?.base64 ?? (asset?.uri ? await readUriAsBase64(asset.uri) : null)
+  const base64 = asset?.uri ? await readUriAsBase64(asset.uri, asset.fileSize, createFile) : null
   if (!base64) {
     return null
   }
@@ -57,7 +111,8 @@ async function pickFromLibrary(
 }
 
 async function pickFromFiles(
-  launch: typeof DocumentPicker.getDocumentAsync = DocumentPicker.getDocumentAsync
+  launch: typeof DocumentPicker.getDocumentAsync = DocumentPicker.getDocumentAsync,
+  createFile: MobileImageFileFactory = defaultMobileImageFileFactory
 ): Promise<PickedMobileImage | null> {
   const result = await launch({
     type: 'image/*',
@@ -71,7 +126,8 @@ async function pickFromFiles(
   if (!asset?.uri) {
     return null
   }
-  return { base64: await readUriAsBase64(asset.uri), uri: asset.uri }
+  const base64 = await readUriAsBase64(asset.uri, asset.size, createFile)
+  return base64 ? { base64, uri: asset.uri } : null
 }
 
 export async function pickMobileImage(
@@ -80,10 +136,11 @@ export async function pickMobileImage(
     readonly requestLibraryPermission?: typeof ImagePicker.requestMediaLibraryPermissionsAsync
     readonly launchLibrary?: typeof ImagePicker.launchImageLibraryAsync
     readonly launchFiles?: typeof DocumentPicker.getDocumentAsync
+    readonly createFile?: MobileImageFileFactory
   }
 ): Promise<PickedMobileImage | null> {
   if (source === 'library') {
-    return pickFromLibrary(deps?.requestLibraryPermission, deps?.launchLibrary)
+    return pickFromLibrary(deps?.requestLibraryPermission, deps?.launchLibrary, deps?.createFile)
   }
-  return pickFromFiles(deps?.launchFiles)
+  return pickFromFiles(deps?.launchFiles, deps?.createFile)
 }

From 9a2676023c0233aa953c54f868663b2028e98e73 Mon Sep 17 00:00:00 2001
From: OrcaWin <alpha-eng@stably.ai>
Date: Fri, 31 Jul 2026 01:56:13 -0700
Subject: [PATCH 12/23] fix(orchestration): prefer current authority over
 legacy fallback (#11737)

---
 skill-guides/orchestration.md                 |   2 +
 src/cli/bundled-skill-guides.ts               |   2 +-
 ...ation-current-authority-precedence.test.ts | 336 ++++++++++++++++++
 ...y-compatibility-dispatcher-test-fixture.ts |  45 ++-
 .../rpc/orchestration-legacy-compatibility.ts |  97 ++++-
 5 files changed, 477 insertions(+), 5 deletions(-)
 create mode 100644 src/main/runtime/rpc/orchestration-current-authority-precedence.test.ts

diff --git a/skill-guides/orchestration.md b/skill-guides/orchestration.md
index 05c13c7da24..e78652d4198 100644
--- a/skill-guides/orchestration.md
+++ b/skill-guides/orchestration.md
@@ -62,6 +62,8 @@ Treat the authority label on injected or formatted messages as definitive:
 - `[LEGACY READ-ONLY]` is inspection-only. It has no reply, acknowledgment, or lifecycle action.
 - An unlabeled current message uses the current guide and current grammar.
 
+An explicitly selected current Run, attested current Run binding, current Dispatch, or federated attachment takes precedence over legacy fallback. A retained adoption record alone never turns a current command into a legacy call.
+
 Database provenance, an old-looking terminal, or a legacy Run ID does not prove mutation authority. If the runtime cannot prove liveness, principal ownership, capability, or the exact legacy contract, it degrades to read-only inspection and must not fall back to local execution. Exact recovery may restore the already-live PTY once in its original inactive background tab. It must not spawn, write, signal, stop, switch, focus, split, or inject a terminal. Loss of lifecycle authority does not invalidate the existing assignment, process, or filesystem work.
 
 Compatibility retries have narrow guarantees. A pending ask, a reply, a final Dispatch settlement, and a consuming check have durable recovery identities. A-era heartbeat and escalation calls remain at-least-once across a manual A-to-B retry because identical later signals may be intentional. If an A-era ask may already have been answered, run the exact non-consuming recovery check printed by the runtime first; after its answer is printed and acknowledged, a new invocation with the same question creates a new question. Never guess among multiple identical question threads.
diff --git a/src/cli/bundled-skill-guides.ts b/src/cli/bundled-skill-guides.ts
index 369ebe53670..748d62dd1a6 100644
--- a/src/cli/bundled-skill-guides.ts
+++ b/src/cli/bundled-skill-guides.ts
@@ -30,7 +30,7 @@ const ORCA_LINEAR_MARKDOWN = "---\nname: orca-linear\ndescription: >-\n  Use Orc
 const ORCA_PER_WORKSPACE_ENV_MARKDOWN = "---\nname: orca-per-workspace-env\ndescription: >-\n  Set up, review, debug, or validate Orca per-workspace environment recipes —\n  on-demand, disposable runtimes (cloud sandboxes, VMs, or local) created fresh\n  for each workspace. Covers first-time setup (provider prerequisites, the\n  reusable base snapshot, the coding-agent auth snapshot, credentials, and\n  state), not just the per-workspace lifecycle scripts. Use to stand up\n  per-workspace environments, fix an `environmentRecipes` entry in `orca.yaml`, scaffold\n  provider lifecycle scripts, or resolve an `orca vm recipe doctor` failure.\n---\n\n# Per-Workspace Environments\n\nHelp a user stand up and maintain a repo-owned per-workspace environment recipe end to end. Each\nworkspace gets its own on-demand, disposable runtime (a cloud sandbox, a VM, or a local one),\ncreated fresh and torn down after.\n\nOrca is a **thin wrapper**: you guide, detect, and scaffold; you never own the user's cloud account,\nbilling, images, or credentials.\n\n- **You DO:** sequence the setup, detect what's detectable (provider CLI present/logged-in? recipe\n  present? `doctor` passing?), scaffold provider-templated scripts the user fills in, drive the slow\n  snapshot/auth phases with the user, and always show the next action.\n- **You DO NOT:** create accounts, choose plans/regions, invent org/project/scope ids, store or print\n  secrets, or run anything that spends money without an explicit user OK.\n\nFirst-time setup has **four phases before the per-workspace recipe runs** — easy to miss, so walk\nthem in order:\n\n1. **Prerequisites** — cloud account, provider CLI, scope/project, plan limits, git token (§2).\n2. **Base snapshot** — reusable image: tools + repo + headless build, snapshotted once (§3).\n3. **Agent-auth snapshot** — boot the base, run interactive device-auth, re-snapshot (§4).\n4. **State** — thread snapshot id / scope / project / port between phases via a state file (§6).\n\nThen the **per-workspace contract** (create/suspend/resume/destroy) runs fast (§8).\n\n**The one branch that shapes everything — connection mode:** **Orca-server** (`create` runs `orca serve`\nin the env and emits a `pairingCode`; §7c/§7f) vs **SSH** (`create` runs no server and emits a\n`connection.type:\"ssh\"` block Orca dials into; §7g/§7h). Settle this first — it changes the `create`\noutput shape and half the templates.\n\n**Quick-start (happy path):** interview the user (connection mode Orca-server vs SSH, provider, agent CLI,\ngit auth — §1.2) + read the provider's CLI docs → scaffold `scripts/orca-vm/` from §7 → run the\nbase-snapshot script, then the auth script (you invoke these by hand; not via `orca.yaml`) → wire\n`environmentRecipes` in `orca.yaml` → `orca vm recipe doctor <id> --json` (free) → then the `--provision`\nself-test loop (§9) until it passes.\n\n---\n\n## 1. Setup workflow\n\nDrive these with the user. **[CHECKPOINT]** steps need explicit confirmation — they spend money, take\na long time, or need the user at the keyboard. Never create an Orca workspace or commit unless asked.\n\n1. **Inspect the repo** for an existing `environmentRecipes` entry, `scripts/orca-vm/`, a state file, or setup\n   notes. If a working recipe exists, jump to Doctor (§9) instead of rebuilding.\n2. **Interview the user up front** — gather these choices and confirm them back before scaffolding\n   anything. Don't pick for them (§11); don't guess.\n   - **Connection mode:** how Orca attaches to the environment — an **Orca server** (the VM runs\n     `orca serve` and Orca pairs over its pairing URL; worked example §7f) or **SSH** (Orca connects to\n     the host over SSH; §7g). This decides the recipe's connection shape, so settle it first.\n   - **Provider:** Vercel Sandbox, Fly, Modal, an existing SSH host, … For non-obvious providers, also\n     ask scope/project/region and plan limits (§2). Then **read that provider's CLI/SDK docs** (or\n     `<cli> --help`) before scaffolding — you need its exact create/exec/snapshot/remove verbs.\n     If a provider advertises `ssh`, verify whether it exposes a real dialable SSH target\n     (host/port/user/key or proxy command) or only a provider-mediated interactive shell; Orca SSH mode\n     needs the former.\n   - **Coding-agent CLI + account:** which agent runs in the VM (`codex`, `claude`, …) and that the user\n     has an account for it — it gets logged in during the Phase-3 auth snapshot (§4).\n   - **Git auth:** the token source for cloning a private repo (`GH_TOKEN`/`GITHUB_TOKEN` or `gh auth\n     token`; §5).\n3. **Check prerequisites (§2)** — detect the provider CLI + auth and confirm the items above are in\n   place before any paid step.\n4. **Scaffold scripts + state file** from §7 (worked Vercel example: §7f; SSH host: §7g; Docker SSH:\n   §7h; Windows: §7i), filling in the provider's real commands. Make them executable.\n5. **[CHECKPOINT] Build the base snapshot (§3)** — paid, slow.\n6. **[CHECKPOINT] Authenticate the agent (§4)** — interactive; the user follows a URL/code. **You cannot\n   drive this step** — you run commands non-interactively, so there's no TTY for `docker exec -it` /\n   `ssh -t` to prompt against. The **user** runs the Phase-3 login in their own terminal (or via the\n   Claude Code harness bang-prefix — `! <cmd>`, with the required space after `!`); you scaffold and drive\n   the non-interactive phases around it. After kicking it off, **ask the user to report back once the login\n   finishes** — you can't observe it completing, and you need that confirmation before resuming the\n   non-interactive steps (base/auth commit, doctor, provision).\n7. **Wire the recipe** so `orca.yaml` points create/suspend/resume/destroy at the scripts (§8). The\n   workspace composer reads `environmentRecipes` from the project's primary checkout of `orca.yaml`, **not** from\n   a feature branch or worktree. So a recipe added only on a branch won't appear as a \"Run on\" option\n   until that `orca.yaml` change is committed and merged to the project's primary branch. Tell the user\n   this up front: `doctor`/`--provision` validate the scripts from the working copy on any branch, but\n   creating a workspace from the recipe in the picker needs it on primary.\n8. **Dry-run doctor** — `orca vm recipe doctor <recipe-id> --repo-path <repo> --json` (free, static; §9).\n   Fix every failure before going live.\n9. **[CHECKPOINT] Live self-test** — get the user's OK once, then run\n   `orca vm recipe doctor <recipe-id> --provision --json` as a loop: it runs create → validates →\n   destroys, and on failure returns a full transcript. Read it, fix the scripts, and re-run yourself until\n   it passes (§9). Spends cloud money; the one approval covers the loop.\n10. **[CHECKPOINT] Optional workspace test** — only if asked: create a workspace via the picker, then\n    verify sleep/wake/delete.\n\n---\n\n## 2. Phase 1 — Prerequisites\n\nThe user's responsibility; verify what's verifiable, ask for the rest, invent nothing. State which\nitems you verified vs. which the user asserted.\n\n- **Connection mode** (Orca server vs SSH) confirmed with the user — see §1 step 2; it shapes the recipe.\n- **Cloud account + plan** that allows sandboxes/VMs. Ask.\n- **Provider CLI installed + authenticated** — detect (`command -v <cli>`), check auth (e.g.\n  `vercel whoami`). If missing, point at the provider's docs; don't log them in.\n- **Scope / project / region** the sandboxes live under. Ask; flows into every script via state.\n- **Plan / timeout / RAM caps.** Record them — e.g. Vercel Hobby caps sandbox timeout at **45m**,\n  which limits both the base build and per-workspace runtime (see §10).\n- **Git token for private repos** (`GH_TOKEN`/`GITHUB_TOKEN`, or the provider's git auth; can fall back\n  to `gh auth token`). See §5.\n- **Coding-agent CLI choice** (`codex`, `claude`…) and that the user has an account — it gets\n  authenticated into the VM in Phase 3.\n\n---\n\n## 3. Phase 2 — Base snapshot (the reusable image)\n\nBuild **once**, snapshot, and every workspace boots from it in seconds instead of rebuilding.\nProvisioning + building takes a while (often ~20–30 min), so it runs behind a checkpoint. The script\nshape is §7a; key points:\n\n- Build the **headless Electron main only** (not the renderer) so it fits in plan RAM.\n- Use the VM image's package manager (`apt`/`dnf`/`apk`, per the base distro — not the provider brand).\n- Clone with the git token via `GIT_ASKPASS` (§5).\n- **Trap errors and remove the half-built sandbox** so a crash doesn't leave a paid resource running.\n- Snapshot the stopped sandbox, parse the snapshot id, and write it + scope/project/port/repo to state.\n\n---\n\n## 4. Phase 3 — Agent-auth snapshot (interactive)\n\nThe base snapshot has the agent CLI installed but **not logged in**, and per-workspace VMs are\nephemeral — so authenticate once and bake it into a second snapshot layer. Script shape is §7b:\n\n1. Boot a sandbox from the base `snapshotId` (from state).\n2. Run the agent's login **interactively** (`--interactive --tty`); the user completes the URL/code in\n   their browser. On a **headless VM this must be the device-auth flow** (e.g. `codex login --device-auth`),\n   **not** plain `codex login`: the default OAuth login starts a loopback callback server on a container\n   port the host browser can't reach, so it hangs. Device-auth instead prints a URL + code the user opens\n   on the **host**.\n3. Verify login; **refuse to snapshot an unauthenticated VM.** Prefer the status command's **exit code**\n   (most agent CLIs exit non-zero when unauthenticated). If you grep instead, agent status often goes to\n   **stderr** (e.g. `codex login status` prints \"Logged in using ChatGPT\" there), so **fold stderr first**\n   (`... 2>&1 | grep …`) and match the agent's **exact success line** — never `grep -qi 'logged in'`, which\n   also matches \"**not** logged in\" and would commit an unauthenticated image.\n4. Re-snapshot, parse the new id, and overwrite `snapshotId` in state to the authenticated image\n   (recording `authSourceSnapshotId`). Remove the auth sandbox.\n\n**You can't drive step 2 yourself** (you run commands non-interactively — no TTY). The **user** runs it in\ntheir own terminal, or via the Claude Code harness bang-prefix (`! <cmd>`, with the required space after\n`!`). You scaffold/boot the sandbox and run steps 3–4, but **you cannot observe the interactive login\nfinishing** — so **ask the user to tell you when it's done** before you verify and re-snapshot.\n\nIf the agent's credentials are short-lived, warn that the snapshot may need periodic re-auth (§10).\n\nFor disposable runtimes, do **not** treat a host agent config directory (for example `~/.codex`) as the\nauth snapshot by bind-mounting or copying it wholesale. Agent homes often contain sqlite state, hook\napproval state, caches, logs, and host-specific env/config. Instead, authenticate/configure the agent\ninside the disposable runtime and snapshot/commit that runtime layer.\n\n---\n\n## 5. Credentials\n\n- **Never** commit secrets or put them in `userData`, recipe JSON, comments, docs, or the state file.\n- **Git token:** read from env (`GH_TOKEN`/`GITHUB_TOKEN`), falling back to `gh auth token`. Pass to the\n  VM only via the provider's ephemeral `--env`. Inside the VM, use a `GIT_ASKPASS` helper with\n  `x-access-token` (not the token in the clone URL) and `GIT_TERMINAL_PROMPT=0` so a missing token fails\n  fast instead of hanging. When you write the helper from inside `bash -lc` under `set -u`, escape the\n  positional arg and the token (`\\$1`, `\\$GH_TOKEN`) so they land **literally** and resolve at git-runtime\n  — an unescaped `$1` aborts with \"unbound variable\", and a literal `$GH_TOKEN` keeps the real token out of\n  the written file. `rm -f` the helper after the clone/fetch.\n- **Provider auth:** rely on the provider CLI's logged-in session, not checked-in keys.\n- **Agent auth:** lives in the authenticated snapshot (Phase 3) — never a file you write or commit.\n- State holds only **non-secret** wiring (snapshot ids, scope, project, port, repo url/ref).\n\n---\n\n## 6. State file\n\nA repo-local JSON file (e.g. `scripts/orca-vm/<provider>-state.json`) threads non-secret values between\nphases. Each script resolves values as **env var → state → built-in fallback**, and merges its outputs\nback. Phase 2 writes the base `snapshotId`; Phase 3 overwrites it with the authenticated snapshot;\nper-workspace `create` boots from `snapshotId`.\n\n```json\n{\n  \"baseName\": \"orca-base\",\n  \"snapshotId\": \"snap_authenticated_image_id\",\n  \"authSourceSnapshotId\": \"snap_base_image_id\",\n  \"scope\": \"<provider-scope>\",\n  \"project\": \"<provider-project>\",\n  \"port\": 7331,\n  \"repoUrl\": \"https://host/org/repo.git\",\n  \"repoRef\": \"main\",\n  \"projectRoot\": \"/abs/path/on/remote/repo\"\n}\n```\n\n---\n\n## 7. Script templates (provider-agnostic shapes)\n\nScaffold under `scripts/orca-vm/`. These are **shapes** — fill in the provider's real commands. All\nreserve stdout for the final JSON and log progress to stderr. Include a shared `json_value <key>` /\n`env_value <NAME>` reader (env → state → fallback) in each.\n\n**Where each script runs:**\n\n- **Local-side** (`create`/`suspend`/`resume`/`destroy` + the base-snapshot/auth scripts the user\n  invokes) runs **on the user's desktop**, so it must run on their OS. macOS/Linux: `#!/usr/bin/env\n  bash`, `set -euo pipefail`, quoted paths. **Windows:** a bare `.sh` won't run — scaffold `.ps1`/`.cmd`\n  or require WSL/Git-Bash and point `orca.yaml` at the right launcher.\n- **Remote-side** (commands you `exec` *inside* the Linux VM) always runs in the VM's Linux shell, so\n  bash is fine there regardless of the user's OS.\n\n### 7a. Base-snapshot (`<provider>-base-snapshot.sh`) — Phase 2\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\n# resolve base_name/repo_url/repo_ref/project_root/port/scope/project/timeout (env→state→fallback)\n# resolve gh token: GH_TOKEN | GITHUB_TOKEN | `gh auth token`\n# 1. provision a sandbox (timeout/vcpus/published port/snapshot retention); trap: remove on error\n# 2. remote exec (long timeout): install pkgs + gh + corepack/pnpm + agent CLI;\n#    clone with GIT_ASKPASS(token); write headless main-only build config;\n#    dev setup; pnpm install; build CLI; build headless electron main; smoke-check tools\n# 3. snapshot stopped sandbox; parse snapshot id (fail if unparseable)\n# 4. merge { baseName, snapshotId, projectRoot, repoUrl, repoRef, port, scope, project } into state\n# print only the state JSON to stdout\n```\n\nWorked Vercel commands for this phase are in §7f. You run this script by hand (not via `orca.yaml`),\nafter exporting the first-run inputs the state file doesn't have yet — e.g. provider scope/project, the\nrepo URL/ref, and a git token (`GH_TOKEN`); later runs read them back from state.\n\n### 7b. Auth (`<provider>-base-auth.sh`) — Phase 3\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\n# read source snapshot from state.snapshotId (fail if absent); auth_name=\"${base_name}-auth\"\n# 1. boot sandbox from source snapshot; trap: remove on error\n# 2. INTERACTIVE/TTY remote exec: agent login — user completes URL/code. Headless VM: MUST use the\n#    device-auth flow (e.g. `codex login --device-auth`) — plain OAuth login binds a loopback callback\n#    port the host can't reach and hangs. User runs this themselves (you have no interactive TTY); ask\n#    them to report back when it's done before continuing.\n# 3. verify login, then refuse to snapshot if not logged in. Prefer the status command's EXIT CODE (most\n#    agent CLIs exit non-zero when unauthenticated) over string-matching. If you must grep, fold stderr\n#    first (`status 2>&1 | grep …` — many agents print the success line there) and match the agent's exact\n#    success line; never `grep -qi 'logged in'`, which also matches \"not logged in\". Codex example: §7f.\n# 4. snapshot; parse new id\n# 5. merge { snapshotId:<new>, authSourceSnapshotId:<source> } into state; remove auth sandbox\n# print only the state JSON to stdout\n```\n\n### 7c. Create (`<provider>-create.sh`) — per workspace\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\n# read authenticated snapshotId/scope/project/port/repo*/project_root (env→state→fallback)\n# fail clearly if snapshotId is missing (point back to Phases 2–3)\n# name = orca-${ORCA_VM_RECIPE_ID}-${ORCA_VM_INSTANCE_ID} (sanitized, length-capped)\n# 1. boot sandbox from snapshotId with a published port; capture the public URL → pairing address\n#    (an externally reachable wss:// URL); trap: remove sandbox on error\n# 2. remote exec: ensure repo at desired commit; rebuild only if commit changed (cache marker)\n# 3. remote exec: start orca serve in the background and read the recipe JSON it writes (see below)\n# 4. print serve's JSON to stdout, optionally enriched with userData:\n#    { schemaVersion:1, pairingCode, projectRoot, userData:{ provider, resourceId:name, snapshotId } }\n```\n\n**The exact `orca serve` invocation and its output (verified — do not improvise the flags).** Inside the\nVM, run:\n\n```bash\norca serve \\\n  --port \"$PORT\" \\\n  --project-root \"$ABS_REPO_PATH_ON_REMOTE\" \\\n  --pairing-address \"$EXTERNAL_WSS_URL\" \\\n  --recipe-json\n```\n\n**Binary name:** in a VM built from source (the Phase-2 flow), run it as `pnpm exec orca-dev serve …`\nfrom the repo root — `orca-dev` is the in-repo entrypoint and is what the §7f example uses. Plain\n`orca serve …` is the same command when the built CLI is installed on the VM's PATH. The flags/output\nare identical either way.\n\nThere is **no `--host` flag**. `--project-root` must be an absolute directory on the remote. With\n`--recipe-json` the server **stays running** and prints exactly this single object to **stdout**, then\nkeeps serving:\n\n```json\n{ \"schemaVersion\": 1, \"pairingCode\": \"<orca pairing URL>\", \"projectRoot\": \"<the --project-root you passed>\" }\n```\n\n`pairingCode` is the pairing URL, already pointing at whatever you passed as `--pairing-address` — so set\n`--pairing-address` to the externally reachable address and **pass `pairingCode` through unchanged; never\nhand-rewrite it**. Because serve runs in the foreground and doesn't exit, redirect its stdout to a file\nand poll until that file parses as JSON (and bail if the process dies — dump its stderr log). Your\n`create` script then prints that JSON (optionally merging `userData`). Concrete pattern: §7f.\n\n### 7d. Suspend / resume / destroy — per workspace\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\npayload=\"$(cat)\"                       # Orca passes lifecycle JSON on stdin\nresource_id=\"$(node -e 'const d=JSON.parse(process.argv[1]); process.stdout.write(d.recipeResult?.userData?.resourceId ?? \"\")' \"$payload\")\"\n[ -n \"$resource_id\" ] || { echo \"No resource id in lifecycle payload\" >&2; exit 1; }\n# suspend: provider suspend \"$resource_id\"\n# resume:  provider resume \"$resource_id\"; then RE-EMIT fresh recipe JSON (pairing may change)\n# destroy: provider remove \"$resource_id\"   (or set destroy: none in orca.yaml)\n```\n\n### 7e. State file — scaffold with scope/project/repo filled in and snapshot ids empty (§6).\n\n### 7f. Worked example — Vercel Sandbox (all three phases)\n\nA real, working shape (the Vercel surface is a CLI: `vercel sandbox create|exec|snapshot|remove`). Adapt\nnames; verify flags against `vercel sandbox --help` for the user's CLI version before relying on them.\nThese ground §7a (base snapshot) and §7b (auth), which are otherwise generic skeletons.\n\n**Phase 2 — base snapshot (§7a):** provision → install tools + clone + headless build → snapshot.\n\n```bash\n# provision a fresh build sandbox (retain a couple of snapshots); trap-remove on error\nvercel sandbox create --name \"$base\" --runtime node24 --timeout 30m --vcpus 4 --publish-port \"$port\" \\\n  --snapshot-expiration 30d --keep-last-snapshots 2 \"${vercel_args[@]}\" >&2\n# remote build (long timeout): install pkgs+gh+pnpm+agent CLI, clone with GIT_ASKPASS (write the helper\n# with LITERAL \\$1/\\$GH_TOKEN so they resolve at git-runtime, not write-time — see §5/§7f create — then\n# `rm -f /tmp/askpass.sh`), write the headless main-only build config (drop the renderer), dev setup,\n# build CLI + headless main, smoke-check\nvercel sandbox exec \"$base\" \"${vercel_args[@]}\" --timeout 25m --env \"GH_TOKEN=$gh_token\" … -- bash -lc '…build…' >&2\n# snapshot the STOPPED sandbox and parse the id from CLI output (fail if unparseable)\nout=\"$(vercel sandbox snapshot \"$base\" --stop --expiration 30d \"${vercel_args[@]}\" 2>&1)\"; printf '%s\\n' \"$out\" >&2\nsnapshot_id=\"$(printf '%s\\n' \"$out\" | sed -nE 's/.*(snap_[A-Za-z0-9]+).*/\\1/p' | tail -1)\"\n# merge { baseName, snapshotId, scope, project, port, repoUrl, repoRef, projectRoot } into state; print state JSON\n```\n\n**Phase 3 — agent-auth snapshot (§7b):** boot the base, log the agent in interactively, re-snapshot.\n(`codex` below is an example — substitute the user's chosen agent's login/status verbs, e.g. `claude`.)\n\n```bash\nvercel sandbox create --name \"$auth\" --snapshot \"$snapshot_id\" --timeout 30m --publish-port \"$port\" \"${vercel_args[@]}\" >&2\n# INTERACTIVE — the USER runs this in their own terminal (you have no interactive TTY) and completes the\n# URL/code on the HOST. --device-auth is MANDATORY on a headless VM: plain `codex login` binds a loopback\n# callback port the host browser can't reach and hangs. Ask the user to report back when login finishes.\nvercel sandbox exec --interactive --tty \"$auth\" \"${vercel_args[@]}\" -- bash -lc 'codex login --device-auth'\n# refuse to snapshot an unauthenticated VM — fold stderr, match codex's exact success line (§4)\nvercel sandbox exec \"$auth\" \"${vercel_args[@]}\" --timeout 30s -- bash -lc 'codex login status 2>&1' | grep -Eqi 'Logged in using ChatGPT|Logged in via device' \\\n  || { echo \"agent not logged in; not snapshotting\" >&2; exit 1; }\nout=\"$(vercel sandbox snapshot \"$auth\" --stop --expiration 30d \"${vercel_args[@]}\" 2>&1)\"; printf '%s\\n' \"$out\" >&2\nnew_id=\"$(printf '%s\\n' \"$out\" | sed -nE 's/.*(snap_[A-Za-z0-9]+).*/\\1/p' | tail -1)\"\n# overwrite state.snapshotId = new_id, record authSourceSnapshotId = snapshot_id; remove the auth sandbox\n```\n\n**Per-workspace `create`** (the fast path):\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\n# resolve from env→state→fallback: snapshot_id, scope, project, port, repo_url, repo_ref, project_root\nvercel_args=(); [ -n \"$scope\" ] && vercel_args+=(--scope \"$scope\"); [ -n \"$project\" ] && vercel_args+=(--project \"$project\")\n[ -n \"$snapshot_id\" ] || { echo \"snapshotId missing — run Phases 2–3 first\" >&2; exit 1; }\ngh_token=\"${GH_TOKEN:-${GITHUB_TOKEN:-$(command -v gh >/dev/null 2>&1 && gh auth token 2>/dev/null || true)}}\"\nname=\"orca-${ORCA_VM_RECIPE_ID:-vercel-sandbox}-${ORCA_VM_INSTANCE_ID:-$(date +%s)}\"  # sanitize+cap to 63 chars\n\n# Arm cleanup BEFORE create so a failing create can't leak a half-built paid sandbox.\ncleanup_on_error() { [ \"$?\" -ne 0 ] && vercel sandbox remove \"$name\" \"${vercel_args[@]}\" >/dev/null 2>&1 || true; }\ntrap cleanup_on_error EXIT\n\n# 1. boot from the authenticated snapshot, publish the serve port\ncreate_output=\"$(vercel sandbox create --name \"$name\" --snapshot \"$snapshot_id\" \\\n  --timeout 30m --publish-port \"$port\" \"${vercel_args[@]}\" 2>&1)\"; printf '%s\\n' \"$create_output\" >&2\n# Vercel prints the published https URL; derive the external wss:// pairing address from it\npublic_url=\"$(printf '%s\\n' \"$create_output\" | sed -nE 's#.*(https://[^[:space:]]+\\.vercel\\.run).*#\\1#p' | head -1)\"\n[ -n \"$public_url\" ] || { echo \"no published URL in create output\" >&2; exit 1; }\npairing_ws=\"${public_url/https:\\/\\//wss://}\"\n\n# 2. (remote) ensure the repo is at the right commit; rebuild only if the commit changed (cache marker)\nvercel sandbox exec \"$name\" \"${vercel_args[@]}\" --timeout 20m \\\n  --env \"GH_TOKEN=$gh_token\" --env \"ORCA_PROJECT_ROOT=$project_root\" \\\n  --env \"ORCA_REPO_URL=$repo_url\" --env \"ORCA_REPO_REF=$repo_ref\" \\\n  -- bash -lc 'set -euo pipefail; cd \"$ORCA_PROJECT_ROOT\"; \\\n    # Re-establish git auth for the private-repo fetch (why + full rationale: §5); else it hangs on a prompt.\n    # Load-bearing escaping: \\$1 and \\$GH_TOKEN must land LITERALLY and resolve at git-runtime. Test after\n    # any edit here — reformatting the nested printf/node quoting silently breaks the fetch or leaks the token.\n    if [ -n \"${GH_TOKEN:-}\" ]; then \\\n      printf \"%s\\n\" \"#!/usr/bin/env bash\" \"case \\\"\\$1\\\" in *Username*) echo x-access-token;; *Password*) echo \\\"\\$GH_TOKEN\\\";; esac\" > /tmp/askpass.sh; \\\n      chmod 700 /tmp/askpass.sh; export GIT_ASKPASS=/tmp/askpass.sh GIT_TERMINAL_PROMPT=0; fi; \\\n    git fetch origin \"$ORCA_REPO_REF\"; \\\n    git checkout -B \"$ORCA_REPO_REF\" FETCH_HEAD; \\\n    rm -f /tmp/askpass.sh; \\\n    c=\"$(git rev-parse HEAD)\"; [ -f .orca-built ] && [ \"$(cat .orca-built)\" = \"$c\" ] || { \\\n      pnpm install --prefer-offline && pnpm run build:cli && \\\n      node config/scripts/run-electron-vite-build.mjs --config config/electron-vite.vm-serve.config.ts && \\\n      printf \"%s\" \"$c\" > .orca-built; }' >&2\n\n# 3. (remote) start orca serve in the background, writing recipe JSON to a file; poll until it parses\nrecipe_json=\"$(vercel sandbox exec \"$name\" \"${vercel_args[@]}\" --timeout 60s \\\n  --env \"ORCA_PORT=$port\" --env \"ORCA_PROJECT_ROOT=$project_root\" --env \"ORCA_PAIRING_ADDRESS=$pairing_ws\" \\\n  -- bash -lc 'set -euo pipefail; cd \"$ORCA_PROJECT_ROOT\"; rm -f /tmp/orca-recipe.json /tmp/orca-serve.log; \\\n    nohup pnpm exec orca-dev serve --port \"$ORCA_PORT\" --project-root \"$ORCA_PROJECT_ROOT\" \\\n      --pairing-address \"$ORCA_PAIRING_ADDRESS\" --recipe-json >/tmp/orca-recipe.json 2>/tmp/orca-serve.log </dev/null & \\\n    pid=$!; for _ in $(seq 1 80); do \\\n      node -e \"JSON.parse(require(\\\"node:fs\\\").readFileSync(\\\"/tmp/orca-recipe.json\\\",\\\"utf8\\\"))\" >/dev/null 2>&1 && { cat /tmp/orca-recipe.json; exit 0; }; \\\n      kill -0 \"$pid\" 2>/dev/null || { cat /tmp/orca-serve.log >&2; exit 1; }; sleep 0.25; \\\n    done; cat /tmp/orca-serve.log >&2; echo \"serve recipe JSON timed out\" >&2; exit 1')\"\n\n# 4. print serve's JSON enriched with userData (single object on stdout)\nnode -e 'const p=JSON.parse(process.argv[1]); console.log(JSON.stringify({...p, schemaVersion:1,\n  userData:{...p.userData, provider:\"vercel-sandbox\", resourceId:process.argv[2], snapshotId:process.argv[3]}}))' \\\n  \"$recipe_json\" \"$name\" \"$snapshot_id\"\ntrap - EXIT\n```\n\n`suspend`/`resume`/`destroy` use `vercel sandbox stop|...|remove \"$resource_id\"` reading\n`userData.resourceId` from stdin (§7d). This is the **Orca-server** connection mode (the recipe emits a\npairing URL). If the user chose **SSH** in the §1 interview, use §7g instead.\n\n### 7g. Worked example — existing SSH host (SSH connection mode)\n\nSSH mode is **fundamentally different from §7c/§7f**, not a relabeling of them:\n\n- **`create` does NOT run `orca serve` and does NOT emit a `pairingCode`.** Orca itself connects to the\n  host over its SSH relay, brings up the git + filesystem providers, and imports the repo. The script's\n  only job is to make the host ready and **print SSH connection details** Orca will dial.\n- The result uses a `connection` block with `type: \"ssh\"` and a `target`, **not** the flat\n  `pairingCode`/`projectRoot` shape. Exact shape (Orca rejects anything else):\n\n```json\n{\n  \"schemaVersion\": 1,\n  \"connection\": {\n    \"type\": \"ssh\",\n    \"projectRoot\": \"/abs/path/to/repo/on/host\",\n    \"target\": {\n      \"label\": \"my-box\",\n      \"host\": \"192.0.2.10\",\n      \"port\": 22,\n      \"username\": \"ubuntu\",\n      \"identityFile\": \"~/.ssh/id_ed25519\",\n      \"jumpHost\": \"bastion.example.com\",\n      \"proxyCommand\": \"cloudflared access ssh --hostname %h\",\n      \"relayGracePeriodSeconds\": 0,\n      \"portForwards\": []\n    }\n  }\n}\n```\n\n`label`, `host`, `port`, `username` are required; the rest are optional — omit any you don't need.\n\n**Networking → which `target` fields to set** (how *your desktop* reaches the box — there is no\n`orca serve` URL in SSH mode):\n\n- Public IP / DNS, or a Tailscale/VPN address → `host`; SSH port → `port` (usually 22).\n- Key auth → `identityFile` (add `identitiesOnly: true` if the agent has many keys).\n- Through a bastion → `jumpHost` (a `user@host` ProxyJump) **or** a full `proxyCommand` (e.g. an access\n  proxy). Use one, not both.\n- A service port the workspace needs → add entries to `portForwards`.\n- `relayGracePeriodSeconds` (optional): how long Orca keeps the SSH relay alive after the workspace\n  detaches before tearing it down; `0` = tear down immediately. Leave it off unless the user wants a\n  reconnect grace window.\n\n**Toolchain & agent auth on a persistent (no-snapshot) host — do this ONCE, by hand, before wiring the\nrecipe** (there's no base image to bake; the host *is* the base). Run the §7f Phase-2 install steps and\nthe §7f Phase-3 `<agent> login --device-auth` **directly over SSH on the host** (interactive, e.g.\n`ssh -t user@host '<agent> login --device-auth'`). After that the host stays ready across workspaces.\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\n# resolve from env→state→fallback (default unset optionals to \"\"): ssh_username, host,\n#   ssh_port (default 22), identity_file, jump_host, proxy_command, project_root, repo_url, repo_ref\n: \"${identity_file:=}\"; : \"${jump_host:=}\"; : \"${proxy_command:=}\"   # avoid set -u aborts on optionals\ngh_token=\"${GH_TOKEN:-${GITHUB_TOKEN:-$(command -v gh >/dev/null 2>&1 && gh auth token 2>/dev/null || true)}}\"\nssh_target=\"${ssh_username}@${host}\"\nssh_opts=(-p \"$ssh_port\"); [ -n \"$identity_file\" ] && ssh_opts+=(-i \"$identity_file\")\n# Why: a fresh host's key isn't in known_hosts; a StrictHostKeyChecking prompt would HANG a\n# non-interactive create. Pre-add the key (or set the option) so it can't block.\nssh-keyscan -p \"$ssh_port\" \"$host\" >> \"$HOME/.ssh/known_hosts\" 2>/dev/null || true\n\n# 1. ensure the repo is present and at the right commit on the host (NO orca serve here)\nssh \"${ssh_opts[@]}\" \"$ssh_target\" \\\n  \"GH_TOKEN='$gh_token' GIT_TERMINAL_PROMPT=0 bash -lc '\n     set -euo pipefail\n     [ -d \\\"$project_root/.git\\\" ] || git clone \\\"$repo_url\\\" \\\"$project_root\\\"\n     cd \\\"$project_root\\\" && git fetch origin \\\"$repo_ref\\\" && git checkout -B \\\"$repo_ref\\\" FETCH_HEAD\n   '\" >&2\n\n# 2. print the SSH connection block (NO pairingCode, NO orca serve). host/port/username tell Orca's\n#    relay how to dial in; identityFile/jumpHost/proxyCommand/portForwards are emitted when set.\nnode -e 'const [host,port,user,idf,jh,pc,root]=process.argv.slice(1);\n  const target={ label:\"per-workspace-host\", host, port:Number(port), username:user };\n  if(idf) target.identityFile=idf; if(jh) target.jumpHost=jh; if(pc) target.proxyCommand=pc;\n  // add target.portForwards=[...] here if the workspace needs forwarded service ports\n  console.log(JSON.stringify({ schemaVersion:1, connection:{ type:\"ssh\", projectRoot:root, target } }))' \\\n  \"$host\" \"$ssh_port\" \"$ssh_username\" \"$identity_file\" \"$jump_host\" \"$proxy_command\" \"$project_root\"\n```\n\n`suspend`/`resume`/`destroy`: on a persistent host there's usually nothing to tear down — set\n`destroy: none` and omit suspend/resume. (Orca still disconnects/reconnects its own SSH relay on\nsleep/wake/delete — that's separate from these scripts.)\n\nIf the SSH host is instead an **ephemeral/snapshot-capable VM** (your hypervisor, or a cloud VM with\nimage support), keep the §7f Phase-2/3 base-image model for provisioning, but still emit the\n`connection.type:\"ssh\"` block above instead of starting `orca serve`.\n\n### 7h. Worked example — local Docker SSH (SSH connection mode)\n\nLocal Docker can model an ephemeral SSH VM without cloud cost: build a base image with `sshd`, tools,\nrepo prerequisites, and the agent CLI; run an **interactive auth container** once; then `docker commit`\nthat container as the authenticated image used by per-workspace `create`.\n\nKey points:\n\n- Publish container SSH to a random localhost port (`-p 127.0.0.1::22`) and emit\n  `connection.type:\"ssh\"` with `host:\"127.0.0.1\"`, that port, `username`, `identityFile`, and\n  `identitiesOnly:true`.\n- Generate a repo-local SSH key if needed, but gitignore the private/public key files.\n- **Bake SSH host keys into the base image** (`ssh-keygen -A` at **build** time; at runtime only generate\n  if absent). Ephemeral containers all present the **same** host key, so `known_hosts` on `127.0.0.1`\n  doesn't churn as the published port rotates across workspaces (otherwise every container's freshly\n  generated key collides on `localhost` and trips host-key-changed warnings).\n- The auth image is the Docker equivalent of Phase 3: the **user** runs the agent login **inside** the\n  container (you can't drive it — you have no interactive TTY), configures proxy env/config, approves\n  hooks, and you commit once they report it's done. On a headless container use the **device-auth** flow\n  (§4). Verify login before committing — exit code, or fold stderr and match the exact success line (§4).\n- Do not bind-mount or copy the host's full agent home into the image. Let each container have writable\n  agent state; only the committed auth image should carry reusable authenticated state.\n- If committing from an interactive shell, force the runtime entrypoint back to `sshd`:\n  `docker commit --change='ENTRYPOINT [\"/usr/local/bin/orca-docker-ssh-entrypoint\"]' …`.\n- `destroy` should read `recipeResult.userData.resourceId` and run `docker rm -f \"$resource_id\"`.\n\nValidation before wiring/live use:\n\n```bash\ndocker image inspect \"$auth_image\" --format '{{json .Config.Entrypoint}}'\ndocker run -d --name \"$name\" -p 127.0.0.1::22 -e \"ORCA_SSH_PUBLIC_KEY=$pubkey\" \"$auth_image\"\ndocker ps -a --filter \"name=$name\"\ndocker logs \"$name\"\nssh -i \"$key\" -p \"$port\" -o IdentitiesOnly=yes user@127.0.0.1 'codex --version'\n```\n\nIf the container exits immediately, inspect logs before the cleanup trap removes it; a committed\ninteractive image with `ENTRYPOINT [\"bash\"]` is a common cause.\n\nAlso confirm the **host key is stable** across containers: the SSH `ssh -i … 127.0.0.1` dial should not\ntrigger a host-key-changed warning when a second container reuses the port. If it does, the host keys\nweren't baked into the base image (see the `ssh-keygen -A` point above).\n\n### 7i. Windows local-side scripts\n\nThe local-side scripts run on the user's desktop. On **Windows**, a bare `.sh` won't execute. Either\nrequire WSL/Git-Bash (and point `orca.yaml` at e.g. `bash ./scripts/orca-vm/<name>.sh` via a `.cmd`\nlauncher), or scaffold PowerShell equivalents. Minimal PowerShell shape:\n\n```powershell\n#requires -Version 5\n$ErrorActionPreference = 'Stop'\n# resolve env→state→fallback; run the provider CLI / ssh the same way;\n# capture provider output; build the result object for the chosen mode and write ONE line of JSON to stdout.\n# Orca-server mode: @{ schemaVersion=1; pairingCode=$pairingCode; projectRoot=$projectRoot; userData=@{...} }\n# SSH mode:        @{ schemaVersion=1; connection=@{ type=\"ssh\"; projectRoot=$projectRoot;\n#                     target=@{ label=$label; host=$host; port=$port; username=$user } } }  (see §7g/§7h)\n($result | ConvertTo-Json -Compress -Depth 6)\n# progress/errors → Write-Error / the error stream, never stdout.\n```\n\nThe remote-side commands you run *inside* the Linux VM stay bash regardless of the desktop OS.\n\n---\n\n## 8. Per-workspace recipe contract (the fast path)\n\nOnce the authenticated snapshot exists, this runs on every workspace create. Define recipes in\n`orca.yaml`:\n\n```yaml\nenvironmentRecipes:\n  - id: cloud-sandbox\n    name: Cloud Sandbox\n    create: ./scripts/orca-vm/cloud-sandbox-create.sh\n    suspend: ./scripts/orca-vm/cloud-sandbox-suspend.sh\n    resume: ./scripts/orca-vm/cloud-sandbox-resume.sh\n    destroy: ./scripts/orca-vm/cloud-sandbox-destroy.sh\n```\n\n`create` runs **locally from the repo root** and prints **one** JSON object to stdout. Its shape depends\non the connection mode chosen in §1:\n\n**Orca-server mode** — boot the env, start `orca serve` in it, and print serve's result:\n\n```json\n{\n  \"schemaVersion\": 1,\n  \"pairingCode\": \"orca-pairing-code-or-url\",\n  \"projectRoot\": \"/absolute/path/to/repo/on/remote\",\n  \"userData\": { \"provider\": \"example\", \"resourceId\": \"provider-resource-id\" }\n}\n```\n\nHere `pairingCode` (from `orca serve --recipe-json`) and `projectRoot` are required; `schemaVersion` (`1`)\nand `userData` are optional.\n\n**SSH mode** — do **not** run `orca serve`; print the `connection.type:\"ssh\"` block instead (full shape +\nworked script in §7g). `pairingCode` is **not** used in SSH mode.\n\nLifecycle hooks (all run locally):\n\n- `create`: required. Prints recipe result JSON.\n- `suspend`: optional. Sleep; reads lifecycle payload on stdin.\n- `resume`: optional. Wake; reads payload on stdin and **prints fresh recipe JSON** (pairing may change).\n- `destroy`: optional unless `destroy: none`. Delete/cleanup; reads payload on stdin.\n\nStart Orca remotely with `orca serve --port \"$PORT\" --project-root \"$ABS_ROOT\" --pairing-address\n\"$EXTERNAL_WSS_URL\" --recipe-json` (exact flags + output in §7c). Set `--pairing-address` to the\nexternally reachable address so the emitted `pairingCode` is reachable; tunneling/port mapping is the\nscript's job.\n\nBackward compatibility: `command`→`create`, `cleanup`→`destroy`, `cleanup: none`→`destroy: none`.\nPrefer the lifecycle names.\n\n---\n\n## 9. Doctor and validation\n\nValidate in two stages — the cheap dry run first, then the live self-test.\n\n### Dry run (free, non-destructive) — always do this first\n\n`orca vm recipe doctor <recipe-id> --repo-path <repo> --json` validates **static wiring only** — it does\n**not** boot anything. It checks: local-host execution (v1), repo path, recipe id exists,\ncreate/destroy/suspend/resume command paths resolve, suspend/resume are paired, and each script is\nexecutable (POSIX exec bit; skipped on Windows). Fix every failure here before spending any cloud money.\n\n### Live self-test (`--provision`) — diagnose and iterate yourself\n\n`orca vm recipe doctor <recipe-id> --repo-path <repo> --provision --json` actually runs the recipe end\nto end: it executes `create`, validates the returned recipe JSON, then runs `destroy` to **tear the\nenvironment back down** (so the test leaves nothing running, as long as `destroy` works). It spends real\ncloud money, so get the user's OK **once** before starting — that one approval covers the whole loop\nbelow; do not re-ask before each run.\n\nOn failure, the JSON result includes a `provisionTranscript` with the **complete** captured output of\neach stage so you can self-diagnose without asking the user to relay logs:\n\n```json\n{\n  \"ok\": false,\n  \"checks\": [ { \"id\": \"recipe.provision\", \"status\": \"fail\", \"message\": \"…\" } ],\n  \"provisionTranscript\": {\n    \"provision\": { \"exitCode\": 0, \"signal\": null, \"stdout\": \"…\", \"stderr\": \"…\", \"parseError\": \"…\" },\n    \"destroy\":   { \"exitCode\": 0, \"signal\": null, \"stdout\": \"…\", \"stderr\": \"…\" }\n  }\n}\n```\n\n**Run it as a loop:** read `provisionTranscript.provision.stderr` / `.stdout` / `.parseError` (and\n`destroy.*`), fix the script, and re-run `--provision` until `ok` is `true` — iterating on your own\nrather than waiting for the user to paste errors. Common reads: a non-empty `stderr` with `exitCode 0`\nplus a `parseError` means `create` ran but printed something other than the single recipe-result JSON on\nstdout (often a stray `echo` — route it to stderr, see §10); a non-zero `exitCode` is a provider/script\nfailure described in `stderr`. Each stream is redacted and capped (head+tail) — large logs keep both the\nsetup context and the failure.\n\nThe self-test cannot see provider-side truth beyond what the scripts print, so still confirm: state has a\npopulated **authenticated** `snapshotId` (Phases 2–3 done), and `destroy` is implemented/tested (or\nexplicitly `none` — in which case the self-test won't tear down, so clean up manually).\n\nFor SSH recipes, also smoke-test the exact emitted target before declaring success: dial the host/port\nwith the identity/proxy settings, run `pwd`, verify the repo path, check the agent binary, and confirm\n`destroy` removes the provider resource/container. For Docker, inspect the auth image entrypoint and do a\nstartup-only `docker run` before the full clone/install path.\n\n---\n\n## 10. Failure modes\n\n- **Build exceeds plan timeout (e.g. Hobby 45m).** Use enough vCPUs and a timeout covering the build;\n  else split work or use a higher plan. The cap also limits per-workspace runtime — surface it.\n- **Build exceeds plan RAM.** Build the **headless main only** (drop the renderer) — the biggest fitter.\n- **Private-repo clone hangs/fails.** Wrong/missing token. Use `GIT_ASKPASS` + `GIT_TERMINAL_PROMPT=0`\n  so it fails fast instead of prompting.\n- **`GIT_ASKPASS` helper aborts the clone with \"`$1: unbound variable`\".** The `printf`/heredoc that writes\n  the helper inside `bash -lc` under `set -u` expanded `$1`/`$GH_TOKEN` at **write** time. Escape them\n  (`\\$1`, `\\$GH_TOKEN`) so they land literally and resolve at git-runtime; this also keeps the real token\n  out of the file. `rm -f` the helper afterward (§5, §7f).\n- **Agent verified as \"not logged in\" despite a good login.** `codex login status` (and similar) print\n  \"Logged in …\" to **stderr**; an stdout-only `grep` misses it. Prefer the status **exit code**; if you\n  grep, fold stderr first (`status 2>&1 | grep …`) and match the exact success line — not `grep -qi\n  'logged in'`, which also matches \"not logged in\".\n- **Headless agent login hangs.** Plain OAuth `login` starts a loopback callback server on a VM/container\n  port the host browser can't reach. Use the **device-auth** flow (`login --device-auth`) — it prints a\n  URL + code the user opens on the host.\n- **`known_hosts` host-key churn on local Docker.** Each ephemeral container regenerating its SSH host key\n  collides on `127.0.0.1` as the published port rotates. Bake host keys into the base image at build time\n  (`ssh-keygen -A`; runtime generates only if absent) so all containers share one stable key (§7h).\n- **Snapshot expired/evicted.** If `create` hits an unknown snapshot id, rerun Phases 2–3 and update\n  `snapshotId`.\n- **Agent auth didn't persist.** Confirm `snapshotId` points at the **authenticated** snapshot; re-run\n  Phase 3. Warn that short-lived tokens may need periodic re-auth.\n- **Agent auth copied from the host breaks.** Do not bind-mount/copy a full host agent home; sqlite\n  files can be unwritable or host-specific, hooks may need approval again, and config may reference\n  local-only env vars. Authenticate inside the runtime and snapshot/commit that layer.\n- **Docker auth image exits immediately.** Inspect `docker image inspect … .Config.Entrypoint` and\n  `docker logs`. If the image was committed from an interactive shell, reset the entrypoint to the SSH\n  entrypoint during `docker commit`.\n- **Leaked paid resource.** Every long script must trap errors and remove the sandbox it created.\n- **`create` emits non-JSON on stdout.** A stray `echo` corrupts the result — stdout is for the final\n  JSON only; everything else to stderr. The `--provision` self-test surfaces this as `exitCode 0` + a\n  `parseError` with the offending stdout in `provisionTranscript` (§9).\n\n---\n\n## 11. Boundaries\n\n- Don't create accounts, choose plans/regions, or invent scope/project/org/image/billing ids.\n- Don't invent or store credentials; no secrets in `userData`, state, comments, docs, or commits.\n- Don't run paid/long phases (base snapshot, auth, live test) without an explicit OK.\n- Don't hide provider errors behind generic messages — preserve actionable stderr.\n- Don't make Orca own provider lifecycle beyond invoking the configured scripts.\n- Don't commit or create an Orca workspace unless asked.\n"
 
 // oxfmt-ignore
-const ORCHESTRATION_MARKDOWN = "---\nname: orchestration\ndescription: >-\n  Use Orca orchestration for structured multi-agent coordination: threaded\n  messages, blocking ask/reply flows, task dispatch, worker_done/escalation\n  waits, task DAGs, decision gates, coordinator loops, or decomposing work\n  across agents. Use `orca-cli` instead for full ownership handoffs, including\n  requests phrased as \"hand off\", \"handoff\", \"handover\", \"give this to another\n  agent\", or \"another worktree\" when the user did not explicitly ask to\n  supervise, monitor, wait for results, or coordinate a DAG. Use `orca-cli` for\n  ordinary terminal control, lightweight terminal prompts, shell commands, Orca\n  worktree management, reading or waiting on terminals, and automation of the\n  browser embedded inside Orca. Use Computer Use for browser windows, webviews,\n  Orca app UI, or desktop UI outside Orca's embedded browser.\n---\n\n# Orca Inter-Agent Orchestration\n\nOrchestration is Orca's structured coordination layer for agent messages, task ownership, dispatch state, and worker completion tracking.\n\nUse this skill when coordination state matters. For lightweight terminal prompts or basic worktree/terminal/built-in-browser control, use `orca-cli`.\n\n## Tool Boundary\n\nIf a task says to use Orca orchestration, the coordinator must create or bind a Run, create the Task with `orca orchestration task-create`, then attach the worker with either the preferred `orca orchestration worker-start` composition or the low-level `orca orchestration dispatch --inject` path.\n\nDo not substitute non-Orca subagent tools, generic agent-spawn APIs, or chat-only parallel worker features. Those may create useful workers, but they do not create Orca task/dispatch provenance, injected lifecycle preambles, `worker_done` authority, or decision gates.\n\nBefore claiming a worker was orchestrated, verify the task/dispatch exists:\n\n```bash\norca orchestration task-list --json\norca orchestration dispatch-show --task <task_id> --json\n```\n\nIf the work was accidentally run outside Orca orchestration, say so plainly. To repair provenance, rerun or revalidate the needed work through a fresh Orca terminal plus injected dispatch; do not retroactively describe the external worker as orchestrated.\n\n## When To Use\n\n- Send/reply/ask between agent terminals with persistent messages.\n- Dispatch structured tasks to workers and wait for `worker_done` or `escalation`.\n- Track task DAGs with dependencies.\n- Run coordinator loops or decision gates.\n\nDo not use orchestration merely because the user says \"hand off\", \"handoff\", \"handover\", \"give this to another agent\", or asks for another worktree/agent/model/effort. Those are full ownership transfers unless the user explicitly asks to supervise, monitor, wait for worker completion/results, coordinate a DAG, use decision gates, or keep a blocking ask/reply loop.\n\n## Preconditions\n\n- `orca status --json` should show a running runtime.\n- `orca` must be on PATH (`orca-ide` on Linux).\n- The orchestration experimental feature must be enabled in Settings > Experimental.\n- `orca orchestration` commands are RPC calls to the running Orca runtime.\n\n## Contract Migration\n\nOrca adopts a live pre-update orchestration assignment into an ordinary Run. Adoption preserves the existing agent process, PTY/session, terminal handle, tab/leaf/pane, worktree or folder workspace, Task, and Dispatch; it never restarts or replaces the worker. The retired scheduler is not revived, and a newly created attempt uses the current grammar.\n\nTreat the authority label on injected or formatted messages as definitive:\n\n- `[LEGACY COMPATIBILITY]` is live and attested. Run only the exact supported command printed with the message, using the same CLI executable and arguments that the original prompt supplied.\n- `[LEGACY RECOVERY REPLAY — MAY HAVE BEEN SEEN]` is one bounded, at-least-once cutover replay. Process it idempotently and acknowledge it only through the exact displayed guidance.\n- `[LEGACY READ-ONLY]` is inspection-only. It has no reply, acknowledgment, or lifecycle action.\n- An unlabeled current message uses the current guide and current grammar.\n\nDatabase provenance, an old-looking terminal, or a legacy Run ID does not prove mutation authority. If the runtime cannot prove liveness, principal ownership, capability, or the exact legacy contract, it degrades to read-only inspection and must not fall back to local execution. Exact recovery may restore the already-live PTY once in its original inactive background tab. It must not spawn, write, signal, stop, switch, focus, split, or inject a terminal. Loss of lifecycle authority does not invalidate the existing assignment, process, or filesystem work.\n\nCompatibility retries have narrow guarantees. A pending ask, a reply, a final Dispatch settlement, and a consuming check have durable recovery identities. A-era heartbeat and escalation calls remain at-least-once across a manual A-to-B retry because identical later signals may be intentional. If an A-era ask may already have been answered, run the exact non-consuming recovery check printed by the runtime first; after its answer is printed and acknowledged, a new invocation with the same question creates a new question. Never guess among multiple identical question threads.\n\nWhen a compatibility or recovery command returns structured next-step arguments, run those exact arguments with the same CLI executable. The arguments intentionally omit the executable name so the guidance works with `orca`, `orca-ide`, `orca-dev`, or another configured Orca CLI command. Do not translate the command from memory, broaden its recipient, or retry it as a current mutation unless the returned guidance explicitly says to.\n\nOn packaged Windows, a legacy ask uses a two-step commit/resume protocol. The initial command durably commits the question, prints its exact `ask --resume <message_id>` command, and exits with launcher status `75`; it does not wait for the answer. Run that exact resume command after the launcher or update boundary. Resume is idempotent and read-oriented: it waits for the already-committed question and does not create another one. For a WSL process that received compatibility proof at launch, use the printed executable `orca-ide` WSL resume command so the same distro and packaged launcher authority are preserved; do not substitute a PATH-resolved local CLI. Older WSL processes that never received the hidden launch token remain lifecycle read-only after the update, even while their terminal and filesystem work continue.\n\nLegacy inspection remains available without consuming mail:\n\n```bash\norca orchestration run-list --json\n# run_legacy_local is an empty audit tombstone after adoption.\norca orchestration run-show --id run_legacy_local --json\n# In run-list, find the ordinary Run whose objective is:\n# \"Recovered orchestration work from a contract update\"\norca orchestration run-show --id <adopted_run_id> --json\norca orchestration task-list --run <adopted_run_id> --json\norca orchestration inbox --full --json\norca orchestration check --terminal <legacy_handle> --peek --format --json\norca terminal read --terminal <legacy_handle> --json\norca terminal wait --terminal <legacy_handle> --for tui-idle --timeout-ms 60000 --json\n```\n\nIf the original coordinator is unavailable or cannot prove its retained authority, a current coordinator may explicitly take over the adopted Run from its own live agent terminal:\n\n```bash\norca orchestration run-use --id <adopted_run_id> --takeover-legacy --json\norca orchestration check --run <adopted_run_id> --json\n```\n\nTakeover fences only the old coordinator, binds the current one, and moves pending worker mail into current Run Delivery. It is bound to the authenticated invoking terminal; `--from` cannot name another coordinator. Live legacy workers keep their original Tasks, Dispatches, processes, filesystems, and old prompt commands; their later questions, escalations, and completion reports route to the current coordinator. Do not use takeover while the original coordinator is still actively coordinating, because its later lifecycle mutations are rejected.\n\nDo not launch a replacement editor merely because the desktop app or runtime was updated. If adoption cannot prove continuing authority, keep the original worker as the only editor until it reaches a stable handoff point, then use a new current Dispatch in a conflict-free placement for any remaining work.\n\n## Ownership\n\nNew orchestration messages and tasks belong to one explicitly bound Run. A Run is only a durable namespace and coordinator inbox; it never schedules or places workers. Lifecycle authority comes from the active Dispatch, and terminal handles remain routing metadata rather than durable identity. Send `worker_done` and `heartbeat` from the worker's own terminal; Orca routes them to that Dispatch's Run.\n\nClassify inherited context before sending lifecycle messages:\n\n- Coordinated subtask: a live coordinator owns the DAG and waits on this dispatch. Follow the preamble exactly, including `worker_done`, heartbeat/status, `ask`, and `escalation`.\n- Full handoff means ownership transfer, not supervised dispatch. The original actor is not monitoring a DAG, so do not create lifecycle obligations unless the user explicitly asks you to supervise.\n- Classify requests containing \"hand off\", \"handoff\", \"handover\", \"give this to another agent\", \"give this to another worktree\", \"another agent\", or \"another worktree\" as full handoffs by default, even when the user names a custom model or reasoning effort.\n- Use supervised orchestration only when the user explicitly asks you to \"supervise\", \"monitor\", \"wait\", \"track completion\", \"wait for worker_done\", return results, coordinate a DAG, use a decision gate, or manage ask/reply flow.\n- Do not use `orca orchestration dispatch --inject` for full handoffs. It injects a coordinator preamble that tells the worker to send `worker_done`, heartbeat, and `ask` messages, then end its turn under the original terminal's dispatch lifecycle.\n- Do not run `orca orchestration task-create`, `orca orchestration dispatch --inject`, or `orca orchestration check --wait` for full handoffs. Do not peek at terminal output after prompt delivery to monitor progress.\n- A review-only `worker_done` reports findings; it does not authorize coordinator file edits. After a review-only completion, synthesize findings, ask a decision gate if ownership is unclear, and dispatch or hand off fixes unless the user explicitly asked the coordinator to own fixes.\n- If the user's plan names a next owner agent (for example, \"then use opencode to create a PR\"), post-review corrections and PR prep belong to that named owner. The coordinator routes, synthesizes, asks decision gates when needed, and supervises; the named owner edits files and creates the PR.\n\nIf unclear, inspect orchestration state before sending lifecycle messages:\n\n```bash\norca orchestration task-list --json\norca terminal list --json\n# If inherited context includes a task id:\norca orchestration dispatch-show --task <task_id> --json\n```\n\n## Messaging\n\n```bash\norca orchestration send --subject <text> [--to <run:id|dispatch:id|legacy_handle>] [--from <handle>] [--body <text>] [--type <type>] [--priority <level>] [--thread-id <id>] [--payload <json>] [--json]\norca orchestration check [--terminal <handle>] [--ack <delivery_id>] [--peek|--all] [--types <type,...>] [--format] [--wait] [--timeout-ms <n>] [--json]\norca orchestration reply --id <msg_id> --body <text> [--from <handle>] [--json]\norca orchestration ask (--question <text>|--resume <msg_id>) [--options <csv>] [--timeout-ms <n>] [--from <handle>] [--json]\norca orchestration inbox [--limit <n>] [--json]\n```\n\nRules:\n\n- Omit `--from` unless impersonating another terminal; Orca auto-resolves it from the current terminal.\n- A coordinator `check` returns the bound Run's oldest FIFO Delivery (up to 50 messages) and replays that exact batch until `--ack <delivery_id>`. Process every message before acknowledging; `check --ack <id> --wait` acknowledges, checks, and waits in one operation.\n- Use `--peek` and `--all` only for read-only history/debugging. Type filters decide when a waiter wakes; the returned actionable Delivery is still the oldest full batch.\n- Use `dispatch:<id>` for coordinator guidance to one supervised worker. Orca routes that stable address locally or through the connected-server relay; do not substitute a remote terminal handle.\n- Terminal handles remain appropriate for low-level pre-Dispatch messaging. Prefer `agentTerminalHandle` from the create response, fall back to `startupTerminal.handle` for older runtimes, then re-resolve with `orca terminal list --worktree ... --json` if missing or stale. Continue with the replacement handle only; never dual-send to old and new handles.\n- `orca orchestration check --peek --format --json` returns locally formatted unread mail without consuming it; it never writes to terminal input or remotely wakes another terminal. Use `orchestration dispatch --inject` to deliver a tracked task, or `terminal send` when an existing agent needs a free-form prompt.\n- While supervising workers manually, use `check --wait --types worker_done,escalation,question --timeout-ms <n>` instead of sleep/poll loops. Process the whole Delivery, reply to `question` messages with `orca orchestration reply --id <msg_id> --body <answer> --json`, then acknowledge and keep waiting.\n- Treat a `check --wait` timeout or `{count:0}` as a checkpoint, not a worker failure. Long coding tasks routinely run 15-60 minutes; keep using rolling waits unless you receive `worker_done`/`escalation`, the terminal exits or disappears, or the user explicitly asks you to stop.\n- Heartbeats and visible terminal activity mean the worker is alive, not done. Do not stop, close, kill, or restart a worker just because it has not produced a completion message yet.\n- Use `ask` when a worker needs a blocking answer from the coordinator; it defaults to the active Dispatch's Run. Timeout or disconnect leaves the question pending, so resume by its original message ID instead of asking again.\n- `check --wait` returns one bounded Delivery, not every future completion. Process every message, acknowledge it, then keep waiting until every expected Dispatch settles.\n- Group addresses include `@all`, `@idle`, `@claude`, `@codex`, `@opencode`, `@gemini`, `@droid`, `@grok`, `@cursor`, and `@worktree:<id>`.\n- Message types include `status`, `dispatch`, `worker_done`, `merge_ready`, `escalation`, `handoff`, `question`, `decision_gate` (legacy/gates), and `heartbeat`.\n- Use group addresses only for messages that are genuinely useful to many terminals, such as `status` broadcasts or intentional fan-out questions. Do not send dispatch lifecycle messages to groups.\n- `worker_done` belongs to the active Dispatch and defaults to its Run mailbox; never target a group.\n- A valid `worker_done` for the active `taskId` + `dispatchId` marks the task and dispatch completed automatically. Do not follow it with `task-update --status completed`; reserve manual updates for explicit recovery or overrides.\n- `heartbeat` is also Dispatch-scoped. Include both IDs and omit `--to` so Orca uses the owning Run; use `status` for broad progress updates.\n\n## Tasks And Dispatch\n\nA Run is the namespace/inbox, a Task is the work item, and a Dispatch assigns one Task attempt to a terminal. Create or bind a Run once before the common loop.\n\n```bash\norca orchestration run-create --objective <text> --json\norca orchestration task-create --spec <text> [--deps <json_array>] [--parent <task_id>] [--json]\norca orchestration task-list [--status <status>] [--ready] [--brief] [--json]\norca orchestration task-update --id <task_id> --status <status> [--result <json>] [--json]\norca orchestration dispatch --task <task_id> --to <handle> [--from <handle>] [--inject] [--json]\norca orchestration dispatch-show --task <task_id> [--json]\n```\n\nTask statuses: `pending`, `ready`, `dispatched`, `completed`, `failed`, `blocked`.\n\nDispatch rules:\n\n- `--inject` sends the task spec plus preamble into a recognized agent CLI so it can report `worker_done`.\n- If the target is a bare shell, omit `--inject`, dispatch for tracking if needed, then send the prompt manually with `orca terminal send --terminal <handle> --text <prompt> --enter --json`.\n- After 3 consecutive failures on one task, the dispatch context circuit-breaks and the task is marked failed.\n- Use `task-list --brief --json` for coordinator sweeps; it collapses whitespace and caps each echoed spec at 160 characters (`spec_truncated` marks shortened rows). Omit `--brief` when the full spec is required, or when an older CLI rejects it as an unknown flag.\n\n## Preferred Supervised Worker Loop\n\nUse `worker-start` for the normal supervised path. It composes the existing worktree, terminal, readiness, and dispatch primitives while returning exact created/reused effects. Agents still choose placement and concurrency; Orca does not schedule workers or infer conflicts.\n\nCreate the Run and every independent Task first, then start all independent workers before waiting:\n\n```bash\norca orchestration run-create --objective \"<objective>\" --json\norca orchestration task-create --spec \"<worker A task>\" --json\norca orchestration task-create --spec \"<worker B task>\" --json\norca orchestration worker-start --task <task_a> --worktree current --agent codex --json\norca orchestration worker-start --task <task_b> --worktree current --agent claude --json\n```\n\n`current` and exact existing worktrees create a fresh agent terminal and do not rerun setup. Reuse an existing agent only with `--terminal <handle>`.\n\nFor a new worktree, setup runs by default and agent-first creation reuses the returned startup agent terminal:\n\n```bash\norca orchestration worker-start --task <task_id> --worktree new-child --name <name> --agent codex --setup run --json\n# Independent/top-level:\norca orchestration worker-start --task <task_id> --worktree new-top-level --name <name> --agent codex --setup run --json\n```\n\nSetup normally starts alongside the agent. Only a repository explicitly configured with `wait-for-setup` delays agent launch until setup succeeds. Use `--setup skip` or `--setup inherit` only for a concrete reason.\n\nRead the returned receipt before continuing: `ready` plus setup `running` is normal for start-immediately, while wait-for-setup returns setup `succeeded` before accepting task input. A failed or unknown start exits nonzero; inspect its `stage`, `effects`, and `residualResources` instead of guessing or automatically retrying. A wait-for-setup timeout can honestly leave setup `running`, which is not proof of failure.\n\nTo run the worker on another connected Orca server, add `--on <saved-environment>`. The Run and Tasks remain authoritative on the current server; later commands route by Dispatch ID, so never repeat `--on`:\n\n```bash\n# Mac Run home -> Windows worker (the reverse is identical from a Windows Run home)\norca orchestration worker-start --task <task_id> --on windows --worktree new-top-level --repo <exact_remote_repo_selector> --name <name> --agent codex --setup run --json\norca orchestration worker-show --dispatch <dispatch_id> --json\norca orchestration worker-read --dispatch <dispatch_id> --limit 50 --json\norca orchestration send --to dispatch:<dispatch_id> --subject \"Follow-up\" --body \"<attempt-specific guidance>\" --json\n```\n\nRemote `current` and `new-child` are intentionally invalid because those words are ambiguous across servers. Use an exact discovered remote worktree selector or `new-top-level` with an explicit remote repo selector.\n\nThe follow-up is structured inbox mail, not prompt injection. The worker's next\n`orchestration check` receives it even when the Dispatch is on another connected Orca server.\n\n`worker-read` defaults to `--source auto`: Orca returns the exact hook-reported Codex, Claude, OpenClaude, or Grok transcript when it can prove the worker session, otherwise it returns bounded terminal output with `source: \"terminal\"` and a typed `fallbackReason`. Continue with the returned top-level `cursor`; it stays pinned to that exact source. If Orca reports `source_changed`, start a fresh read without the old cursor. Never supply or guess a provider session ID or transcript path.\n\nWait until every expected Dispatch settles, not for a fixed number of batches:\n\n```bash\norca orchestration check --wait --types worker_done,escalation,question --timeout-ms 900000 --json\n# Process every message in the returned Delivery, then atomically ack and continue:\norca orchestration check --ack <delivery_id> --wait --types worker_done,escalation,question --timeout-ms 900000 --json\n```\n\nWorkers report exactly once using the IDs and capability injected by Orca; they do not supply Run/server/terminal identity:\n\n```bash\norca orchestration send --type worker_done --subject \"<status>\" --body \"<what changed, findings, and what remains>\" --task-id <task_id> --dispatch-id <dispatch_id> --outcome succeeded --files-modified \"path/a,path/b\" --json\n# On failure, use --outcome failed; never encode failure only in prose.\n```\n\nA worker question defaults to its owning Run. Timeout leaves it pending:\n\n```bash\norca orchestration ask --question \"<question>\" --options \"yes,no\" --timeout-ms 600000 --json\norca orchestration ask --resume <message_id> --timeout-ms 600000 --json\n# Coordinator:\norca orchestration reply --id <message_id> --body \"<answer>\" --json\n```\n\nRecovery is conditional, never a fixed destructive sequence:\n\n- `worker-show --dispatch <id>` says `ready`: keep waiting or read bounded output.\n- It proves `failed` or `stopped`: start a replacement with `worker-start --task <task> --retry-of <id>` plus an explicit `--on`/`--worktree` and `--agent`/`--terminal` choice. Retry does not silently inherit placement.\n- It remains `outcome_unknown`: either `worker-stop --dispatch <id>` and inspect again, or explicitly `worker-abandon --dispatch <id>` while accepting that resources may still be live. Abandon performs no remote, process, or filesystem action.\n- `worker-stop` closes only the exact supervised agent terminal. It never deletes the worktree, setup terminal, configured tabs, or unrelated processes.\n\nLow-level `worktree create`, `terminal create`, and `dispatch --inject` remain valid recipes for custom argv or topology that `worker-start` does not express.\n\n## Gates And Legacy Inspection\n\n```bash\norca orchestration gate-create --task <task_id> --question <text> [--options <json_array>] [--json]\norca orchestration gate-resolve --id <gate_id> --resolution <text> [--json]\norca orchestration gate-list [--task <task_id>] [--status <status>] [--json]\n```\n\nUse `ask` for worker-to-coordinator questions; it creates a `question` message that the coordinator answers with `reply`. Use `gate-create` only for coordinator-managed task DAG decisions, not for answering a worker's `ask`.\n\n`coordinator-start`, `coordinator-stop`, `run`, and `run-stop` are retired scheduler commands. They perform no effects and return the current-skill recovery action. They are not aliases for lightweight Run creation or binding.\n\nRecovery only: `orca orchestration reset --tasks|--messages|--all --json` clears the selected local orchestration database state. Do not run it during active coordination unless explicitly abandoning that state.\n\n## Full Handoffs\n\nFor full ownership transfer, use non-lifecycle terminal/worktree commands and then stop monitoring unless the user asks for supervision.\n\nTreat these as full handoff requests by default: \"hand off\", \"handoff\", \"handover\", \"give this to another agent\", \"give this to another worktree\", \"send this to another agent\", \"another agent\", \"another worktree\", or \"launch another agent to own this.\" Custom model or reasoning effort words such as `gpt-5.5`, `high`, or `xhigh` do not make the handoff supervised.\n\nSupervised orchestration remains available only when the user explicitly asks for supervision or coordination: \"supervise\", \"monitor\", \"wait for worker_done\", \"wait for results\", \"track completion\", \"DAG\", \"decision gate\", \"ask/reply\", or \"coordinate workers.\"\n\nDo not run `orca orchestration task-create`, `orca orchestration dispatch --inject`, or `orca orchestration check --wait` for full handoffs. `task-create` is also forbidden because it records coordinator-owned tracking state; if a task row is needed, the user asked for supervised orchestration. Do not create a `taskId`/`dispatchId`, inject a lifecycle preamble, wait for completion, or read the worker terminal after prompt delivery except to avoid losing the initial prompt.\n\nNew top-level worktree handoff:\n\n```bash\norca worktree create --name <task-name> --no-parent --agent codex --prompt \"<task brief>\" --setup run --json\n```\n\nBefore creating a new worktree from an active feature branch, decide and state whether the desired Orca lineage is child or top-level. Use child worktree lineage only when the new work is conceptually stacked under or dependent on the active worktree. For independent repo-wide fixes, standalone feature work, or unrelated follow-up tasks, create a top-level worktree with `--no-parent`.\n\nExisting terminal handoff:\n\n```bash\norca terminal send --terminal <handle> --text \"<task brief>\" --enter --json\n```\n\nCustom Codex model/effort handoff:\n\n`orca worktree create --agent codex --prompt ...` launches the known Codex agent but does not accept Codex-specific `--model` or `-c model_reasoning_effort=...` arguments. When the user asks for a specific Codex model or effort, create the independent worktree first, launch Codex with the requested command in that worktree, wait only for TUI readiness if prompt delivery would otherwise race startup, send the prompt, and stop.\n\nThe two-step custom-argv path cannot enforce a repository's explicit `wait-for-setup` startup policy because the later `terminal create` is not the startup owned by `worktree create`. Use it only when the repository starts agents immediately. If the repository requires `wait-for-setup`, use an agent-first configured launcher that can preserve sequencing, or stop and ask rather than silently bypassing the policy.\n\nNote: when no repo default-terminal configuration supplies a primary terminal, bare create opens a fallback shell before `terminal create` adds the agent. Configured default tabs are materialized instead and may run real commands. Prefer `--agent` whenever custom argv is not required. With the two-step path, target only the agent handle; close a prior terminal only after `terminal list` or `terminal show` confirms it is an unused shell.\n\nUse the exact full `<repo-id>::<path>` worktree id returned by `orca worktree create --json`; a bare repo id cannot target the new worktree.\n\n```bash\norca worktree create --name <task-name> --no-parent --setup run --json\norca terminal create --worktree id:<newFullWorktreeId> --title <task-name> --command 'codex --model gpt-5.5 -c model_reasoning_effort=\"xhigh\"' --json\norca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json\norca terminal send --terminal <handle> --text \"<task brief>\" --enter --json\n```\n\nWait only for `tui-idle` when needed to avoid losing the prompt. Do not monitor task completion.\n\n`--no-parent` only controls Orca lineage; it does not choose the Git base. If the work should start from the repo default base, omit `--base-branch` so Orca uses that default, or explicitly pass the repo default base (`origin/main`, `origin/master`, or the `orca repo show --repo <selector> --json` value); never base it on the current feature branch unless the user explicitly asks for stacked work or \"branch from current\". Put current-branch context in the prompt instead.\n\n## Worker Terminals\n\nChoose the worker location before creating a terminal. `Fresh worker` means a fresh agent session, not a new git worktree. For parallel work, create one fresh agent terminal per worker in the same required worktree, falling back to the active worktree when none is named. If the task says current worktree only, depends on uncommitted files/artifacts, or must validate/PR the current branch, keep every worker in the active worktree:\n\n```bash\norca terminal create --worktree active --title <task-name> --command \"codex\" --json\norca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json\norca orchestration dispatch --task <task_id> --to <handle> --inject --json\n```\n\nReuse an idle agent in the required worktree only if the prompt allows reuse; otherwise create a fresh terminal there. Create a new worktree only when the user explicitly requests one or a concrete checkout or filesystem conflict makes sharing unsafe or impossible; if the user did not request it, state that conflict before running `worktree create`. Independent tasks, parallel execution, convenience, or a preference for separate checkouts are not isolation requirements.\n\nWhen a new worktree is allowed, use child lineage for isolated work that is stacked under or dependent on the active worktree, and use `--no-parent` when it is not stacked. Decide the Git base separately: `--no-parent` makes the worktree top-level in Orca, while omitted `--base-branch` uses the repo default base.\n\nFor every new worktree, pass `--setup run` so any configured repository setup hook runs. This does not mean waiting for setup before agent launch: preserve the repository's startup policy, whose default starts setup and the agent side by side. Use `--setup skip` or `--setup inherit` only when there is a concrete task-specific reason, and state that reason before creating the worktree. This rule does not rerun setup for current or existing worktrees.\n\n```bash\norca worktree create --name <task-name> --agent codex --setup run --json\n# or: --agent claude | omp | pi | grok | ...\n# Read <handle> from agentTerminalHandle, falling back to startupTerminal.handle.\norca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json\norca orchestration dispatch --task <task_id> --to <handle> --inject --json\n```\n\nFor new-worktree workers, read the id and `agentTerminalHandle` from `worktree create`, falling back to `startupTerminal.handle` for older runtimes. Use that as the sole worker handle when present; otherwise use `terminal list` to resolve the agent handle. Omit `--repo` only inside an Orca-managed worktree; otherwise pass `--repo <selector>`.\n\n**For an allowed new worktree, use agent-first:** `--agent` reveals the new worktree and launches the selected agent **in its first terminal**, without adding a separate fallback shell for that worker. Pass `--setup run`; repo setup and default-terminal settings may add intentional tabs or splits. Do **not** run bare `worktree create` and then `terminal create --command <agent>` for the same worker when agent-first create is available: without configured default tabs, that two-step path leaves a fallback shell + agent pair. Only use it when custom agent argv is required (for example Codex model/effort flags) or when an older CLI rejects `--agent`; if you must, message only the agent handle. Configured default tabs are intentional surfaces, so close a prior terminal only after `terminal list` or `terminal show` confirms it is an unused shell. Do not run `worktree create` when the task must stay in the current worktree.\n\nUse `orca worktree create --prompt ...` or `orca terminal send ...` for full handoffs or untracked/lightweight prompts. Those paths do not attach `taskId`/`dispatchId`; the worker should not send lifecycle messages unless the prompt supplies a live orchestration preamble.\n\nSidebar lineage and orchestration lifecycle are related but not identical. A same-worktree worker may appear as a peer under that worktree in the sidebar while remaining a child dispatch in orchestration state; only an actual child worktree creates visible parent/child worktree lineage.\n\nOther terminal commands coordinators often need:\n\n```bash\norca terminal list [--worktree <selector>] [--json]\norca terminal create [--worktree <selector>] [--title <text>] [--command <cmd>] [--json]\norca terminal split --terminal <handle> [--direction horizontal|vertical] [--command <cmd>] [--json]\norca terminal wait --terminal <handle> --for tui-idle --timeout-ms <n> --json\norca terminal read --terminal <handle> --json\norca terminal send --terminal <handle> --text <text> --enter --json\n```\n\nIf an older CLI rejects `worktree create --agent`, create the worktree normally, then run `orca terminal create --worktree <selector> --command \"codex\" --json` or `--command \"claude\"`.\n\nWait for `tui-idle` before dispatching. Always pass `--timeout-ms`; real coding tasks can take 15-60 minutes. During supervision, use rolling `check --wait` windows. If a window returns no matching message, inspect `task-list`, `terminal read`, or `terminal wait --for tui-idle` as a liveness checkpoint; if the terminal is still working or producing activity, keep waiting instead of retrying the task.\n\n## Agent Guidance\n\n- Workers with a valid live preamble must send `worker_done` exactly once from their own terminal with an explicit `--outcome succeeded` or `--outcome failed`:\n  `orca orchestration send --type worker_done --subject \"<short status>\" --body \"<3-sentence summary: what you did, what you found, what's left>\" --task-id <task_id> --dispatch-id <dispatch_id> --outcome succeeded --files-modified \"path/a\" --report-path \"<optional>\" --json`\n- A failed outcome is still a terminal report, but Orca records both the Dispatch and Task as failed. Never encode failure only in the subject/body.\n- After sending `worker_done`, end your turn and idle at the agent prompt. Do not poll or keep calling `orca orchestration check`; the coordinator re-engages you with a fresh preamble + TASK block delivered as new terminal input.\n- For long tasks, send heartbeat/status only when the preamble asks for it, including both IDs:\n  `orca orchestration send --type heartbeat --subject \"alive\" --payload '{\"taskId\":\"<task_id>\",\"dispatchId\":\"<dispatch_id>\",\"phase\":\"implementing\"}' --json`\n- If blocked before completion, use `ask`; use `escalation` only when ownership is valid and the coordinator must intervene.\n- Treat preambles inherited through terminal history or full handoffs as stale unless the current prompt explicitly keeps that coordinator in the loop.\n- Coordinators should use `task-list --ready` as external memory, dispatch parallel waves, and avoid dependency chains deeper than 3-4 steps.\n\n## Example\n\n```bash\norca terminal create --worktree active --title login-css-worker --command \"claude\" --json\norca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json\norca orchestration task-create --spec \"Fix the login button CSS\" --json\norca orchestration dispatch --task <task_id> --to <handle> --inject --json\norca orchestration check --wait --types worker_done,escalation,question --timeout-ms 900000 --json\n```\n\n## Next Action\n\nCoordinator: confirm `orca status --json`, create or bind a Run, inspect `task-list`/`dispatch-show` if inheriting state, then use the explicit supervised loop (`task-create` -> `worker-start` -> `check --wait`). Use low-level terminal creation plus `dispatch --inject` only when the composed start does not express the needed topology.\n\nWorker: if the current prompt contains a live dispatch preamble, do the task, use `ask` for blocking questions, and send `worker_done` once with the required payload. If the preamble is stale or absent, do not send lifecycle messages; inspect state or treat the prompt as an ordinary handoff.\n"
+const ORCHESTRATION_MARKDOWN = "---\nname: orchestration\ndescription: >-\n  Use Orca orchestration for structured multi-agent coordination: threaded\n  messages, blocking ask/reply flows, task dispatch, worker_done/escalation\n  waits, task DAGs, decision gates, coordinator loops, or decomposing work\n  across agents. Use `orca-cli` instead for full ownership handoffs, including\n  requests phrased as \"hand off\", \"handoff\", \"handover\", \"give this to another\n  agent\", or \"another worktree\" when the user did not explicitly ask to\n  supervise, monitor, wait for results, or coordinate a DAG. Use `orca-cli` for\n  ordinary terminal control, lightweight terminal prompts, shell commands, Orca\n  worktree management, reading or waiting on terminals, and automation of the\n  browser embedded inside Orca. Use Computer Use for browser windows, webviews,\n  Orca app UI, or desktop UI outside Orca's embedded browser.\n---\n\n# Orca Inter-Agent Orchestration\n\nOrchestration is Orca's structured coordination layer for agent messages, task ownership, dispatch state, and worker completion tracking.\n\nUse this skill when coordination state matters. For lightweight terminal prompts or basic worktree/terminal/built-in-browser control, use `orca-cli`.\n\n## Tool Boundary\n\nIf a task says to use Orca orchestration, the coordinator must create or bind a Run, create the Task with `orca orchestration task-create`, then attach the worker with either the preferred `orca orchestration worker-start` composition or the low-level `orca orchestration dispatch --inject` path.\n\nDo not substitute non-Orca subagent tools, generic agent-spawn APIs, or chat-only parallel worker features. Those may create useful workers, but they do not create Orca task/dispatch provenance, injected lifecycle preambles, `worker_done` authority, or decision gates.\n\nBefore claiming a worker was orchestrated, verify the task/dispatch exists:\n\n```bash\norca orchestration task-list --json\norca orchestration dispatch-show --task <task_id> --json\n```\n\nIf the work was accidentally run outside Orca orchestration, say so plainly. To repair provenance, rerun or revalidate the needed work through a fresh Orca terminal plus injected dispatch; do not retroactively describe the external worker as orchestrated.\n\n## When To Use\n\n- Send/reply/ask between agent terminals with persistent messages.\n- Dispatch structured tasks to workers and wait for `worker_done` or `escalation`.\n- Track task DAGs with dependencies.\n- Run coordinator loops or decision gates.\n\nDo not use orchestration merely because the user says \"hand off\", \"handoff\", \"handover\", \"give this to another agent\", or asks for another worktree/agent/model/effort. Those are full ownership transfers unless the user explicitly asks to supervise, monitor, wait for worker completion/results, coordinate a DAG, use decision gates, or keep a blocking ask/reply loop.\n\n## Preconditions\n\n- `orca status --json` should show a running runtime.\n- `orca` must be on PATH (`orca-ide` on Linux).\n- The orchestration experimental feature must be enabled in Settings > Experimental.\n- `orca orchestration` commands are RPC calls to the running Orca runtime.\n\n## Contract Migration\n\nOrca adopts a live pre-update orchestration assignment into an ordinary Run. Adoption preserves the existing agent process, PTY/session, terminal handle, tab/leaf/pane, worktree or folder workspace, Task, and Dispatch; it never restarts or replaces the worker. The retired scheduler is not revived, and a newly created attempt uses the current grammar.\n\nTreat the authority label on injected or formatted messages as definitive:\n\n- `[LEGACY COMPATIBILITY]` is live and attested. Run only the exact supported command printed with the message, using the same CLI executable and arguments that the original prompt supplied.\n- `[LEGACY RECOVERY REPLAY — MAY HAVE BEEN SEEN]` is one bounded, at-least-once cutover replay. Process it idempotently and acknowledge it only through the exact displayed guidance.\n- `[LEGACY READ-ONLY]` is inspection-only. It has no reply, acknowledgment, or lifecycle action.\n- An unlabeled current message uses the current guide and current grammar.\n\nAn explicitly selected current Run, attested current Run binding, current Dispatch, or federated attachment takes precedence over legacy fallback. A retained adoption record alone never turns a current command into a legacy call.\n\nDatabase provenance, an old-looking terminal, or a legacy Run ID does not prove mutation authority. If the runtime cannot prove liveness, principal ownership, capability, or the exact legacy contract, it degrades to read-only inspection and must not fall back to local execution. Exact recovery may restore the already-live PTY once in its original inactive background tab. It must not spawn, write, signal, stop, switch, focus, split, or inject a terminal. Loss of lifecycle authority does not invalidate the existing assignment, process, or filesystem work.\n\nCompatibility retries have narrow guarantees. A pending ask, a reply, a final Dispatch settlement, and a consuming check have durable recovery identities. A-era heartbeat and escalation calls remain at-least-once across a manual A-to-B retry because identical later signals may be intentional. If an A-era ask may already have been answered, run the exact non-consuming recovery check printed by the runtime first; after its answer is printed and acknowledged, a new invocation with the same question creates a new question. Never guess among multiple identical question threads.\n\nWhen a compatibility or recovery command returns structured next-step arguments, run those exact arguments with the same CLI executable. The arguments intentionally omit the executable name so the guidance works with `orca`, `orca-ide`, `orca-dev`, or another configured Orca CLI command. Do not translate the command from memory, broaden its recipient, or retry it as a current mutation unless the returned guidance explicitly says to.\n\nOn packaged Windows, a legacy ask uses a two-step commit/resume protocol. The initial command durably commits the question, prints its exact `ask --resume <message_id>` command, and exits with launcher status `75`; it does not wait for the answer. Run that exact resume command after the launcher or update boundary. Resume is idempotent and read-oriented: it waits for the already-committed question and does not create another one. For a WSL process that received compatibility proof at launch, use the printed executable `orca-ide` WSL resume command so the same distro and packaged launcher authority are preserved; do not substitute a PATH-resolved local CLI. Older WSL processes that never received the hidden launch token remain lifecycle read-only after the update, even while their terminal and filesystem work continue.\n\nLegacy inspection remains available without consuming mail:\n\n```bash\norca orchestration run-list --json\n# run_legacy_local is an empty audit tombstone after adoption.\norca orchestration run-show --id run_legacy_local --json\n# In run-list, find the ordinary Run whose objective is:\n# \"Recovered orchestration work from a contract update\"\norca orchestration run-show --id <adopted_run_id> --json\norca orchestration task-list --run <adopted_run_id> --json\norca orchestration inbox --full --json\norca orchestration check --terminal <legacy_handle> --peek --format --json\norca terminal read --terminal <legacy_handle> --json\norca terminal wait --terminal <legacy_handle> --for tui-idle --timeout-ms 60000 --json\n```\n\nIf the original coordinator is unavailable or cannot prove its retained authority, a current coordinator may explicitly take over the adopted Run from its own live agent terminal:\n\n```bash\norca orchestration run-use --id <adopted_run_id> --takeover-legacy --json\norca orchestration check --run <adopted_run_id> --json\n```\n\nTakeover fences only the old coordinator, binds the current one, and moves pending worker mail into current Run Delivery. It is bound to the authenticated invoking terminal; `--from` cannot name another coordinator. Live legacy workers keep their original Tasks, Dispatches, processes, filesystems, and old prompt commands; their later questions, escalations, and completion reports route to the current coordinator. Do not use takeover while the original coordinator is still actively coordinating, because its later lifecycle mutations are rejected.\n\nDo not launch a replacement editor merely because the desktop app or runtime was updated. If adoption cannot prove continuing authority, keep the original worker as the only editor until it reaches a stable handoff point, then use a new current Dispatch in a conflict-free placement for any remaining work.\n\n## Ownership\n\nNew orchestration messages and tasks belong to one explicitly bound Run. A Run is only a durable namespace and coordinator inbox; it never schedules or places workers. Lifecycle authority comes from the active Dispatch, and terminal handles remain routing metadata rather than durable identity. Send `worker_done` and `heartbeat` from the worker's own terminal; Orca routes them to that Dispatch's Run.\n\nClassify inherited context before sending lifecycle messages:\n\n- Coordinated subtask: a live coordinator owns the DAG and waits on this dispatch. Follow the preamble exactly, including `worker_done`, heartbeat/status, `ask`, and `escalation`.\n- Full handoff means ownership transfer, not supervised dispatch. The original actor is not monitoring a DAG, so do not create lifecycle obligations unless the user explicitly asks you to supervise.\n- Classify requests containing \"hand off\", \"handoff\", \"handover\", \"give this to another agent\", \"give this to another worktree\", \"another agent\", or \"another worktree\" as full handoffs by default, even when the user names a custom model or reasoning effort.\n- Use supervised orchestration only when the user explicitly asks you to \"supervise\", \"monitor\", \"wait\", \"track completion\", \"wait for worker_done\", return results, coordinate a DAG, use a decision gate, or manage ask/reply flow.\n- Do not use `orca orchestration dispatch --inject` for full handoffs. It injects a coordinator preamble that tells the worker to send `worker_done`, heartbeat, and `ask` messages, then end its turn under the original terminal's dispatch lifecycle.\n- Do not run `orca orchestration task-create`, `orca orchestration dispatch --inject`, or `orca orchestration check --wait` for full handoffs. Do not peek at terminal output after prompt delivery to monitor progress.\n- A review-only `worker_done` reports findings; it does not authorize coordinator file edits. After a review-only completion, synthesize findings, ask a decision gate if ownership is unclear, and dispatch or hand off fixes unless the user explicitly asked the coordinator to own fixes.\n- If the user's plan names a next owner agent (for example, \"then use opencode to create a PR\"), post-review corrections and PR prep belong to that named owner. The coordinator routes, synthesizes, asks decision gates when needed, and supervises; the named owner edits files and creates the PR.\n\nIf unclear, inspect orchestration state before sending lifecycle messages:\n\n```bash\norca orchestration task-list --json\norca terminal list --json\n# If inherited context includes a task id:\norca orchestration dispatch-show --task <task_id> --json\n```\n\n## Messaging\n\n```bash\norca orchestration send --subject <text> [--to <run:id|dispatch:id|legacy_handle>] [--from <handle>] [--body <text>] [--type <type>] [--priority <level>] [--thread-id <id>] [--payload <json>] [--json]\norca orchestration check [--terminal <handle>] [--ack <delivery_id>] [--peek|--all] [--types <type,...>] [--format] [--wait] [--timeout-ms <n>] [--json]\norca orchestration reply --id <msg_id> --body <text> [--from <handle>] [--json]\norca orchestration ask (--question <text>|--resume <msg_id>) [--options <csv>] [--timeout-ms <n>] [--from <handle>] [--json]\norca orchestration inbox [--limit <n>] [--json]\n```\n\nRules:\n\n- Omit `--from` unless impersonating another terminal; Orca auto-resolves it from the current terminal.\n- A coordinator `check` returns the bound Run's oldest FIFO Delivery (up to 50 messages) and replays that exact batch until `--ack <delivery_id>`. Process every message before acknowledging; `check --ack <id> --wait` acknowledges, checks, and waits in one operation.\n- Use `--peek` and `--all` only for read-only history/debugging. Type filters decide when a waiter wakes; the returned actionable Delivery is still the oldest full batch.\n- Use `dispatch:<id>` for coordinator guidance to one supervised worker. Orca routes that stable address locally or through the connected-server relay; do not substitute a remote terminal handle.\n- Terminal handles remain appropriate for low-level pre-Dispatch messaging. Prefer `agentTerminalHandle` from the create response, fall back to `startupTerminal.handle` for older runtimes, then re-resolve with `orca terminal list --worktree ... --json` if missing or stale. Continue with the replacement handle only; never dual-send to old and new handles.\n- `orca orchestration check --peek --format --json` returns locally formatted unread mail without consuming it; it never writes to terminal input or remotely wakes another terminal. Use `orchestration dispatch --inject` to deliver a tracked task, or `terminal send` when an existing agent needs a free-form prompt.\n- While supervising workers manually, use `check --wait --types worker_done,escalation,question --timeout-ms <n>` instead of sleep/poll loops. Process the whole Delivery, reply to `question` messages with `orca orchestration reply --id <msg_id> --body <answer> --json`, then acknowledge and keep waiting.\n- Treat a `check --wait` timeout or `{count:0}` as a checkpoint, not a worker failure. Long coding tasks routinely run 15-60 minutes; keep using rolling waits unless you receive `worker_done`/`escalation`, the terminal exits or disappears, or the user explicitly asks you to stop.\n- Heartbeats and visible terminal activity mean the worker is alive, not done. Do not stop, close, kill, or restart a worker just because it has not produced a completion message yet.\n- Use `ask` when a worker needs a blocking answer from the coordinator; it defaults to the active Dispatch's Run. Timeout or disconnect leaves the question pending, so resume by its original message ID instead of asking again.\n- `check --wait` returns one bounded Delivery, not every future completion. Process every message, acknowledge it, then keep waiting until every expected Dispatch settles.\n- Group addresses include `@all`, `@idle`, `@claude`, `@codex`, `@opencode`, `@gemini`, `@droid`, `@grok`, `@cursor`, and `@worktree:<id>`.\n- Message types include `status`, `dispatch`, `worker_done`, `merge_ready`, `escalation`, `handoff`, `question`, `decision_gate` (legacy/gates), and `heartbeat`.\n- Use group addresses only for messages that are genuinely useful to many terminals, such as `status` broadcasts or intentional fan-out questions. Do not send dispatch lifecycle messages to groups.\n- `worker_done` belongs to the active Dispatch and defaults to its Run mailbox; never target a group.\n- A valid `worker_done` for the active `taskId` + `dispatchId` marks the task and dispatch completed automatically. Do not follow it with `task-update --status completed`; reserve manual updates for explicit recovery or overrides.\n- `heartbeat` is also Dispatch-scoped. Include both IDs and omit `--to` so Orca uses the owning Run; use `status` for broad progress updates.\n\n## Tasks And Dispatch\n\nA Run is the namespace/inbox, a Task is the work item, and a Dispatch assigns one Task attempt to a terminal. Create or bind a Run once before the common loop.\n\n```bash\norca orchestration run-create --objective <text> --json\norca orchestration task-create --spec <text> [--deps <json_array>] [--parent <task_id>] [--json]\norca orchestration task-list [--status <status>] [--ready] [--brief] [--json]\norca orchestration task-update --id <task_id> --status <status> [--result <json>] [--json]\norca orchestration dispatch --task <task_id> --to <handle> [--from <handle>] [--inject] [--json]\norca orchestration dispatch-show --task <task_id> [--json]\n```\n\nTask statuses: `pending`, `ready`, `dispatched`, `completed`, `failed`, `blocked`.\n\nDispatch rules:\n\n- `--inject` sends the task spec plus preamble into a recognized agent CLI so it can report `worker_done`.\n- If the target is a bare shell, omit `--inject`, dispatch for tracking if needed, then send the prompt manually with `orca terminal send --terminal <handle> --text <prompt> --enter --json`.\n- After 3 consecutive failures on one task, the dispatch context circuit-breaks and the task is marked failed.\n- Use `task-list --brief --json` for coordinator sweeps; it collapses whitespace and caps each echoed spec at 160 characters (`spec_truncated` marks shortened rows). Omit `--brief` when the full spec is required, or when an older CLI rejects it as an unknown flag.\n\n## Preferred Supervised Worker Loop\n\nUse `worker-start` for the normal supervised path. It composes the existing worktree, terminal, readiness, and dispatch primitives while returning exact created/reused effects. Agents still choose placement and concurrency; Orca does not schedule workers or infer conflicts.\n\nCreate the Run and every independent Task first, then start all independent workers before waiting:\n\n```bash\norca orchestration run-create --objective \"<objective>\" --json\norca orchestration task-create --spec \"<worker A task>\" --json\norca orchestration task-create --spec \"<worker B task>\" --json\norca orchestration worker-start --task <task_a> --worktree current --agent codex --json\norca orchestration worker-start --task <task_b> --worktree current --agent claude --json\n```\n\n`current` and exact existing worktrees create a fresh agent terminal and do not rerun setup. Reuse an existing agent only with `--terminal <handle>`.\n\nFor a new worktree, setup runs by default and agent-first creation reuses the returned startup agent terminal:\n\n```bash\norca orchestration worker-start --task <task_id> --worktree new-child --name <name> --agent codex --setup run --json\n# Independent/top-level:\norca orchestration worker-start --task <task_id> --worktree new-top-level --name <name> --agent codex --setup run --json\n```\n\nSetup normally starts alongside the agent. Only a repository explicitly configured with `wait-for-setup` delays agent launch until setup succeeds. Use `--setup skip` or `--setup inherit` only for a concrete reason.\n\nRead the returned receipt before continuing: `ready` plus setup `running` is normal for start-immediately, while wait-for-setup returns setup `succeeded` before accepting task input. A failed or unknown start exits nonzero; inspect its `stage`, `effects`, and `residualResources` instead of guessing or automatically retrying. A wait-for-setup timeout can honestly leave setup `running`, which is not proof of failure.\n\nTo run the worker on another connected Orca server, add `--on <saved-environment>`. The Run and Tasks remain authoritative on the current server; later commands route by Dispatch ID, so never repeat `--on`:\n\n```bash\n# Mac Run home -> Windows worker (the reverse is identical from a Windows Run home)\norca orchestration worker-start --task <task_id> --on windows --worktree new-top-level --repo <exact_remote_repo_selector> --name <name> --agent codex --setup run --json\norca orchestration worker-show --dispatch <dispatch_id> --json\norca orchestration worker-read --dispatch <dispatch_id> --limit 50 --json\norca orchestration send --to dispatch:<dispatch_id> --subject \"Follow-up\" --body \"<attempt-specific guidance>\" --json\n```\n\nRemote `current` and `new-child` are intentionally invalid because those words are ambiguous across servers. Use an exact discovered remote worktree selector or `new-top-level` with an explicit remote repo selector.\n\nThe follow-up is structured inbox mail, not prompt injection. The worker's next\n`orchestration check` receives it even when the Dispatch is on another connected Orca server.\n\n`worker-read` defaults to `--source auto`: Orca returns the exact hook-reported Codex, Claude, OpenClaude, or Grok transcript when it can prove the worker session, otherwise it returns bounded terminal output with `source: \"terminal\"` and a typed `fallbackReason`. Continue with the returned top-level `cursor`; it stays pinned to that exact source. If Orca reports `source_changed`, start a fresh read without the old cursor. Never supply or guess a provider session ID or transcript path.\n\nWait until every expected Dispatch settles, not for a fixed number of batches:\n\n```bash\norca orchestration check --wait --types worker_done,escalation,question --timeout-ms 900000 --json\n# Process every message in the returned Delivery, then atomically ack and continue:\norca orchestration check --ack <delivery_id> --wait --types worker_done,escalation,question --timeout-ms 900000 --json\n```\n\nWorkers report exactly once using the IDs and capability injected by Orca; they do not supply Run/server/terminal identity:\n\n```bash\norca orchestration send --type worker_done --subject \"<status>\" --body \"<what changed, findings, and what remains>\" --task-id <task_id> --dispatch-id <dispatch_id> --outcome succeeded --files-modified \"path/a,path/b\" --json\n# On failure, use --outcome failed; never encode failure only in prose.\n```\n\nA worker question defaults to its owning Run. Timeout leaves it pending:\n\n```bash\norca orchestration ask --question \"<question>\" --options \"yes,no\" --timeout-ms 600000 --json\norca orchestration ask --resume <message_id> --timeout-ms 600000 --json\n# Coordinator:\norca orchestration reply --id <message_id> --body \"<answer>\" --json\n```\n\nRecovery is conditional, never a fixed destructive sequence:\n\n- `worker-show --dispatch <id>` says `ready`: keep waiting or read bounded output.\n- It proves `failed` or `stopped`: start a replacement with `worker-start --task <task> --retry-of <id>` plus an explicit `--on`/`--worktree` and `--agent`/`--terminal` choice. Retry does not silently inherit placement.\n- It remains `outcome_unknown`: either `worker-stop --dispatch <id>` and inspect again, or explicitly `worker-abandon --dispatch <id>` while accepting that resources may still be live. Abandon performs no remote, process, or filesystem action.\n- `worker-stop` closes only the exact supervised agent terminal. It never deletes the worktree, setup terminal, configured tabs, or unrelated processes.\n\nLow-level `worktree create`, `terminal create`, and `dispatch --inject` remain valid recipes for custom argv or topology that `worker-start` does not express.\n\n## Gates And Legacy Inspection\n\n```bash\norca orchestration gate-create --task <task_id> --question <text> [--options <json_array>] [--json]\norca orchestration gate-resolve --id <gate_id> --resolution <text> [--json]\norca orchestration gate-list [--task <task_id>] [--status <status>] [--json]\n```\n\nUse `ask` for worker-to-coordinator questions; it creates a `question` message that the coordinator answers with `reply`. Use `gate-create` only for coordinator-managed task DAG decisions, not for answering a worker's `ask`.\n\n`coordinator-start`, `coordinator-stop`, `run`, and `run-stop` are retired scheduler commands. They perform no effects and return the current-skill recovery action. They are not aliases for lightweight Run creation or binding.\n\nRecovery only: `orca orchestration reset --tasks|--messages|--all --json` clears the selected local orchestration database state. Do not run it during active coordination unless explicitly abandoning that state.\n\n## Full Handoffs\n\nFor full ownership transfer, use non-lifecycle terminal/worktree commands and then stop monitoring unless the user asks for supervision.\n\nTreat these as full handoff requests by default: \"hand off\", \"handoff\", \"handover\", \"give this to another agent\", \"give this to another worktree\", \"send this to another agent\", \"another agent\", \"another worktree\", or \"launch another agent to own this.\" Custom model or reasoning effort words such as `gpt-5.5`, `high`, or `xhigh` do not make the handoff supervised.\n\nSupervised orchestration remains available only when the user explicitly asks for supervision or coordination: \"supervise\", \"monitor\", \"wait for worker_done\", \"wait for results\", \"track completion\", \"DAG\", \"decision gate\", \"ask/reply\", or \"coordinate workers.\"\n\nDo not run `orca orchestration task-create`, `orca orchestration dispatch --inject`, or `orca orchestration check --wait` for full handoffs. `task-create` is also forbidden because it records coordinator-owned tracking state; if a task row is needed, the user asked for supervised orchestration. Do not create a `taskId`/`dispatchId`, inject a lifecycle preamble, wait for completion, or read the worker terminal after prompt delivery except to avoid losing the initial prompt.\n\nNew top-level worktree handoff:\n\n```bash\norca worktree create --name <task-name> --no-parent --agent codex --prompt \"<task brief>\" --setup run --json\n```\n\nBefore creating a new worktree from an active feature branch, decide and state whether the desired Orca lineage is child or top-level. Use child worktree lineage only when the new work is conceptually stacked under or dependent on the active worktree. For independent repo-wide fixes, standalone feature work, or unrelated follow-up tasks, create a top-level worktree with `--no-parent`.\n\nExisting terminal handoff:\n\n```bash\norca terminal send --terminal <handle> --text \"<task brief>\" --enter --json\n```\n\nCustom Codex model/effort handoff:\n\n`orca worktree create --agent codex --prompt ...` launches the known Codex agent but does not accept Codex-specific `--model` or `-c model_reasoning_effort=...` arguments. When the user asks for a specific Codex model or effort, create the independent worktree first, launch Codex with the requested command in that worktree, wait only for TUI readiness if prompt delivery would otherwise race startup, send the prompt, and stop.\n\nThe two-step custom-argv path cannot enforce a repository's explicit `wait-for-setup` startup policy because the later `terminal create` is not the startup owned by `worktree create`. Use it only when the repository starts agents immediately. If the repository requires `wait-for-setup`, use an agent-first configured launcher that can preserve sequencing, or stop and ask rather than silently bypassing the policy.\n\nNote: when no repo default-terminal configuration supplies a primary terminal, bare create opens a fallback shell before `terminal create` adds the agent. Configured default tabs are materialized instead and may run real commands. Prefer `--agent` whenever custom argv is not required. With the two-step path, target only the agent handle; close a prior terminal only after `terminal list` or `terminal show` confirms it is an unused shell.\n\nUse the exact full `<repo-id>::<path>` worktree id returned by `orca worktree create --json`; a bare repo id cannot target the new worktree.\n\n```bash\norca worktree create --name <task-name> --no-parent --setup run --json\norca terminal create --worktree id:<newFullWorktreeId> --title <task-name> --command 'codex --model gpt-5.5 -c model_reasoning_effort=\"xhigh\"' --json\norca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json\norca terminal send --terminal <handle> --text \"<task brief>\" --enter --json\n```\n\nWait only for `tui-idle` when needed to avoid losing the prompt. Do not monitor task completion.\n\n`--no-parent` only controls Orca lineage; it does not choose the Git base. If the work should start from the repo default base, omit `--base-branch` so Orca uses that default, or explicitly pass the repo default base (`origin/main`, `origin/master`, or the `orca repo show --repo <selector> --json` value); never base it on the current feature branch unless the user explicitly asks for stacked work or \"branch from current\". Put current-branch context in the prompt instead.\n\n## Worker Terminals\n\nChoose the worker location before creating a terminal. `Fresh worker` means a fresh agent session, not a new git worktree. For parallel work, create one fresh agent terminal per worker in the same required worktree, falling back to the active worktree when none is named. If the task says current worktree only, depends on uncommitted files/artifacts, or must validate/PR the current branch, keep every worker in the active worktree:\n\n```bash\norca terminal create --worktree active --title <task-name> --command \"codex\" --json\norca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json\norca orchestration dispatch --task <task_id> --to <handle> --inject --json\n```\n\nReuse an idle agent in the required worktree only if the prompt allows reuse; otherwise create a fresh terminal there. Create a new worktree only when the user explicitly requests one or a concrete checkout or filesystem conflict makes sharing unsafe or impossible; if the user did not request it, state that conflict before running `worktree create`. Independent tasks, parallel execution, convenience, or a preference for separate checkouts are not isolation requirements.\n\nWhen a new worktree is allowed, use child lineage for isolated work that is stacked under or dependent on the active worktree, and use `--no-parent` when it is not stacked. Decide the Git base separately: `--no-parent` makes the worktree top-level in Orca, while omitted `--base-branch` uses the repo default base.\n\nFor every new worktree, pass `--setup run` so any configured repository setup hook runs. This does not mean waiting for setup before agent launch: preserve the repository's startup policy, whose default starts setup and the agent side by side. Use `--setup skip` or `--setup inherit` only when there is a concrete task-specific reason, and state that reason before creating the worktree. This rule does not rerun setup for current or existing worktrees.\n\n```bash\norca worktree create --name <task-name> --agent codex --setup run --json\n# or: --agent claude | omp | pi | grok | ...\n# Read <handle> from agentTerminalHandle, falling back to startupTerminal.handle.\norca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json\norca orchestration dispatch --task <task_id> --to <handle> --inject --json\n```\n\nFor new-worktree workers, read the id and `agentTerminalHandle` from `worktree create`, falling back to `startupTerminal.handle` for older runtimes. Use that as the sole worker handle when present; otherwise use `terminal list` to resolve the agent handle. Omit `--repo` only inside an Orca-managed worktree; otherwise pass `--repo <selector>`.\n\n**For an allowed new worktree, use agent-first:** `--agent` reveals the new worktree and launches the selected agent **in its first terminal**, without adding a separate fallback shell for that worker. Pass `--setup run`; repo setup and default-terminal settings may add intentional tabs or splits. Do **not** run bare `worktree create` and then `terminal create --command <agent>` for the same worker when agent-first create is available: without configured default tabs, that two-step path leaves a fallback shell + agent pair. Only use it when custom agent argv is required (for example Codex model/effort flags) or when an older CLI rejects `--agent`; if you must, message only the agent handle. Configured default tabs are intentional surfaces, so close a prior terminal only after `terminal list` or `terminal show` confirms it is an unused shell. Do not run `worktree create` when the task must stay in the current worktree.\n\nUse `orca worktree create --prompt ...` or `orca terminal send ...` for full handoffs or untracked/lightweight prompts. Those paths do not attach `taskId`/`dispatchId`; the worker should not send lifecycle messages unless the prompt supplies a live orchestration preamble.\n\nSidebar lineage and orchestration lifecycle are related but not identical. A same-worktree worker may appear as a peer under that worktree in the sidebar while remaining a child dispatch in orchestration state; only an actual child worktree creates visible parent/child worktree lineage.\n\nOther terminal commands coordinators often need:\n\n```bash\norca terminal list [--worktree <selector>] [--json]\norca terminal create [--worktree <selector>] [--title <text>] [--command <cmd>] [--json]\norca terminal split --terminal <handle> [--direction horizontal|vertical] [--command <cmd>] [--json]\norca terminal wait --terminal <handle> --for tui-idle --timeout-ms <n> --json\norca terminal read --terminal <handle> --json\norca terminal send --terminal <handle> --text <text> --enter --json\n```\n\nIf an older CLI rejects `worktree create --agent`, create the worktree normally, then run `orca terminal create --worktree <selector> --command \"codex\" --json` or `--command \"claude\"`.\n\nWait for `tui-idle` before dispatching. Always pass `--timeout-ms`; real coding tasks can take 15-60 minutes. During supervision, use rolling `check --wait` windows. If a window returns no matching message, inspect `task-list`, `terminal read`, or `terminal wait --for tui-idle` as a liveness checkpoint; if the terminal is still working or producing activity, keep waiting instead of retrying the task.\n\n## Agent Guidance\n\n- Workers with a valid live preamble must send `worker_done` exactly once from their own terminal with an explicit `--outcome succeeded` or `--outcome failed`:\n  `orca orchestration send --type worker_done --subject \"<short status>\" --body \"<3-sentence summary: what you did, what you found, what's left>\" --task-id <task_id> --dispatch-id <dispatch_id> --outcome succeeded --files-modified \"path/a\" --report-path \"<optional>\" --json`\n- A failed outcome is still a terminal report, but Orca records both the Dispatch and Task as failed. Never encode failure only in the subject/body.\n- After sending `worker_done`, end your turn and idle at the agent prompt. Do not poll or keep calling `orca orchestration check`; the coordinator re-engages you with a fresh preamble + TASK block delivered as new terminal input.\n- For long tasks, send heartbeat/status only when the preamble asks for it, including both IDs:\n  `orca orchestration send --type heartbeat --subject \"alive\" --payload '{\"taskId\":\"<task_id>\",\"dispatchId\":\"<dispatch_id>\",\"phase\":\"implementing\"}' --json`\n- If blocked before completion, use `ask`; use `escalation` only when ownership is valid and the coordinator must intervene.\n- Treat preambles inherited through terminal history or full handoffs as stale unless the current prompt explicitly keeps that coordinator in the loop.\n- Coordinators should use `task-list --ready` as external memory, dispatch parallel waves, and avoid dependency chains deeper than 3-4 steps.\n\n## Example\n\n```bash\norca terminal create --worktree active --title login-css-worker --command \"claude\" --json\norca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json\norca orchestration task-create --spec \"Fix the login button CSS\" --json\norca orchestration dispatch --task <task_id> --to <handle> --inject --json\norca orchestration check --wait --types worker_done,escalation,question --timeout-ms 900000 --json\n```\n\n## Next Action\n\nCoordinator: confirm `orca status --json`, create or bind a Run, inspect `task-list`/`dispatch-show` if inheriting state, then use the explicit supervised loop (`task-create` -> `worker-start` -> `check --wait`). Use low-level terminal creation plus `dispatch --inject` only when the composed start does not express the needed topology.\n\nWorker: if the current prompt contains a live dispatch preamble, do the task, use `ask` for blocking questions, and send `worker_done` once with the required payload. If the preamble is stale or absent, do not send lifecycle messages; inspect state or treat the prompt as an ordinary handoff.\n"
 
 // Why: no current guide has bundled reference documents, so --full is byte-identical for now.
 // oxfmt-ignore
diff --git a/src/main/runtime/rpc/orchestration-current-authority-precedence.test.ts b/src/main/runtime/rpc/orchestration-current-authority-precedence.test.ts
new file mode 100644
index 00000000000..27e5b0e1bea
--- /dev/null
+++ b/src/main/runtime/rpc/orchestration-current-authority-precedence.test.ts
@@ -0,0 +1,336 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import {
+  cleanupLegacyCompatibilityDispatcherHarnesses,
+  COORDINATOR_HANDLE,
+  COORDINATOR_PANE,
+  createHarness,
+  currentEvidence,
+  CURRENT_COORDINATOR_HANDLE,
+  CURRENT_COORDINATOR_PANE,
+  CURRENT_WORKER_HANDLE,
+  CURRENT_WORKER_PANE,
+  evidence,
+  invoke,
+  request,
+  WORKER_HANDLE,
+  WORKER_PANE
+} from './orchestration-legacy-compatibility-dispatcher-test-fixture'
+
+afterEach(() => {
+  cleanupLegacyCompatibilityDispatcherHarnesses()
+})
+
+describe('current orchestration authority precedence', () => {
+  it.each(['dispatch', 'websocket'] as const)(
+    '%s uses an attested current coordinator binding before legacy fallback',
+    async (transport) => {
+      const harness = createHarness()
+      const run = harness.db.createRun({
+        objective: 'current work',
+        coordinatorHandle: CURRENT_COORDINATOR_HANDLE,
+        coordinatorPaneKey: CURRENT_COORDINATOR_PANE
+      })
+
+      const response = await invoke(
+        harness.dispatcher,
+        request(
+          'orchestration.taskCreate',
+          {
+            spec: 'current assignment',
+            callerTerminalHandle: CURRENT_COORDINATOR_HANDLE
+          },
+          currentEvidence('coordinator'),
+          `current-task-create-${transport}`
+        ),
+        transport
+      )
+
+      expect(response).toMatchObject({
+        ok: true,
+        result: { task: { run_id: run.id, spec: 'current assignment' } }
+      })
+      expect(harness.db.listTasks({ runId: harness.adoptedRunId })).toHaveLength(1)
+    }
+  )
+
+  it('prefers a different current Run even for the retained coordinator terminal', async () => {
+    const harness = createHarness()
+    const run = harness.db.createRun({
+      objective: 'intentional current work',
+      coordinatorHandle: COORDINATOR_HANDLE,
+      coordinatorPaneKey: COORDINATOR_PANE
+    })
+
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.taskCreate',
+        { spec: 'current assignment', callerTerminalHandle: COORDINATOR_HANDLE },
+        evidence('coordinator'),
+        'retained-terminal-current-run'
+      )
+    )
+
+    expect(response).toMatchObject({ ok: true, result: { task: { run_id: run.id } } })
+  })
+
+  it('checks a different current Run before retained coordinator mail', async () => {
+    const harness = createHarness()
+    const run = harness.db.createRun({
+      objective: 'intentional current work',
+      coordinatorHandle: COORDINATOR_HANDLE,
+      coordinatorPaneKey: COORDINATOR_PANE
+    })
+    const message = harness.db.insertMessage({
+      runId: run.id,
+      from: CURRENT_WORKER_HANDLE,
+      to: `run:${run.id}`,
+      subject: 'current completion',
+      deliveryContract: 'current_delivery'
+    })
+
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.check',
+        { terminal: COORDINATOR_HANDLE },
+        evidence('coordinator'),
+        'retained-terminal-current-check'
+      )
+    )
+
+    expect(response).toMatchObject({
+      ok: true,
+      result: { runId: run.id, messages: [{ id: message.id }], count: 1 }
+    })
+    expect(response).not.toHaveProperty('result.legacyCompatibility')
+  })
+
+  it('preserves legacy fallback for a retained coordinator without a current binding', async () => {
+    const harness = createHarness()
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.taskCreate',
+        { spec: 'legacy follow-up', callerTerminalHandle: COORDINATOR_HANDLE },
+        evidence('coordinator'),
+        'legacy-task-create'
+      )
+    )
+
+    expect(response).toMatchObject({
+      ok: true,
+      result: { task: { run_id: harness.adoptedRunId, spec: 'legacy follow-up' } }
+    })
+  })
+
+  it.each([
+    ['heartbeat', undefined],
+    ['worker_done', 'succeeded']
+  ] as const)(
+    'routes a capability-backed current %s before legacy fallback',
+    async (type, outcome) => {
+      const harness = createHarness()
+      const { taskId, dispatchId, capability } = createCurrentDispatch(harness)
+      const payload = JSON.stringify({
+        taskId,
+        dispatchId,
+        ...(outcome ? { outcome } : {})
+      })
+      const response = await harness.dispatcher.dispatch({
+        ...request(
+          'orchestration.send',
+          {
+            from: CURRENT_WORKER_HANDLE,
+            subject: type === 'heartbeat' ? 'alive' : 'Completed',
+            type,
+            payload
+          },
+          currentEvidence('worker'),
+          `current-${type}`
+        ),
+        orchestrationCapability: capability
+      })
+
+      expect(response).toMatchObject({
+        ok: true,
+        result: {
+          message: {
+            from_handle: CURRENT_WORKER_HANDLE,
+            to_handle: expect.stringMatching(/^run:/),
+            type,
+            delivery_contract: 'current_delivery'
+          }
+        }
+      })
+      expect(response).not.toHaveProperty('result.legacyCompatibility')
+      expect(harness.db.getTask(taskId)?.status).toBe(
+        type === 'worker_done' ? 'completed' : 'dispatched'
+      )
+    }
+  )
+
+  it('routes a current worker mailbox check before legacy fallback', async () => {
+    const harness = createHarness()
+    const { runId, dispatchId } = createCurrentDispatch(harness)
+    const message = harness.db.insertMessage({
+      runId,
+      from: CURRENT_COORDINATOR_HANDLE,
+      to: `dispatch:${dispatchId}`,
+      subject: 'current guidance',
+      deliveryContract: 'current_delivery'
+    })
+
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.check',
+        { terminal: CURRENT_WORKER_HANDLE },
+        currentEvidence('worker'),
+        'current-worker-check'
+      )
+    )
+
+    expect(response).toMatchObject({
+      ok: true,
+      result: {
+        runId,
+        dispatchId,
+        messages: [{ id: message.id }],
+        count: 1
+      }
+    })
+    expect(harness.db.getMessageById(message.id)?.read).toBe(1)
+  })
+
+  it.each(['dispatch', 'websocket'] as const)(
+    '%s routes a reused legacy terminal current check before its retained principal',
+    async (transport) => {
+      const harness = createHarness()
+      const { runId, dispatchId } = await createReusedCurrentDispatch(harness, transport)
+      const message = harness.db.insertMessage({
+        runId,
+        from: CURRENT_COORDINATOR_HANDLE,
+        to: `dispatch:${dispatchId}`,
+        subject: 'reused terminal guidance',
+        deliveryContract: 'current_delivery'
+      })
+
+      const response = await invoke(
+        harness.dispatcher,
+        request(
+          'orchestration.check',
+          { terminal: WORKER_HANDLE },
+          evidence('worker'),
+          `reused-current-check-${transport}`
+        ),
+        transport
+      )
+
+      expect(response).toMatchObject({
+        ok: true,
+        result: {
+          runId,
+          dispatchId,
+          messages: [{ id: message.id }],
+          count: 1
+        }
+      })
+      expect(response).not.toHaveProperty('result.legacyCompatibility')
+    }
+  )
+
+  it.each(['dispatch', 'websocket'] as const)(
+    '%s routes a reused legacy terminal current ask before its retained principal',
+    async (transport) => {
+      const harness = createHarness()
+      const { dispatchId, capability } = await createReusedCurrentDispatch(harness, transport)
+
+      const response = await invoke(
+        harness.dispatcher,
+        {
+          ...request(
+            'orchestration.ask',
+            {
+              from: WORKER_HANDLE,
+              question: 'Continue with the current assignment?',
+              timeoutMs: 0
+            },
+            evidence('worker'),
+            `reused-current-ask-${transport}`
+          ),
+          orchestrationCapability: capability
+        },
+        transport
+      )
+
+      expect(response).toMatchObject({
+        ok: true,
+        result: {
+          answer: null,
+          messageId: expect.any(String),
+          timedOut: true
+        }
+      })
+      expect(response).not.toHaveProperty('result.legacyCompatibility')
+      const questionId = (response as { result: { messageId: string } }).result.messageId
+      expect(harness.db.getQuestion(questionId)?.dispatch_id).toBe(dispatchId)
+    }
+  )
+})
+
+function createCurrentDispatch(harness: ReturnType<typeof createHarness>): {
+  runId: string
+  taskId: string
+  dispatchId: string
+  capability: string
+} {
+  const run = harness.db.createRun({
+    objective: 'current work',
+    coordinatorHandle: CURRENT_COORDINATOR_HANDLE,
+    coordinatorPaneKey: CURRENT_COORDINATOR_PANE
+  })
+  const task = harness.db.createTask({ spec: 'current assignment', runId: run.id })
+  const dispatch = harness.db.createDispatchContext(
+    task.id,
+    CURRENT_WORKER_HANDLE,
+    CURRENT_WORKER_PANE
+  )
+  const capability = harness.db.mintDispatchCapability({
+    dispatchId: dispatch.id,
+    paneKey: CURRENT_WORKER_PANE,
+    processIncarnation: 'process-1'
+  })
+  return { runId: run.id, taskId: task.id, dispatchId: dispatch.id, capability }
+}
+
+async function createReusedCurrentDispatch(
+  harness: ReturnType<typeof createHarness>,
+  suffix: string
+): Promise<{
+  runId: string
+  taskId: string
+  dispatchId: string
+  capability: string
+}> {
+  const legacyCheck = await harness.dispatcher.dispatch(
+    request(
+      'orchestration.check',
+      { terminal: WORKER_HANDLE, peek: true },
+      evidence('worker'),
+      `attest-legacy-worker-${suffix}`
+    )
+  )
+  expect(legacyCheck).toHaveProperty('result.legacyCompatibility')
+  harness.db.completeDispatch(harness.dispatchId)
+
+  const run = harness.db.createRun({
+    objective: 'current work in reused terminal',
+    coordinatorHandle: CURRENT_COORDINATOR_HANDLE,
+    coordinatorPaneKey: CURRENT_COORDINATOR_PANE
+  })
+  const task = harness.db.createTask({ spec: 'reused terminal assignment', runId: run.id })
+  const dispatch = harness.db.createDispatchContext(task.id, WORKER_HANDLE, WORKER_PANE)
+  const capability = harness.db.mintDispatchCapability({
+    dispatchId: dispatch.id,
+    paneKey: WORKER_PANE,
+    processIncarnation: 'process-1'
+  })
+  return { runId: run.id, taskId: task.id, dispatchId: dispatch.id, capability }
+}
diff --git a/src/main/runtime/rpc/orchestration-legacy-compatibility-dispatcher-test-fixture.ts b/src/main/runtime/rpc/orchestration-legacy-compatibility-dispatcher-test-fixture.ts
index a7d98082a54..b2c31d741c0 100644
--- a/src/main/runtime/rpc/orchestration-legacy-compatibility-dispatcher-test-fixture.ts
+++ b/src/main/runtime/rpc/orchestration-legacy-compatibility-dispatcher-test-fixture.ts
@@ -16,6 +16,10 @@ export const WORKER_HANDLE = 'term_legacy_worker'
 export const WORKER_PANE = 'tab_worker:33333333-3333-4333-8333-333333333333'
 export const COORDINATOR_HANDLE = 'term_legacy_coord'
 export const COORDINATOR_PANE = 'tab_coord:44444444-4444-4444-8444-444444444444'
+export const CURRENT_COORDINATOR_HANDLE = 'term_current_coord'
+export const CURRENT_COORDINATOR_PANE = 'tab_current_coord:55555555-5555-4555-8555-555555555555'
+export const CURRENT_WORKER_HANDLE = 'term_current_worker'
+export const CURRENT_WORKER_PANE = 'tab_current_worker:66666666-6666-4666-8666-666666666666'
 
 type Transport = 'dispatch' | 'websocket'
 
@@ -71,8 +75,23 @@ export function createHarness(): LegacyCompatibilityDispatcherHarness {
   const adoptedRunId = db.getLegacyAdoption()?.adopted_run_id as string
   const runtime = new OrcaRuntimeService()
   runtime.setOrchestrationDb(db)
-  vi.spyOn(runtime, 'getTerminalPaneKey').mockImplementation((handle) =>
-    handle === COORDINATOR_HANDLE ? COORDINATOR_PANE : handle === WORKER_HANDLE ? WORKER_PANE : null
+  vi.spyOn(runtime, 'getTerminalPaneKey').mockImplementation((handle) => {
+    if (handle === COORDINATOR_HANDLE) {
+      return COORDINATOR_PANE
+    }
+    if (handle === WORKER_HANDLE) {
+      return WORKER_PANE
+    }
+    if (handle === CURRENT_COORDINATOR_HANDLE) {
+      return CURRENT_COORDINATOR_PANE
+    }
+    if (handle === CURRENT_WORKER_HANDLE) {
+      return CURRENT_WORKER_PANE
+    }
+    return null
+  })
+  vi.spyOn(runtime, 'getTerminalProcessIncarnation').mockImplementation((handle) =>
+    [WORKER_HANDLE, CURRENT_WORKER_HANDLE].includes(handle) ? 'process-1' : null
   )
   const verify = vi
     .spyOn(runtime, 'verifyOrchestrationCompatibilityCaller')
@@ -81,7 +100,16 @@ export function createHarness(): LegacyCompatibilityDispatcherHarness {
         evidence?.terminalHandle === WORKER_HANDLE && evidence.paneKey === WORKER_PANE
       const validCoordinator =
         evidence?.terminalHandle === COORDINATOR_HANDLE && evidence.paneKey === COORDINATOR_PANE
-      if ((!validWorker && !validCoordinator) || !evidence?.launchToken) {
+      const validCurrentCoordinator =
+        evidence?.terminalHandle === CURRENT_COORDINATOR_HANDLE &&
+        evidence.paneKey === CURRENT_COORDINATOR_PANE
+      const validCurrentWorker =
+        evidence?.terminalHandle === CURRENT_WORKER_HANDLE &&
+        evidence.paneKey === CURRENT_WORKER_PANE
+      if (
+        (!validWorker && !validCoordinator && !validCurrentCoordinator && !validCurrentWorker) ||
+        !evidence?.launchToken
+      ) {
         return null
       }
       return {
@@ -117,6 +145,17 @@ export function evidence(
   }
 }
 
+export function currentEvidence(
+  role: 'worker' | 'coordinator'
+): OrchestrationCompatibilityEvidence {
+  const worker = role === 'worker'
+  return {
+    terminalHandle: worker ? CURRENT_WORKER_HANDLE : CURRENT_COORDINATOR_HANDLE,
+    paneKey: worker ? CURRENT_WORKER_PANE : CURRENT_COORDINATOR_PANE,
+    launchToken: `current-${role}-token`
+  }
+}
+
 export function request(
   method: string,
   params: unknown,
diff --git a/src/main/runtime/rpc/orchestration-legacy-compatibility.ts b/src/main/runtime/rpc/orchestration-legacy-compatibility.ts
index ff699d34636..52b0fd0535b 100644
--- a/src/main/runtime/rpc/orchestration-legacy-compatibility.ts
+++ b/src/main/runtime/rpc/orchestration-legacy-compatibility.ts
@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto'
 import type { LegacyCoordinatorAuthorityProof, RpcRequest } from './core'
 import type { OrcaRuntimeService, OrchestrationCompatibilityCallerAuthority } from '../orca-runtime'
+import { CURRENT_CONTRACT_VERSION } from '../orchestration/db'
 import { LegacyCompatibilityAuthority } from './orchestration-legacy-authority'
 import { handleLegacyLifecycleSend } from './orchestration-legacy-lifecycle'
 import { handleLegacyCheck, handleLegacyReply } from './orchestration-legacy-mail'
@@ -26,6 +27,11 @@ const COORDINATOR_PREFLIGHT_METHODS = new Set([
   'orchestration.reply'
 ])
 
+const CURRENT_AUTHORITY_PREFLIGHT_METHODS = new Set([
+  ...COORDINATOR_PREFLIGHT_METHODS,
+  'orchestration.ask'
+])
+
 export type LegacyCompatibilityRoute =
   | { handled: true; result: unknown }
   | {
@@ -58,6 +64,13 @@ export class OrchestrationLegacyCompatibility {
     if (!request.method.startsWith('orchestration.')) {
       return { handled: false }
     }
+    const values = params as Record<string, unknown>
+    if (
+      CURRENT_AUTHORITY_PREFLIGHT_METHODS.has(request.method) &&
+      this.usesCurrentAuthority(request, values)
+    ) {
+      return { handled: false }
+    }
     const result = await this.route(request, params, signal)
     if (result !== undefined) {
       return { handled: true, result }
@@ -65,7 +78,6 @@ export class OrchestrationLegacyCompatibility {
     if (!COORDINATOR_PREFLIGHT_METHODS.has(request.method)) {
       return { handled: false }
     }
-    const values = params as Record<string, unknown>
     if (request.method === 'orchestration.runUse' && values.takeoverLegacy === true) {
       const callerAuthority = this.runtime.verifyOrchestrationCompatibilityCaller(
         request.orchestrationCompatibilityEvidence
@@ -110,6 +122,75 @@ export class OrchestrationLegacyCompatibility {
       : undefined
   }
 
+  private usesCurrentAuthority(request: RpcRequest, params: Record<string, unknown>): boolean {
+    const db = this.runtime.getOrchestrationDb()
+    const adoption = db.getLegacyAdoption()
+    if (!adoption || stringValue(params.run) || request.method === 'orchestration.runUse') {
+      return false
+    }
+    const evidence = request.orchestrationCompatibilityEvidence
+    if (!evidence?.terminalHandle || !evidence.paneKey) {
+      return false
+    }
+    const claimedHandle = currentCallerHandle(request.method, params)
+    if (claimedHandle && claimedHandle !== evidence.terminalHandle) {
+      return false
+    }
+    const dispatch = db.getActiveDispatchForIdentity(evidence.terminalHandle, evidence.paneKey)
+    if (dispatch) {
+      if (dispatch.contract_version !== CURRENT_CONTRACT_VERSION) {
+        return false
+      }
+      const caller = this.runtime.verifyOrchestrationCompatibilityCaller(evidence)
+      return Boolean(
+        caller &&
+        caller.terminalHandle === evidence.terminalHandle &&
+        db.getActiveDispatchForIdentity(caller.terminalHandle, caller.paneKey)?.id === dispatch.id
+      )
+    }
+    const remoteAttachment = db.findActiveRemoteAttachmentForPane(evidence.paneKey)
+    if (remoteAttachment) {
+      const caller = this.runtime.verifyOrchestrationCompatibilityCaller(evidence)
+      return Boolean(
+        caller &&
+        caller.terminalHandle === evidence.terminalHandle &&
+        db.findActiveRemoteAttachmentForPane(caller.paneKey)?.dispatch_id ===
+          remoteAttachment.dispatch_id
+      )
+    }
+    const boundRun = db.getCurrentRunForPane(evidence.paneKey)
+    if (!boundRun) {
+      return false
+    }
+    const legacyCandidate =
+      boundRun.id === adoption.adopted_run_id
+        ? db.resolveLegacyCoordinatorCandidate({
+            runId: adoption.adopted_run_id,
+            terminalHandle: evidence.terminalHandle,
+            paneKey: evidence.paneKey
+          })
+        : undefined
+    if (legacyCandidate) {
+      return false
+    }
+    const caller = this.runtime.verifyOrchestrationCompatibilityCaller(evidence)
+    if (
+      !caller ||
+      caller.terminalHandle !== evidence.terminalHandle ||
+      db.getCurrentRunForPane(caller.paneKey)?.id !== boundRun.id
+    ) {
+      return false
+    }
+    if (boundRun.id !== adoption.adopted_run_id) {
+      return true
+    }
+    return !db.resolveLegacyCoordinatorCandidate({
+      runId: adoption.adopted_run_id,
+      terminalHandle: caller.terminalHandle,
+      paneKey: caller.paneKey
+    })
+  }
+
   private async route(
     request: RpcRequest,
     params: unknown,
@@ -168,3 +249,17 @@ function legacyCoordinatorMutationCallerFingerprint(
 function stringValue(value: unknown): string | undefined {
   return typeof value === 'string' && value.length > 0 ? value : undefined
 }
+
+function currentCallerHandle(method: string, params: Record<string, unknown>): string | undefined {
+  if (
+    method === 'orchestration.taskCreate' ||
+    method === 'orchestration.taskList' ||
+    method === 'orchestration.taskUpdate'
+  ) {
+    return stringValue(params.callerTerminalHandle)
+  }
+  if (method === 'orchestration.check') {
+    return stringValue(params.terminal)
+  }
+  return stringValue(params.from)
+}

From f936e7fc9c7defebc40398a1ddf2ce50e93c7dfc Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Fri, 31 Jul 2026 01:57:41 -0700
Subject: [PATCH 13/23] feat(editor): richer rich-markdown table keyboard (Tab,
 Enter, Backspace) (#11724)

Co-authored-by: Orca <help@stably.ai>
---
 .../editor/rich-markdown-key-handler.test.ts  |  55 ++++
 .../editor/rich-markdown-key-handler.ts       |  33 ++-
 .../editor/rich-markdown-table-enter.ts       |  44 +++
 .../rich-markdown-table-keyboard.test.ts      | 271 ++++++++++++++++++
 .../editor/rich-markdown-table-row-delete.ts  |  76 +++++
 .../editor/rich-markdown-table-tab.ts         |  28 ++
 .../e2e/markdown-table-row-backspace.spec.ts  | 152 ++++++++++
 7 files changed, 654 insertions(+), 5 deletions(-)
 create mode 100644 src/renderer/src/components/editor/rich-markdown-table-enter.ts
 create mode 100644 src/renderer/src/components/editor/rich-markdown-table-keyboard.test.ts
 create mode 100644 src/renderer/src/components/editor/rich-markdown-table-row-delete.ts
 create mode 100644 src/renderer/src/components/editor/rich-markdown-table-tab.ts
 create mode 100644 tests/e2e/markdown-table-row-backspace.spec.ts

diff --git a/src/renderer/src/components/editor/rich-markdown-key-handler.test.ts b/src/renderer/src/components/editor/rich-markdown-key-handler.test.ts
index a78f1b103fd..26847626853 100644
--- a/src/renderer/src/components/editor/rich-markdown-key-handler.test.ts
+++ b/src/renderer/src/components/editor/rich-markdown-key-handler.test.ts
@@ -3,6 +3,8 @@ import { Editor } from '@tiptap/core'
 import StarterKit from '@tiptap/starter-kit'
 import { createIsolatedMarkdownExtensionForTests } from './isolated-markdown-extension-for-tests'
 import { createRichMarkdownKeyHandler, type KeyHandlerContext } from './rich-markdown-key-handler'
+import { createRichMarkdownExtensions } from './rich-markdown-extensions'
+import { createRichMarkdownEditorCodec } from './rich-markdown-source-transport'
 
 // Why: keybinding matching resolves the platform from navigator.userAgent,
 // which is environment-dependent under vitest; pin it for determinism.
@@ -20,6 +22,39 @@ function createEditor(content: object): Editor {
   })
 }
 
+const TABLE_MARKDOWN = `| A | B |
+| --- | --- |
+| a1 | b1 |
+| a2 | b2 |
+`
+
+// The StarterKit schema above has no table nodes, so table key paths need this one.
+function createTableEditor(): Editor {
+  return new Editor({
+    element: null,
+    extensions: createRichMarkdownExtensions({ codec: createRichMarkdownEditorCodec() }),
+    content: TABLE_MARKDOWN,
+    contentType: 'markdown'
+  })
+}
+
+function caretAtText(editor: Editor, text: string): number {
+  let position: number | null = null
+  editor.state.doc.descendants((node, pos) => {
+    if (!node.isText || node.text !== text) {
+      return true
+    }
+    position = pos
+    return false
+  })
+
+  if (position === null) {
+    throw new Error(`Expected cell text: ${text}`)
+  }
+
+  return position
+}
+
 function firstEmptyParagraphPosition(editor: Editor): number {
   let position: number | null = null
   editor.state.doc.descendants((node, pos) => {
@@ -300,6 +335,26 @@ describe('rich markdown key handler', () => {
     }
   })
 
+  it('runs the selected slash command on Enter instead of the table cell-below move', () => {
+    const editor = createTableEditor()
+
+    try {
+      editor.commands.setTextSelection(caretAtText(editor, 'a1'))
+      const ctx = createContext(editor, false)
+      const from = editor.state.selection.from
+      const run = vi.fn()
+      ctx.slashMenuRef.current = { query: '', from, to: from, left: 0, top: 0 }
+      ctx.filteredSlashCommandsRef.current = [{ id: 'heading-1', run } as never]
+      const event = keyEvent('Enter')
+
+      expect(createRichMarkdownKeyHandler(ctx)(null, event)).toBe(true)
+      expect(run).toHaveBeenCalledWith(editor)
+      expect(editor.state.selection.$from.parent.textContent).toBe('a1')
+    } finally {
+      editor.destroy()
+    }
+  })
+
   it('dismisses the slash menu on Escape even when search has no matches', () => {
     const editor = createEditor({
       type: 'doc',
diff --git a/src/renderer/src/components/editor/rich-markdown-key-handler.ts b/src/renderer/src/components/editor/rich-markdown-key-handler.ts
index b0a223887b5..358d236e1eb 100644
--- a/src/renderer/src/components/editor/rich-markdown-key-handler.ts
+++ b/src/renderer/src/components/editor/rich-markdown-key-handler.ts
@@ -18,6 +18,9 @@ import {
   exitTrailingEmptyOrderedListItem
 } from './rich-markdown-list-continuation'
 import { deleteAdjacentEmptyParagraph } from './rich-markdown-empty-paragraph-delete'
+import { handleRichMarkdownTableBackspace } from './rich-markdown-table-row-delete'
+import { handleRichMarkdownTableEnter } from './rich-markdown-table-enter'
+import { handleRichMarkdownTableTab } from './rich-markdown-table-tab'
 import { handleRichMarkdownCitationKey } from './rich-markdown-citation-keyboard'
 import type { RichMarkdownHtmlSuperscriptLinkContext } from './rich-markdown-html-superscript-link-context'
 import { handleRichMarkdownLinkShortcut } from './rich-markdown-link-shortcut'
@@ -129,7 +132,8 @@ export function createRichMarkdownKeyHandler(
         !isComposingMarkdownInput(event, ed) &&
         (convertEmptyNestedOrderedItemToContinuation(ed) ||
           collapseEmptyListContinuationParagraph(ed) ||
-          deleteAdjacentEmptyParagraph(ed, 'backward'))
+          deleteAdjacentEmptyParagraph(ed, 'backward') ||
+          handleRichMarkdownTableBackspace(ed))
       ) {
         event.preventDefault()
         return true
@@ -164,12 +168,25 @@ export function createRichMarkdownKeyHandler(
         event.preventDefault()
         return true
       }
+      // Why: table Enter (cell below / add row) must run before ProseMirror
+      // inserts an in-cell paragraph that GFM serialization cannot keep — but
+      // the slash/doc-link menus own Enter while open (their blocks run later).
+      if (
+        ed &&
+        !ctx.slashMenuRef.current &&
+        !ctx.docLinkMenuRef.current &&
+        !isComposingMarkdownInput(event, ed) &&
+        handleRichMarkdownTableEnter(ed)
+      ) {
+        event.preventDefault()
+        return true
+      }
     }
 
-    // Tab/Shift-Tab: indent/outdent lists, insert spaces in code blocks,
-    // and prevent focus from escaping the editor. When the slash menu or
-    // doc-link menu is open, Tab selects a row instead (handled in the
-    // menu blocks below).
+    // Tab/Shift-Tab: table cell nav first, then list indent/outdent, code-block
+    // spaces, and prevent focus escaping the editor.
+    // When the slash menu or doc-link menu is open, Tab selects a row instead
+    // (handled in the menu blocks below).
     if (event.key === 'Tab' && !ctx.slashMenuRef.current && !ctx.docLinkMenuRef.current) {
       event.preventDefault()
       const ed = ctx.editorRef.current
@@ -178,6 +195,12 @@ export function createRichMarkdownKeyHandler(
       }
       flushPendingProseMirrorSelection(ed)
 
+      // Why: Orca's Tab handler runs before TipTap Table shortcuts and used to
+      // always sink/lift lists, so table cell Tab/Shift-Tab never fired.
+      if (!isComposingMarkdownInput(event, ed) && handleRichMarkdownTableTab(ed, event.shiftKey)) {
+        return true
+      }
+
       if (event.shiftKey) {
         if (!ed.commands.liftListItem('listItem')) {
           ed.commands.liftListItem('taskItem')
diff --git a/src/renderer/src/components/editor/rich-markdown-table-enter.ts b/src/renderer/src/components/editor/rich-markdown-table-enter.ts
new file mode 100644
index 00000000000..c3ee2aa45aa
--- /dev/null
+++ b/src/renderer/src/components/editor/rich-markdown-table-enter.ts
@@ -0,0 +1,44 @@
+import type { Editor } from '@tiptap/react'
+import { TextSelection } from '@tiptap/pm/state'
+import { isInTable, moveCellForward, nextCell, selectionCell } from '@tiptap/pm/tables'
+
+function moveToVerticalNeighbor(editor: Editor, direction: 1 | -1): boolean {
+  const { state, view } = editor
+  const $nextCell = nextCell(selectionCell(state), 'vert', direction)
+  if (!$nextCell) {
+    return false
+  }
+
+  view.dispatch(
+    state.tr
+      .setSelection(TextSelection.between($nextCell, moveCellForward($nextCell)))
+      .scrollIntoView()
+  )
+  return true
+}
+
+/**
+ * Table Enter: move to the cell below instead of inserting an in-cell
+ * paragraph (GFM cannot keep multi-line table cells). On the last row,
+ * insert a row and move into it. Returns true when consumed inside a table.
+ */
+export function handleRichMarkdownTableEnter(editor: Editor): boolean {
+  if (!isInTable(editor.state)) {
+    return false
+  }
+
+  if (moveToVerticalNeighbor(editor, 1)) {
+    return true
+  }
+
+  // Why: last-row Enter grows the table rather than inserting an in-cell hard
+  // break that GFM serialization cannot keep.
+  if (!editor.can().addRowAfter()) {
+    return true
+  }
+
+  editor.commands.addRowAfter()
+  // Selection stays in the original row; step down into the new one.
+  moveToVerticalNeighbor(editor, 1)
+  return true
+}
diff --git a/src/renderer/src/components/editor/rich-markdown-table-keyboard.test.ts b/src/renderer/src/components/editor/rich-markdown-table-keyboard.test.ts
new file mode 100644
index 00000000000..591e175ff3b
--- /dev/null
+++ b/src/renderer/src/components/editor/rich-markdown-table-keyboard.test.ts
@@ -0,0 +1,271 @@
+import { describe, expect, it } from 'vitest'
+import { Editor } from '@tiptap/core'
+import { createRichMarkdownExtensions } from './rich-markdown-extensions'
+import { createRichMarkdownEditorCodec } from './rich-markdown-source-transport'
+import { handleRichMarkdownTableBackspace } from './rich-markdown-table-row-delete'
+import { handleRichMarkdownTableEnter } from './rich-markdown-table-enter'
+import { handleRichMarkdownTableTab } from './rich-markdown-table-tab'
+
+const TABLE = `| A | B |
+| --- | --- |
+| a1 | b1 |
+| a2 | b2 |
+`
+
+// Middle body row parses to two empty cells.
+const TABLE_WITH_EMPTY_ROW = `| Name | Value |
+| --- | --- |
+| keep | a |
+|  |  |
+| stay | c |
+`
+
+function createEditor(content = TABLE): Editor {
+  return new Editor({
+    element: null,
+    extensions: createRichMarkdownExtensions({ codec: createRichMarkdownEditorCodec() }),
+    content,
+    contentType: 'markdown'
+  })
+}
+
+function countRows(editor: Editor): number {
+  let count = 0
+  editor.state.doc.descendants((node) => {
+    if (node.type.name === 'tableRow') {
+      count += 1
+    }
+  })
+  return count
+}
+
+function hasTable(editor: Editor): boolean {
+  let found = false
+  editor.state.doc.descendants((node) => {
+    if (node.type.name === 'table') {
+      found = true
+    }
+    return !found
+  })
+  return found
+}
+
+/** Caret at the start of the text node holding `text`. */
+function caretAtText(editor: Editor, text: string): number {
+  let position: number | null = null
+  editor.state.doc.descendants((node, pos) => {
+    if (!node.isText || node.text !== text) {
+      return true
+    }
+    position = pos
+    return false
+  })
+  if (position === null) {
+    throw new Error(`Expected cell text: ${text}`)
+  }
+  return position
+}
+
+/** Caret in the nth cell (0-based) of the first row where `predicate` holds. */
+function caretInRow(
+  editor: Editor,
+  predicate: (rowText: string) => boolean,
+  cellIndex = 0
+): number {
+  let position: number | null = null
+  editor.state.doc.descendants((node, pos) => {
+    if (node.type.name !== 'tableRow' || !predicate(node.textContent)) {
+      return true
+    }
+    let offset = pos + 1
+    for (let index = 0; index < cellIndex; index += 1) {
+      offset += node.child(index).nodeSize
+    }
+    // cell open + paragraph open
+    position = offset + 2
+    return false
+  })
+  if (position === null) {
+    throw new Error('Expected a matching table row')
+  }
+  return position
+}
+
+function selectionText(editor: Editor): string {
+  return editor.state.selection.$from.parent.textContent
+}
+
+function withEditor(content: string, run: (editor: Editor) => void): void {
+  const editor = createEditor(content)
+  try {
+    run(editor)
+  } finally {
+    editor.destroy()
+  }
+}
+
+describe('handleRichMarkdownTableTab', () => {
+  it('moves Tab to the next cell', () => {
+    withEditor(TABLE, (editor) => {
+      editor.commands.setTextSelection(caretAtText(editor, 'a1'))
+      expect(handleRichMarkdownTableTab(editor, false)).toBe(true)
+      expect(selectionText(editor)).toBe('b1')
+    })
+  })
+
+  it('moves Shift-Tab to the previous cell', () => {
+    withEditor(TABLE, (editor) => {
+      editor.commands.setTextSelection(caretAtText(editor, 'b1'))
+      expect(handleRichMarkdownTableTab(editor, true)).toBe(true)
+      expect(selectionText(editor)).toBe('a1')
+    })
+  })
+
+  it('wraps Tab to the next row', () => {
+    withEditor(TABLE, (editor) => {
+      editor.commands.setTextSelection(caretAtText(editor, 'b1'))
+      expect(handleRichMarkdownTableTab(editor, false)).toBe(true)
+      expect(selectionText(editor)).toBe('a2')
+    })
+  })
+
+  it('adds a row when Tab is pressed in the last cell', () => {
+    withEditor(TABLE, (editor) => {
+      const rowsBefore = countRows(editor)
+      editor.commands.setTextSelection(caretAtText(editor, 'b2') + 'b2'.length)
+      expect(handleRichMarkdownTableTab(editor, false)).toBe(true)
+      expect(countRows(editor)).toBe(rowsBefore + 1)
+      expect(selectionText(editor)).toBe('')
+      expect(editor.isActive('table')).toBe(true)
+    })
+  })
+
+  it('does not claim Tab outside tables', () => {
+    withEditor('Just a paragraph.\n', (editor) => {
+      editor.commands.setTextSelection(1)
+      expect(handleRichMarkdownTableTab(editor, false)).toBe(false)
+      expect(handleRichMarkdownTableTab(editor, true)).toBe(false)
+    })
+  })
+})
+
+describe('handleRichMarkdownTableEnter', () => {
+  it('moves Enter to the cell below', () => {
+    withEditor(TABLE, (editor) => {
+      editor.commands.setTextSelection(caretAtText(editor, 'a1'))
+      expect(handleRichMarkdownTableEnter(editor)).toBe(true)
+      expect(selectionText(editor)).toBe('a2')
+    })
+  })
+
+  it('adds a row when Enter is pressed on the last row', () => {
+    withEditor(TABLE, (editor) => {
+      const rowsBefore = countRows(editor)
+      editor.commands.setTextSelection(caretAtText(editor, 'a2'))
+      expect(handleRichMarkdownTableEnter(editor)).toBe(true)
+      expect(countRows(editor)).toBe(rowsBefore + 1)
+      expect(selectionText(editor)).toBe('')
+      expect(editor.isActive('table')).toBe(true)
+    })
+  })
+
+  it('does not claim Enter outside tables', () => {
+    withEditor('Just a paragraph.\n', (editor) => {
+      editor.commands.setTextSelection(1)
+      expect(handleRichMarkdownTableEnter(editor)).toBe(false)
+    })
+  })
+})
+
+describe('handleRichMarkdownTableBackspace', () => {
+  it('deletes a fully empty row and leaves sibling rows intact', () => {
+    withEditor(TABLE_WITH_EMPTY_ROW, (editor) => {
+      expect(countRows(editor)).toBe(4)
+      editor.commands.setTextSelection(caretInRow(editor, (text) => text.length === 0))
+      expect(handleRichMarkdownTableBackspace(editor)).toBe(true)
+
+      expect(countRows(editor)).toBe(3)
+      const markdown = editor.getMarkdown()
+      expect(markdown).toContain('keep')
+      expect(markdown).toContain('stay')
+      expect(markdown).toContain('| Name')
+      expect(hasTable(editor)).toBe(true)
+    })
+  })
+
+  it('removes the whole table once the last remaining row is deleted', () => {
+    withEditor('', (editor) => {
+      editor.commands.insertTable({ rows: 2, cols: 2, withHeaderRow: false })
+      expect(countRows(editor)).toBe(2)
+
+      editor.commands.setTextSelection(caretInRow(editor, () => true))
+      expect(handleRichMarkdownTableBackspace(editor)).toBe(true)
+      expect(countRows(editor)).toBe(1)
+
+      editor.commands.setTextSelection(caretInRow(editor, () => true))
+      expect(handleRichMarkdownTableBackspace(editor)).toBe(true)
+      expect(hasTable(editor)).toBe(false)
+    })
+  })
+
+  it('keeps an emptied header row while body rows remain', () => {
+    withEditor(
+      `|  |  |
+| --- | --- |
+| keep | a |
+| stay | c |
+`,
+      (editor) => {
+        const before = editor.getMarkdown()
+        editor.commands.setTextSelection(caretInRow(editor, (text) => text.length === 0))
+        // Consumed so ProseMirror cannot merge the table into what precedes it.
+        expect(handleRichMarkdownTableBackspace(editor)).toBe(true)
+        expect(countRows(editor)).toBe(3)
+        expect(editor.getMarkdown()).toBe(before)
+      }
+    )
+  })
+
+  it('does not hijack Backspace when the current cell still has content', () => {
+    withEditor(TABLE_WITH_EMPTY_ROW, (editor) => {
+      editor.commands.setTextSelection(caretAtText(editor, 'keep'))
+      expect(handleRichMarkdownTableBackspace(editor)).toBe(false)
+      expect(countRows(editor)).toBe(4)
+    })
+  })
+
+  it('steps to the previous cell from an empty cell in a row that has content', () => {
+    withEditor(TABLE, (editor) => {
+      // Empty the "b1" cell, leaving "a1" in place.
+      const cellStart = caretAtText(editor, 'b1')
+      editor.view.dispatch(editor.state.tr.delete(cellStart, cellStart + 'b1'.length))
+
+      editor.commands.setTextSelection(caretInRow(editor, (text) => text === 'a1', 1))
+      expect(handleRichMarkdownTableBackspace(editor)).toBe(true)
+      expect(countRows(editor)).toBe(3)
+      expect(selectionText(editor)).toBe('a1')
+    })
+  })
+
+  it('does not treat an image-only cell as empty', () => {
+    withEditor(TABLE_WITH_EMPTY_ROW, (editor) => {
+      const emptyRowCaret = caretInRow(editor, (text) => text.length === 0, 1)
+      editor.commands.insertContentAt(emptyRowCaret, {
+        type: 'image',
+        attrs: { src: 'shot.png' }
+      })
+
+      editor.commands.setTextSelection(caretInRow(editor, (text) => text.length === 0))
+      expect(handleRichMarkdownTableBackspace(editor)).toBe(true)
+      // Row keeps the image cell; Backspace steps back instead of deleting.
+      expect(countRows(editor)).toBe(4)
+    })
+  })
+
+  it('does not hijack Backspace outside tables', () => {
+    withEditor('Just a paragraph.\n', (editor) => {
+      editor.commands.setTextSelection(1)
+      expect(handleRichMarkdownTableBackspace(editor)).toBe(false)
+    })
+  })
+})
diff --git a/src/renderer/src/components/editor/rich-markdown-table-row-delete.ts b/src/renderer/src/components/editor/rich-markdown-table-row-delete.ts
new file mode 100644
index 00000000000..f2a78af8bee
--- /dev/null
+++ b/src/renderer/src/components/editor/rich-markdown-table-row-delete.ts
@@ -0,0 +1,76 @@
+import type { Editor } from '@tiptap/react'
+import type { Node as PmNode } from '@tiptap/pm/model'
+import { isInTable, selectionCell } from '@tiptap/pm/tables'
+
+/** Why: textContent alone is empty for image/embed-only cells, which do have content. */
+function isEmptyCell(cell: PmNode): boolean {
+  for (let index = 0; index < cell.childCount; index += 1) {
+    const child = cell.child(index)
+    if (!child.isTextblock || child.content.size > 0) {
+      return false
+    }
+  }
+  return true
+}
+
+function isHeaderRow(row: PmNode): boolean {
+  return row.firstChild?.type.spec.tableRole === 'header_cell'
+}
+
+function isEmptyRow(row: PmNode): boolean {
+  for (let index = 0; index < row.childCount; index += 1) {
+    if (!isEmptyCell(row.child(index))) {
+      return false
+    }
+  }
+  return row.childCount > 0
+}
+
+/**
+ * Structural Backspace inside tables:
+ * 1. Fully empty row → delete row (or the table if it was the last row)
+ * 2. Empty cell in a row that still has content → step to the previous cell
+ * 3. Otherwise fall through to the default content delete
+ */
+export function handleRichMarkdownTableBackspace(editor: Editor): boolean {
+  const { state } = editor
+  if (!state.selection.empty || !isInTable(state)) {
+    return false
+  }
+
+  // selectionCell resolves *before* the cell: nodeAfter is the cell, parent the
+  // row, node(-1) the table.
+  const $cell = selectionCell(state)
+  const cell = $cell.nodeAfter
+  if (!cell || !isEmptyCell(cell)) {
+    return false
+  }
+
+  // $cell.pos + 2 is the start of the cell's first textblock. A caret past it
+  // sits in a second empty paragraph, which should join rather than drop a row.
+  if (state.selection.from !== $cell.pos + 2) {
+    return false
+  }
+
+  if (!isEmptyRow($cell.parent)) {
+    // Step back a cell instead of joining across the cell boundary into the
+    // previous cell's text. Consume either way so ProseMirror never merges the
+    // table into whatever precedes it.
+    editor.commands.goToPreviousCell()
+    return true
+  }
+
+  // Why: prosemirror-tables deleteRow refuses when only one row remains;
+  // deleteTable is the correct last-row exit.
+  if ($cell.node(-1).childCount <= 1) {
+    return editor.commands.deleteTable()
+  }
+
+  // Why: GFM re-synthesizes an empty header on serialize, so deleting the
+  // header row would vanish from the editor but return on the next reload.
+  if (isHeaderRow($cell.parent)) {
+    return true
+  }
+
+  return editor.commands.deleteRow()
+}
diff --git a/src/renderer/src/components/editor/rich-markdown-table-tab.ts b/src/renderer/src/components/editor/rich-markdown-table-tab.ts
new file mode 100644
index 00000000000..082b09dfa54
--- /dev/null
+++ b/src/renderer/src/components/editor/rich-markdown-table-tab.ts
@@ -0,0 +1,28 @@
+import type { Editor } from '@tiptap/react'
+
+/**
+ * Table Tab: move between cells; Tab past the last cell inserts a row.
+ * Returns true when the key should be consumed (always inside a table).
+ */
+export function handleRichMarkdownTableTab(editor: Editor, shiftKey: boolean): boolean {
+  if (!editor.isActive('table')) {
+    return false
+  }
+
+  if (shiftKey) {
+    editor.commands.goToPreviousCell()
+    return true
+  }
+
+  if (editor.commands.goToNextCell()) {
+    return true
+  }
+
+  // Why: match TipTap Table shortcuts — last-cell Tab grows the table instead
+  // of letting focus escape the editor.
+  if (editor.can().addRowAfter()) {
+    editor.chain().addRowAfter().goToNextCell().run()
+  }
+
+  return true
+}
diff --git a/tests/e2e/markdown-table-row-backspace.spec.ts b/tests/e2e/markdown-table-row-backspace.spec.ts
new file mode 100644
index 00000000000..6a30f81f9f7
--- /dev/null
+++ b/tests/e2e/markdown-table-row-backspace.spec.ts
@@ -0,0 +1,152 @@
+import path from 'node:path'
+import { test, expect } from './helpers/orca-app'
+import { waitForActiveWorktree, waitForSessionReady } from './helpers/store'
+import {
+  cleanupMarkdownFixture,
+  createMarkdownFixture,
+  getActiveWorktreeContext,
+  openMarkdownFixture,
+  waitForRichMarkdownEditor
+} from './helpers/markdown-ordered-list-exit'
+
+// Middle body row starts empty so Backspace can structural-delete without
+// relying on Meta+A (which selects the whole document in TipTap).
+const TABLE_MARKDOWN = `| Name | Value |
+| --- | --- |
+| keep | a |
+|  |  |
+| stay | c |
+`
+
+const SCRATCH_DIR =
+  process.env.ORCA_TABLE_ROW_BACKSPACE_SCREENSHOT_DIR ??
+  path.join(process.cwd(), 'test-results', 'table-row-backspace')
+
+async function selectionCellText(page: {
+  evaluate: (fn: () => string | null) => Promise<string | null>
+}): Promise<string | null> {
+  return page.evaluate(() => {
+    const selection = window.getSelection()
+    if (!selection || selection.rangeCount === 0) {
+      return null
+    }
+    const node = selection.anchorNode
+    if (!node) {
+      return null
+    }
+    const element = node.nodeType === Node.ELEMENT_NODE ? (node as Element) : node.parentElement
+    const cell = element?.closest('td, th')
+    return cell?.textContent?.trim() ?? null
+  })
+}
+
+async function tableRowCount(page: {
+  evaluate: (fn: () => number) => Promise<number>
+}): Promise<number> {
+  return page.evaluate(() => {
+    const editorRoot = document.querySelector('.rich-markdown-editor')
+    if (!editorRoot) {
+      return -1
+    }
+    return editorRoot.querySelectorAll('tr').length
+  })
+}
+
+test.describe('Markdown table keyboard', () => {
+  test.beforeEach(async ({ orcaPage }) => {
+    await waitForSessionReady(orcaPage)
+    await waitForActiveWorktree(orcaPage)
+  })
+
+  test('Tab/Shift-Tab move between cells and empty-row Backspace deletes the row', async ({
+    orcaPage
+  }, testInfo) => {
+    const context = await getActiveWorktreeContext(orcaPage)
+    let filePath: string | null = null
+
+    try {
+      filePath = await createMarkdownFixture(
+        context,
+        'table-row-backspace',
+        testInfo.workerIndex,
+        TABLE_MARKDOWN
+      )
+      await openMarkdownFixture(orcaPage, context, filePath)
+      const editor = await waitForRichMarkdownEditor(orcaPage)
+
+      await expect(editor.locator('tr')).toHaveCount(4, { timeout: 10_000 })
+      await expect(editor.getByText('keep')).toBeVisible()
+      await expect(editor.getByText('stay')).toBeVisible()
+
+      // ── Tab / Shift-Tab cell navigation ────────────────────────────
+      await editor.getByText('keep').click()
+
+      await orcaPage.keyboard.press('Tab')
+      await expect
+        .poll(async () => selectionCellText(orcaPage), {
+          timeout: 5_000,
+          message: 'Tab should move from keep → a'
+        })
+        .toBe('a')
+
+      // Next Tab lands in the empty body row (no text).
+      await orcaPage.keyboard.press('Tab')
+      await expect
+        .poll(async () => selectionCellText(orcaPage), {
+          timeout: 5_000,
+          message: 'Tab should wrap into the empty body row'
+        })
+        .toBe('')
+
+      await orcaPage.keyboard.press('Shift+Tab')
+      await expect
+        .poll(async () => selectionCellText(orcaPage), {
+          timeout: 5_000,
+          message: 'Shift-Tab should return to previous cell (a)'
+        })
+        .toBe('a')
+
+      // Enter moves down a column, landing in the empty body row.
+      await orcaPage.keyboard.press('Enter')
+      await expect
+        .poll(async () => selectionCellText(orcaPage), {
+          timeout: 5_000,
+          message: 'Enter should move down into the empty body row'
+        })
+        .toBe('')
+
+      // ── Empty-row Backspace deletes the whole row ──────────────────
+      // Enter above already left the caret in the empty body row.
+      await editor.screenshot({
+        path: path.join(SCRATCH_DIR, 'electron-table-row-backspace-before.png')
+      })
+      await orcaPage.screenshot({
+        path: path.join(SCRATCH_DIR, 'electron-table-row-backspace-before-window.png')
+      })
+
+      await orcaPage.keyboard.press('Backspace')
+
+      await expect
+        .poll(async () => tableRowCount(orcaPage), {
+          timeout: 5_000,
+          message: 'Empty body row should be removed after Backspace'
+        })
+        .toBe(3)
+
+      await expect(editor.getByText('keep')).toBeVisible()
+      await expect(editor.getByText('stay')).toBeVisible()
+
+      await editor.screenshot({
+        path: path.join(SCRATCH_DIR, 'electron-table-row-backspace-after.png')
+      })
+      await orcaPage.screenshot({
+        path: path.join(SCRATCH_DIR, 'electron-table-row-backspace-after-window.png')
+      })
+
+      // Hold a beat so the video recording captures the final table state.
+      await orcaPage.waitForTimeout(800)
+    } finally {
+      await cleanupMarkdownFixture(filePath)
+    }
+  })
+})

From d34bbd7917b3afde4c164ee7338dae4bf1e5818a Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Fri, 31 Jul 2026 02:48:07 -0700
Subject: [PATCH 14/23] fix(orchestration): route the legacy coordinator gate
 at the caller's own Run (#11745)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(orchestration): route the legacy gate at the caller's own Run

The retained-legacy-coordinator gate treated an unnamed Run as the adopted
Run, so callers with no relation to it were fenced with legacy_read_only,
and the adopted Run's NULL coordinator made the owner escape hatch
unreachable.

Resolve the caller's bound Run first and keep the adopted Run only as the
unbound fallback, and treat an unclaimed adopted Run as free — the same
rule bindingMatches() already applies 100 lines down.

* refactor(orchestration): pass the open db handle into boundRunId

Co-authored-by: Orca <help@stably.ai>

---------

Co-authored-by: Orca <help@stably.ai>
---
 ...hestration-legacy-coordinator-authority.ts |  23 ++-
 .../orchestration-legacy-run-routing.test.ts  | 146 ++++++++++++++++++
 2 files changed, 166 insertions(+), 3 deletions(-)
 create mode 100644 src/main/runtime/rpc/orchestration-legacy-run-routing.test.ts

diff --git a/src/main/runtime/rpc/orchestration-legacy-coordinator-authority.ts b/src/main/runtime/rpc/orchestration-legacy-coordinator-authority.ts
index a6223ba073a..782460c891b 100644
--- a/src/main/runtime/rpc/orchestration-legacy-coordinator-authority.ts
+++ b/src/main/runtime/rpc/orchestration-legacy-coordinator-authority.ts
@@ -1,4 +1,5 @@
 import type { OrcaRuntimeService, OrchestrationCompatibilityCallerAuthority } from '../orca-runtime'
+import type { OrchestrationDb } from '../orchestration/db'
 import type { LegacyCompatibilityPrincipalRow } from '../orchestration/types'
 import type { LegacyCoordinatorAuthorityProof, RpcRequest } from './core'
 import {
@@ -20,8 +21,12 @@ export class LegacyCoordinatorAuthority {
   ): LegacyCoordinatorAuthorityProof | undefined {
     const db = this.runtime.getOrchestrationDb()
     const adoption = db.getLegacyAdoption()
-    const requestedRun = requestedRunId ?? adoption?.adopted_run_id
-    if (!adoption || requestedRun !== adoption.adopted_run_id) {
+    if (!adoption) {
+      return undefined
+    }
+    // Why: an unnamed Run means the caller's own binding; only an unbound caller can still mean the adopted Run.
+    const requestedRun = requestedRunId ?? boundRunId(db, request) ?? adoption.adopted_run_id
+    if (requestedRun !== adoption.adopted_run_id) {
       return undefined
     }
     const candidate = db.resolveLegacyCoordinatorCandidate({
@@ -31,10 +36,17 @@ export class LegacyCoordinatorAuthority {
     })
     if (!candidate) {
       if (request.orchestrationCompatibilityEvidence) {
+        const run = db.getRun(adoption.adopted_run_id)
+        // Why: an unclaimed adopted Run has no coordinator to fence — same rule as bindingMatches below.
+        if (
+          !run?.coordinator_pane_key &&
+          !db.getLegacyCoordinatorPrincipal(adoption.adopted_run_id)
+        ) {
+          return undefined
+        }
         const caller = this.runtime.verifyOrchestrationCompatibilityCaller(
           request.orchestrationCompatibilityEvidence
         )
-        const run = db.getRun(adoption.adopted_run_id)
         if (
           caller &&
           run?.coordinator_handle === caller.terminalHandle &&
@@ -168,3 +180,8 @@ export class LegacyCoordinatorAuthority {
     )
   }
 }
+
+function boundRunId(db: OrchestrationDb, request: RpcRequest): string | undefined {
+  const paneKey = request.orchestrationCompatibilityEvidence?.paneKey
+  return paneKey ? db.getCurrentRunForPane(paneKey)?.id : undefined
+}
diff --git a/src/main/runtime/rpc/orchestration-legacy-run-routing.test.ts b/src/main/runtime/rpc/orchestration-legacy-run-routing.test.ts
new file mode 100644
index 00000000000..49e2b78d6ae
--- /dev/null
+++ b/src/main/runtime/rpc/orchestration-legacy-run-routing.test.ts
@@ -0,0 +1,146 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import {
+  cleanupLegacyCompatibilityDispatcherHarnesses,
+  COORDINATOR_HANDLE,
+  createHarness,
+  currentEvidence,
+  CURRENT_COORDINATOR_HANDLE,
+  CURRENT_COORDINATOR_PANE,
+  evidence,
+  invoke,
+  request
+} from './orchestration-legacy-compatibility-dispatcher-test-fixture'
+
+afterEach(() => {
+  cleanupLegacyCompatibilityDispatcherHarnesses()
+})
+
+describe('legacy coordinator gate run routing', () => {
+  it.each(['dispatch', 'websocket'] as const)(
+    '%s asks an unbound caller to bind a Run instead of fencing it as a legacy coordinator',
+    async (transport) => {
+      const harness = createHarness()
+
+      const response = await invoke(
+        harness.dispatcher,
+        request(
+          'orchestration.taskCreate',
+          {
+            spec: 'fresh assignment',
+            callerTerminalHandle: CURRENT_COORDINATOR_HANDLE
+          },
+          currentEvidence('coordinator'),
+          `unbound-task-create-${transport}`
+        ),
+        transport
+      )
+
+      expect(response).toMatchObject({
+        ok: false,
+        error: { code: 'run_required' }
+      })
+      expect(harness.db.listTasks({ runId: harness.adoptedRunId })).toHaveLength(1)
+    }
+  )
+
+  it('routes an unnamed Run to the caller binding even when attestation fails', async () => {
+    const harness = createHarness()
+    const run = harness.db.createRun({
+      objective: 'current work',
+      coordinatorHandle: CURRENT_COORDINATOR_HANDLE,
+      coordinatorPaneKey: CURRENT_COORDINATOR_PANE
+    })
+
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.taskCreate',
+        {
+          spec: 'fresh assignment',
+          callerTerminalHandle: CURRENT_COORDINATOR_HANDLE
+        },
+        { ...currentEvidence('coordinator'), launchToken: '' },
+        'unattested-bound-task-create'
+      )
+    )
+
+    expect(response).toMatchObject({
+      ok: true,
+      result: { task: { run_id: run.id, spec: 'fresh assignment' } }
+    })
+  })
+
+  it('lets a current coordinator rebind the unclaimed adopted Run with actionable guidance', async () => {
+    const harness = createHarness()
+
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.runUse',
+        { id: harness.adoptedRunId, from: CURRENT_COORDINATOR_HANDLE },
+        currentEvidence('coordinator'),
+        'unclaimed-adopted-run-use'
+      )
+    )
+
+    expect(response).toMatchObject({
+      ok: false,
+      error: {
+        code: 'consumer_fenced',
+        data: {
+          recoveryCommand: `orca orchestration run-use --id ${harness.adoptedRunId} --takeover-legacy`
+        }
+      }
+    })
+  })
+
+  it('still routes the retained legacy coordinator to the adopted Run without --run', async () => {
+    const harness = createHarness()
+
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.taskCreate',
+        {
+          spec: 'retained assignment',
+          callerTerminalHandle: COORDINATOR_HANDLE
+        },
+        evidence('coordinator'),
+        'retained-adopted-task-create'
+      )
+    )
+
+    expect(response).toMatchObject({
+      ok: true,
+      result: {
+        task: { run_id: harness.adoptedRunId, spec: 'retained assignment' }
+      }
+    })
+  })
+
+  it('still fences a stale legacy coordinator once the adopted Run is claimed', async () => {
+    const harness = createHarness()
+    harness.db.bindRun({
+      runId: harness.adoptedRunId,
+      coordinatorHandle: CURRENT_COORDINATOR_HANDLE,
+      coordinatorPaneKey: CURRENT_COORDINATOR_PANE,
+      takeoverLegacy: true
+    })
+
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.taskCreate',
+        {
+          spec: 'stale assignment',
+          run: harness.adoptedRunId,
+          callerTerminalHandle: COORDINATOR_HANDLE
+        },
+        evidence('coordinator'),
+        'claimed-adopted-task-create'
+      )
+    )
+
+    expect(response).toMatchObject({
+      ok: false,
+      error: { code: 'legacy_read_only' }
+    })
+    expect(harness.db.listTasks({ runId: harness.adoptedRunId })).toHaveLength(1)
+  })
+})

From 60d2493bbb20a923f3adcff0edacfe78fbcddce3 Mon Sep 17 00:00:00 2001
From: Laily <i@laily.net>
Date: Fri, 31 Jul 2026 19:32:23 +0800
Subject: [PATCH 15/23] fix: route server project adds to selected runtime
 (#11346)

* fix: route server project adds to selected runtime

* fix: preserve selected runtime for nested project scans

* fix: retain nested review runtime ownership

* fix: preserve nested runtime owner through completion

* fix: preserve captured add repo owners

* refactor: isolate add repo nested review controller

* test: cover selected runtime project adds

* fix: preserve selected project host ownership

* fix: pin SSH nested import completion

* fix: fence missing SSH repo refreshes

* test: cover selected runtime reconnect routing

* test: register selected runtime project routing gate

* fix: preserve selected host across all project adds

* fix: isolate selected-host project catalogs

* fix: preserve host-qualified workspace identity

* test: expect local folder host identity

* test: preserve host-qualified activation assertions

* fix: fence folder refreshes by host identity

* fix: preserve runtime owner across project refresh events

* test: fence selected-runtime reconnect oracle

* fix(runtime): preserve selected host during session activation

* test(runtime): force same-id paired terminal activation

* chore(reliability): register prior selected-runtime evidence

* test(runtime): seed isolated Git identity

---------

Co-authored-by: OrcaWin <293788423+OrcaWin@users.noreply.github.com>
---
 config/reliability-gates.jsonc                | 180 ++++-
 .../src/components/WorktreeJumpPalette.tsx    |  20 +-
 .../palette-activation-focus-routing.test.ts  |   4 +-
 .../AddProjectFromFolderDialog.test.tsx       |  17 +-
 .../sidebar/AddProjectFromFolderDialog.tsx    |  22 +-
 .../AddRepoDialog.default-checkout.test.ts    |  55 +-
 .../src/components/sidebar/AddRepoDialog.tsx  |  84 +-
 .../AddRepoSteps.default-checkout.test.ts     |  46 +-
 .../src/components/sidebar/AddRepoSteps.tsx   |  33 +-
 .../sidebar/NonGitFolderDialog.test.tsx       | 101 ++-
 .../components/sidebar/NonGitFolderDialog.tsx |  19 +-
 .../WorktreeCard.affiliate-list-mode.test.tsx |   3 +-
 .../src/components/sidebar/WorktreeCard.tsx   |   8 +-
 .../sidebar/add-repo-runtime-owner.ts         |  35 +
 .../sidebar/add-repo-store-upsert.ts          |  43 +-
 .../sidebar/complete-nested-folder-open.ts    |  51 ++
 .../project-added-default-checkout.test.ts    |  48 ++
 .../sidebar/project-added-default-checkout.ts | 120 ++-
 .../sidebar/track-nested-folder-open.ts       |  30 +
 .../use-add-repo-remote-nested-scan.ts        |   8 +-
 .../sidebar/use-complete-git-repo-add.ts      |  26 +-
 .../sidebar/useAddRepoCloneFlow.test.ts       |  27 +-
 .../components/sidebar/useAddRepoCloneFlow.ts |  25 +-
 .../sidebar/useAddRepoLocalFolderFlow.test.ts |  72 +-
 .../sidebar/useAddRepoLocalFolderFlow.ts      |  55 +-
 .../useAddRepoNestedImportFlow.test.ts        |  51 +-
 .../sidebar/useAddRepoNestedImportFlow.ts     | 100 +--
 .../useAddRepoNestedReviewController.ts       |  82 ++
 .../sidebar/useAddRepoNestedReviewState.ts    |  36 +-
 .../sidebar/useAddRepoServerPathFlow.test.ts  |  45 +-
 .../sidebar/useAddRepoServerPathFlow.ts       |  59 +-
 .../useCreateRepo.default-checkout.test.ts    |  20 +-
 .../src/components/sidebar/useCreateRepo.ts   |  53 +-
 .../sidebar/worktree-list-host-filtering.ts   |   8 +-
 .../runtime-project-refresh-scheduler.test.ts |  25 +-
 .../runtime-project-refresh-scheduler.ts      |  42 +
 src/renderer/src/hooks/useIpcEvents.test.ts   |  10 +-
 src/renderer/src/hooks/useIpcEvents.ts        |  71 +-
 .../worktree-change-refresh-queue.test.ts     |  23 +
 .../hooks/worktree-change-refresh-queue.ts    |  34 +-
 .../src/lib/ai-vault-resume-target.ts         |   4 +-
 .../src/lib/direct-ssh-target-scope-types.ts  |   2 +-
 .../src/lib/folder-workspace-connection.ts    |   5 +
 .../src/lib/folder-workspace-runtime-owner.ts |  88 +-
 .../resolved-worktree-execution-host.test.ts  |  21 +
 .../lib/resolved-worktree-execution-host.ts   |  32 +-
 .../src/lib/sidebar-worktree-activation.ts    |  19 +-
 .../workspace-session-host-field-ownership.ts |   1 +
 .../lib/workspace-session-host-persistence.ts |   8 +-
 .../workspace-session-relevant-fields.test.ts |   1 +
 src/renderer/src/lib/workspace-session.ts     |   6 +-
 src/renderer/src/lib/worktree-activation.ts   |  18 +-
 .../src/lib/worktree-operation-route.ts       |  13 +
 .../src/lib/worktree-runtime-owner-index.ts   | 152 +++-
 .../src/lib/worktree-runtime-owner-state.ts   |   7 +-
 .../src/lib/worktree-runtime-owner.test.ts    |  21 +
 .../src/lib/worktree-runtime-owner.ts         |  21 +
 .../src/runtime/web-runtime-session.test.ts   |  33 +-
 .../src/runtime/web-runtime-session.ts        |  11 +-
 src/renderer/src/store/selectors.test.ts      |  27 +
 src/renderer/src/store/selectors.ts           |  39 +-
 .../direct-ssh-terminal-workspace-scope.ts    |   3 +
 ...r-workspace-owner-routed-mutations.test.ts |  49 ++
 .../repos-all-hosts-folder-workspaces.test.ts |   8 +-
 .../src/store/slices/repos-all-hosts.test.ts  |   4 +-
 .../store/slices/repos-project-groups.test.ts |  14 +-
 .../repos-selected-owner-routing.test.ts      | 536 +++++++++++++
 src/renderer/src/store/slices/repos.ts        | 432 +++++++---
 ...ted-host-active-workspace-identity.test.ts | 185 +++++
 src/renderer/src/store/slices/tabs.ts         |   1 +
 src/renderer/src/store/slices/terminals.ts    |   9 +
 .../src/store/slices/worktree-helpers.ts      |  15 +-
 .../src/store/slices/worktrees.test.ts        | 173 ++++
 src/renderer/src/store/slices/worktrees.ts    | 136 +++-
 src/shared/folder-workspace-worktree.ts       |   6 +-
 src/shared/pr-check-status.ts                 |   6 +-
 src/shared/types.ts                           |   3 +
 src/shared/workspace-session-schema.ts        |   7 +
 .../workspace-session-terminal-tab-close.ts   |   1 +
 .../e2e/pr11346-selected-runtime-add.spec.ts  | 757 ++++++++++++++++++
 ...r11346-selected-runtime-identity-oracle.ts | 247 ++++++
 81 files changed, 4292 insertions(+), 620 deletions(-)
 create mode 100644 src/renderer/src/components/sidebar/add-repo-runtime-owner.ts
 create mode 100644 src/renderer/src/components/sidebar/complete-nested-folder-open.ts
 create mode 100644 src/renderer/src/components/sidebar/track-nested-folder-open.ts
 create mode 100644 src/renderer/src/components/sidebar/useAddRepoNestedReviewController.ts
 create mode 100644 src/renderer/src/store/slices/repos-selected-owner-routing.test.ts
 create mode 100644 src/renderer/src/store/slices/selected-host-active-workspace-identity.test.ts
 create mode 100644 tests/e2e/pr11346-selected-runtime-add.spec.ts
 create mode 100644 tests/e2e/pr11346-selected-runtime-identity-oracle.ts

diff --git a/config/reliability-gates.jsonc b/config/reliability-gates.jsonc
index fb86c790432..0dd16bca193 100644
--- a/config/reliability-gates.jsonc
+++ b/config/reliability-gates.jsonc
@@ -2224,6 +2224,7 @@
         "Advanced Active Server setting",
         "saved server Connect and Disconnect",
         "remote workspace navigation",
+        "Add Project host selection, scan, import, and catalog refresh",
         "terminal reveal and create",
         "browser and mobile handoff",
         "app restart"
@@ -2232,12 +2233,16 @@
       "providers": ["local", "remote-runtime", "ssh", "wsl"],
       "coveredPlatforms": ["macos"],
       "coveredProviders": ["local", "remote-runtime", "ssh", "wsl"],
-      "coverageNotes": "Platform-neutral deterministic tests separate the durable Active Server preference from per-client connection, selected-workspace, browser-session, and execution-host routing. The composed regression models Local desktop -> connect/navigate Windows 2 -> reveal a local terminal -> restart. Multi-client browser host overrides, multi-server profile caches, generic settings IPC rejection, local and remote workspace ownership, and restart reset of transient routing are covered. Live desktop UI runs remain uncollected.",
+      "coverageNotes": "Platform-neutral deterministic tests separate the durable Active Server preference from per-client connection, selected-workspace, browser-session, Add Project, and execution-host routing. The composed regression models Local desktop -> connect/navigate Windows 2 -> reveal a local terminal -> restart. Multi-client browser host overrides, multi-server profile caches, generic settings IPC rejection, local and remote workspace ownership, Add Project owner capture and stale-result fencing, host-qualified group/folder/worktree identity, and restart reset of transient routing are covered. A visible macOS Orca desktop server plus a separate paired Electron client proves real Git, plain-folder, Clone, Create, nested import, runtime-switch, disconnect, reconnect, concurrently visible same-ID local/runtime repo/worktree/group/folder rows, reversed catalog order, reversed refresh completion, local-after-runtime catalog refresh routing, and first paired-terminal activation without local fallback; hidden-window parity also passed. Live Linux, Windows, WSL, and SSH Add Project journeys remain uncollected.",
       "motivatingLinks": ["https://github.com/stablyai/orca/pull/9687"],
-      "invariant": "Only an explicit user change in Settings > Remote Orca Servers > Advanced > Active Server may mutate activeRuntimeEnvironmentId. Connecting, pairing, disconnecting, selecting or revealing a workspace or terminal, browser/mobile handoff, remote navigation, and reconnect must use transient or target-owner routing and must never rewrite the durable preference. Generic settings mutation cannot bypass the dedicated preference IPC.",
-      "oracle": "Start with Active Server=Local desktop, connect and navigate Windows 2, then reveal a local terminal and assert it succeeds while the persisted preference remains local before and after restart. Repeat with multiple clients and servers, browser host switches, remote-owned and local-owned workspaces, pairing/connect/disconnect, and generic settings writes. Assert only the dedicated validated preference method changes activeRuntimeEnvironmentId and stale host-operation completions cannot overwrite the newly selected transient host.",
+      "invariant": "Only an explicit user change in Settings > Remote Orca Servers > Advanced > Active Server may mutate activeRuntimeEnvironmentId. Connecting, pairing, disconnecting, selecting or revealing a workspace or terminal, browser/mobile handoff, remote navigation, and reconnect must use transient or target-owner routing and must never rewrite the durable preference. Every Add Project scan, add, import, catalog refresh, and worktree refresh must stay on the host selected when that operation began, even if the durable preference changes or the repo catalog is not hydrated. Generic settings mutation cannot bypass the dedicated preference IPC.",
+      "oracle": "Start with Active Server=Local desktop, connect and navigate Windows 2, then reveal a local terminal and assert it succeeds while the persisted preference remains local before and after restart. Repeat with multiple clients and servers, browser host switches, remote-owned and local-owned workspaces, pairing/connect/disconnect, and generic settings writes. In a separate paired Electron client, select a non-default headed runtime and add a real Git repo, plain folder, clone, created project, and nested repos while switching the preference and disconnecting/reconnecting. Before Git Add, plain-folder Add, Clone, and Create completion, insert a same-ID local repo/worktree decoy; require final activation to remain on the captured runtime. Merge same-ID local/runtime repo, worktree, group, and folder rows, reverse same-host refresh completions, overlap refresh with reconnect, issue ordinary unqualified local refreshes, then create the first paired runtime terminal while the same-ID local/runtime worktrees remain visible. Require only the selected server inventory to change, exact runtime ownership in the client store, preserved host-qualified catalogs, authoritative direct-SSH pruning without runtime sibling loss, visible projects, and zero direct SSH fallback. Assert only the dedicated validated preference method changes activeRuntimeEnvironmentId and stale host-operation completions cannot overwrite the newly selected transient host.",
       "commands": [
-        "pnpm exec vitest run --config config/vitest.config.ts src/main/ipc/settings.test.ts src/main/ipc/runtime-environments.test.ts src/renderer/src/store/slices/settings.test.ts src/renderer/src/store/slices/browser.test.ts src/renderer/src/components/settings/browser-session-host-selection.test.ts src/renderer/src/components/settings/RuntimeEnvironmentsPane.test.ts src/renderer/src/components/status-bar/SshStatusSegment.test.ts src/renderer/src/components/sidebar/use-add-repo-host-selection.test.ts src/renderer/src/hooks/useIpcEvents.test.ts src/renderer/src/web/web-preload-api.test.ts --maxWorkers=1"
+        "pnpm exec vitest run --config config/vitest.config.ts src/main/ipc/settings.test.ts src/main/ipc/runtime-environments.test.ts src/renderer/src/store/slices/settings.test.ts src/renderer/src/store/slices/browser.test.ts src/renderer/src/components/settings/browser-session-host-selection.test.ts src/renderer/src/components/settings/RuntimeEnvironmentsPane.test.ts src/renderer/src/components/status-bar/SshStatusSegment.test.ts src/renderer/src/components/sidebar/use-add-repo-host-selection.test.ts src/renderer/src/hooks/useIpcEvents.test.ts src/renderer/src/web/web-preload-api.test.ts --maxWorkers=1",
+        "pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/components/sidebar/AddProjectFromFolderDialog.test.tsx src/renderer/src/components/sidebar/NonGitFolderDialog.test.tsx src/renderer/src/components/sidebar/AddRepoDialog.default-checkout.test.ts src/renderer/src/components/sidebar/AddRepoSteps.default-checkout.test.ts src/renderer/src/components/sidebar/project-added-default-checkout.test.ts src/renderer/src/components/sidebar/useAddRepoLocalFolderFlow.test.ts src/renderer/src/components/sidebar/useAddRepoNestedImportFlow.test.ts src/renderer/src/components/sidebar/useAddRepoServerPathFlow.test.ts src/renderer/src/components/sidebar/useAddRepoCloneFlow.test.ts src/renderer/src/components/sidebar/useCreateRepo.default-checkout.test.ts src/renderer/src/components/sidebar/worktree-list-host-filtering.test.ts src/renderer/src/lib/resolved-worktree-execution-host.test.ts src/renderer/src/lib/worktree-runtime-owner.test.ts src/renderer/src/store/selectors.test.ts src/renderer/src/store/slices/repos-all-hosts-folder-workspaces.test.ts src/renderer/src/store/slices/repos-project-groups.test.ts src/renderer/src/store/slices/repos-selected-owner-routing.test.ts src/renderer/src/store/slices/selected-host-active-workspace-identity.test.ts src/renderer/src/store/slices/worktrees.test.ts --maxWorkers=1",
+        "pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/components/sidebar/AddProjectFromFolderDialog.test.tsx src/renderer/src/components/sidebar/NonGitFolderDialog.test.tsx src/renderer/src/components/sidebar/AddRepoDialog.default-checkout.test.ts src/renderer/src/components/sidebar/AddRepoSteps.default-checkout.test.ts src/renderer/src/components/sidebar/project-added-default-checkout.test.ts src/renderer/src/components/sidebar/useAddRepoLocalFolderFlow.test.ts src/renderer/src/components/sidebar/useAddRepoNestedImportFlow.test.ts src/renderer/src/components/sidebar/useAddRepoServerPathFlow.test.ts src/renderer/src/components/sidebar/useAddRepoCloneFlow.test.ts src/renderer/src/components/sidebar/useCreateRepo.default-checkout.test.ts src/renderer/src/components/sidebar/worktree-list-host-filtering.test.ts src/renderer/src/lib/resolved-worktree-execution-host.test.ts src/renderer/src/lib/worktree-runtime-owner.test.ts src/renderer/src/store/selectors.test.ts src/renderer/src/store/slices/repos-all-hosts-folder-workspaces.test.ts src/renderer/src/store/slices/repos-project-groups.test.ts src/renderer/src/store/slices/repos-selected-owner-routing.test.ts src/renderer/src/store/slices/selected-host-active-workspace-identity.test.ts src/renderer/src/store/slices/worktrees.test.ts src/renderer/src/runtime/web-runtime-session.test.ts --maxWorkers=1",
+        "pnpm run ensure:electron-runtime && npx playwright test tests/e2e/pr11346-selected-runtime-add.spec.ts --config tests/playwright.config.ts --project electron-headful --workers=1 --reporter=line",
+        "pnpm run ensure:electron-runtime && npx playwright test tests/e2e/pr11346-selected-runtime-add.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1 --reporter=line"
       ],
       "testFiles": [
         "src/main/ipc/settings.test.ts",
@@ -2249,7 +2254,28 @@
         "src/renderer/src/components/status-bar/SshStatusSegment.test.ts",
         "src/renderer/src/components/sidebar/use-add-repo-host-selection.test.ts",
         "src/renderer/src/hooks/useIpcEvents.test.ts",
-        "src/renderer/src/web/web-preload-api.test.ts"
+        "src/renderer/src/web/web-preload-api.test.ts",
+        "src/renderer/src/components/sidebar/AddProjectFromFolderDialog.test.tsx",
+        "src/renderer/src/components/sidebar/NonGitFolderDialog.test.tsx",
+        "src/renderer/src/components/sidebar/AddRepoDialog.default-checkout.test.ts",
+        "src/renderer/src/components/sidebar/AddRepoSteps.default-checkout.test.ts",
+        "src/renderer/src/components/sidebar/project-added-default-checkout.test.ts",
+        "src/renderer/src/components/sidebar/useAddRepoLocalFolderFlow.test.ts",
+        "src/renderer/src/components/sidebar/useAddRepoNestedImportFlow.test.ts",
+        "src/renderer/src/components/sidebar/useAddRepoServerPathFlow.test.ts",
+        "src/renderer/src/components/sidebar/useAddRepoCloneFlow.test.ts",
+        "src/renderer/src/components/sidebar/useCreateRepo.default-checkout.test.ts",
+        "src/renderer/src/components/sidebar/worktree-list-host-filtering.test.ts",
+        "src/renderer/src/lib/resolved-worktree-execution-host.test.ts",
+        "src/renderer/src/lib/worktree-runtime-owner.test.ts",
+        "src/renderer/src/store/selectors.test.ts",
+        "src/renderer/src/store/slices/repos-all-hosts-folder-workspaces.test.ts",
+        "src/renderer/src/store/slices/repos-project-groups.test.ts",
+        "src/renderer/src/store/slices/repos-selected-owner-routing.test.ts",
+        "src/renderer/src/store/slices/selected-host-active-workspace-identity.test.ts",
+        "src/renderer/src/store/slices/worktrees.test.ts",
+        "src/renderer/src/runtime/web-runtime-session.test.ts",
+        "tests/e2e/pr11346-selected-runtime-add.spec.ts"
       ],
       "assertionRefs": [
         {
@@ -2292,6 +2318,73 @@
             "generic web settings writes cannot mutate Active Server",
             "the dedicated web preference setter rejects unknown server identities without corrupting the saved choice"
           ]
+        },
+        {
+          "file": "src/renderer/src/components/sidebar/useAddRepoCloneFlow.test.ts",
+          "assertions": [
+            "stamps a Clone response with the captured runtime or SSH owner before store upsert and worktree refresh",
+            "preserves same-ID repository siblings that belong to different execution hosts"
+          ]
+        },
+        {
+          "file": "src/renderer/src/components/sidebar/useCreateRepo.default-checkout.test.ts",
+          "assertions": [
+            "stamps Create responses with the captured runtime or SSH owner before store upsert and Git or folder worktree refresh"
+          ]
+        },
+        {
+          "file": "src/renderer/src/store/slices/repos-selected-owner-routing.test.ts",
+          "assertions": [
+            "keeps same-ID local, direct-SSH, and runtime group/folder rows partitioned by execution host",
+            "drops reversed same-host and pre-reconnect group/folder responses without pruning newer catalogs",
+            "prunes deleted direct-SSH rows from the desktop-owned catalog without erasing same-ID runtime siblings",
+            "keeps explicit runtime groups and folders after a later ordinary local refresh",
+            "keeps a selected-runtime import refresh across an overlapping local refresh",
+            "pins selected SSH scans and cancellation to local IPC over an ambient runtime"
+          ]
+        },
+        {
+          "file": "src/renderer/src/components/sidebar/project-added-default-checkout.test.ts",
+          "assertions": [
+            "filters loaded, detected, refreshed, and activated default checkouts by the captured execution host when repo IDs collide"
+          ]
+        },
+        {
+          "file": "src/renderer/src/store/slices/worktrees.test.ts",
+          "assertions": [
+            "honors an explicit runtime owner before the repo catalog is hydrated",
+            "honors an explicit SSH owner before the repo catalog is hydrated",
+            "rejects a missing-owner SSH result after the repo catalog changes",
+            "rejects a missing-owner SSH result after the provider reconnects"
+          ]
+        },
+        {
+          "file": "src/renderer/src/store/slices/selected-host-active-workspace-identity.test.ts",
+          "assertions": [
+            "selects the runtime worktree when exact repo/worktree IDs collide in local-first or reversed order",
+            "keeps exact-ID folder/group activation on the explicitly selected runtime without local fallback"
+          ]
+        },
+        {
+          "file": "src/renderer/src/store/selectors.test.ts",
+          "assertions": [
+            "does not fall back to a same-ID local repo when the selected runtime row is unavailable"
+          ]
+        },
+        {
+          "file": "src/renderer/src/runtime/web-runtime-session.test.ts",
+          "assertions": [
+            "terminal, browser, and staged-browser selection preserve the explicit runtime execution host when local and runtime worktree IDs collide"
+          ]
+        },
+        {
+          "file": "tests/e2e/pr11346-selected-runtime-add.spec.ts",
+          "assertions": [
+            "routes Git Add, plain-folder Add, Clone, Create, and nested import to a selected non-default headed runtime while exact-ID local siblings remain visible and cannot capture final activation @headful",
+            "preserves same-ID runtime group/folder/worktree catalogs across reversed order, local refresh, switch, disconnect, and reconnect-overlap completion",
+            "keeps every expanded selected-runtime Add Project path in hidden-window desktop parity",
+            "creates the first paired runtime terminal while same-ID local/runtime worktrees remain visible without clearing the selected runtime owner"
+          ]
         }
       ],
       "evidenceRuns": [
@@ -2303,34 +2396,91 @@
           "result": "passed",
           "durationSeconds": 6.55,
           "summary": "Ten files and 282 tests passed, including the composed Local -> Windows 2 navigation -> local reveal -> restart regression, dedicated-only preference persistence, removed transient-host fallback, multi-client browser routing, late host-operation suppression, and web pairing/preference separation."
+        },
+        {
+          "date": "2026-07-30",
+          "runner": "local",
+          "platform": "macos",
+          "command": "pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/components/sidebar/AddProjectFromFolderDialog.test.tsx src/renderer/src/components/sidebar/NonGitFolderDialog.test.tsx src/renderer/src/components/sidebar/AddRepoDialog.default-checkout.test.ts src/renderer/src/components/sidebar/AddRepoSteps.default-checkout.test.ts src/renderer/src/components/sidebar/project-added-default-checkout.test.ts src/renderer/src/components/sidebar/useAddRepoLocalFolderFlow.test.ts src/renderer/src/components/sidebar/useAddRepoNestedImportFlow.test.ts src/renderer/src/components/sidebar/useAddRepoServerPathFlow.test.ts src/renderer/src/components/sidebar/useAddRepoCloneFlow.test.ts src/renderer/src/components/sidebar/useCreateRepo.default-checkout.test.ts src/renderer/src/components/sidebar/worktree-list-host-filtering.test.ts src/renderer/src/lib/resolved-worktree-execution-host.test.ts src/renderer/src/lib/worktree-runtime-owner.test.ts src/renderer/src/store/selectors.test.ts src/renderer/src/store/slices/repos-all-hosts-folder-workspaces.test.ts src/renderer/src/store/slices/repos-project-groups.test.ts src/renderer/src/store/slices/repos-selected-owner-routing.test.ts src/renderer/src/store/slices/selected-host-active-workspace-identity.test.ts src/renderer/src/store/slices/worktrees.test.ts --maxWorkers=1",
+          "result": "passed",
+          "durationSeconds": 8.77,
+          "summary": "Nineteen files and 386 tests passed after rebasing onto 94cf2f1422f30fc309cb47c5e864a831d516fa8b, including exact-ID repo/worktree/group/folder host identity in both catalog orders, fail-closed active-repo selection when a runtime row is unavailable, selected runtime and SSH owner capture through final Add/Clone/Create/folder activation, direct-SSH authoritative pruning, reversed catalog responses, reconnect generation fencing, local-after-runtime isolation, and missing-catalog worktree routing."
+        },
+        {
+          "date": "2026-07-30",
+          "runner": "local",
+          "platform": "macos",
+          "command": "pnpm run ensure:electron-runtime && npx playwright test tests/e2e/pr11346-selected-runtime-add.spec.ts --config tests/playwright.config.ts --project electron-headful --workers=1 --reporter=line",
+          "result": "passed",
+          "durationSeconds": 23,
+          "summary": "A visible isolated Orca desktop server and separate paired Electron client added one real Git repo, one plain folder, one clone, one created project, and two nested repos to the selected non-default runtime across preference switches and disconnect/reconnect. Exact-ID local/runtime repo, worktree, group, and folder rows remained concurrently visible in local-first and reversed order without capturing final activation. Server inventory, active host identity, rendered rows, local-client exclusion, preserved post-reconnect catalogs, and zero direct SSH fallback agreed. Runtime switch/Git/folder/Clone/Create/reconnect/nested-import measurements were 307/1667/2932/1247/1321/259/1319 ms."
+        },
+        {
+          "date": "2026-07-30",
+          "runner": "local",
+          "platform": "macos",
+          "command": "pnpm run ensure:electron-runtime && npx playwright test tests/e2e/pr11346-selected-runtime-add.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1 --reporter=line",
+          "result": "passed",
+          "durationSeconds": 66,
+          "summary": "The hidden-window desktop-server parity journey passed with exact-ID Add/Clone/Create activation, selected-runtime inventory, reversed catalog order, reconnect overlap, ownership, local exclusion, and host-qualified catalog-preservation assertions. Runtime switch/Git/folder/Clone/Create/reconnect/nested-import measurements were 59/1770/4330/1375/2137/279/1945 ms."
+        },
+        {
+          "date": "2026-07-31",
+          "runner": "local",
+          "platform": "macos",
+          "command": "pnpm exec vitest run --config config/vitest.config.ts src/renderer/src/components/sidebar/AddProjectFromFolderDialog.test.tsx src/renderer/src/components/sidebar/NonGitFolderDialog.test.tsx src/renderer/src/components/sidebar/AddRepoDialog.default-checkout.test.ts src/renderer/src/components/sidebar/AddRepoSteps.default-checkout.test.ts src/renderer/src/components/sidebar/project-added-default-checkout.test.ts src/renderer/src/components/sidebar/useAddRepoLocalFolderFlow.test.ts src/renderer/src/components/sidebar/useAddRepoNestedImportFlow.test.ts src/renderer/src/components/sidebar/useAddRepoServerPathFlow.test.ts src/renderer/src/components/sidebar/useAddRepoCloneFlow.test.ts src/renderer/src/components/sidebar/useCreateRepo.default-checkout.test.ts src/renderer/src/components/sidebar/worktree-list-host-filtering.test.ts src/renderer/src/lib/resolved-worktree-execution-host.test.ts src/renderer/src/lib/worktree-runtime-owner.test.ts src/renderer/src/store/selectors.test.ts src/renderer/src/store/slices/repos-all-hosts-folder-workspaces.test.ts src/renderer/src/store/slices/repos-project-groups.test.ts src/renderer/src/store/slices/repos-selected-owner-routing.test.ts src/renderer/src/store/slices/selected-host-active-workspace-identity.test.ts src/renderer/src/store/slices/worktrees.test.ts src/renderer/src/runtime/web-runtime-session.test.ts --maxWorkers=1",
+          "result": "passed",
+          "durationSeconds": 7.1,
+          "summary": "Twenty files and 430 tests passed on current main integration, including explicit runtime-owner preservation for terminal and browser session activation."
+        },
+        {
+          "date": "2026-07-31",
+          "runner": "local",
+          "platform": "macos",
+          "command": "pnpm run ensure:electron-runtime && npx playwright test tests/e2e/pr11346-selected-runtime-add.spec.ts --config tests/playwright.config.ts --project electron-headful --workers=1 --reporter=line",
+          "result": "passed",
+          "durationSeconds": 19.9,
+          "summary": "The visible headed server and separate paired client passed the strengthened same-ID terminal-activation oracle with a disposable runtime Git identity. Runtime switch/Git/folder/Clone/Create/reconnect/nested-import measurements were 43/1513/3841/1200/790/202/1312 ms."
+        },
+        {
+          "date": "2026-07-31",
+          "runner": "local",
+          "platform": "macos",
+          "command": "pnpm run ensure:electron-runtime && npx playwright test tests/e2e/pr11346-selected-runtime-add.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1 --reporter=line",
+          "result": "passed",
+          "durationSeconds": 19.7,
+          "summary": "The hidden-window server and separate paired client passed the strengthened same-ID terminal-activation oracle with a disposable runtime Git identity. Runtime switch/Git/folder/Clone/Create/reconnect/nested-import measurements were 51/1502/3843/880/939/200/1359 ms."
         }
       ],
       "runtimeBudget": {
-        "p95Seconds": 20,
-        "scope": "focused persistence and routing contract tests"
+        "p95Seconds": 180,
+        "scope": "focused persistence/routing contracts plus isolated paired Electron journeys"
       },
       "flakeHistory": {
         "status": "unknown",
-        "evidence": "New deterministic gate with no soak history."
+        "evidence": "Deterministic contracts and the final visible plus hidden-window paired Electron runs passed locally. During expansion, attempts exposed three harness-only assumptions: exact project labels did not allow path disambiguation, clicking the inner host label raced cmdk layout, and a disposable CI runtime had no Git author identity for Create. The oracle now targets the host command item, accepts the rendered disambiguated label, seeds only its isolated runtime home with a test Git identity, and explicitly creates a first paired terminal while same-ID local/runtime worktrees remain present. CI soak history is not yet available."
       },
       "redGreenEvidence": {
-        "status": "partial",
-        "evidence": "The user-observed local terminal reveal failure and unintended Active Server switch are encoded by deterministic routing and persistence tests; a saved intentional-break artifact is not yet attached."
+        "status": "complete",
+        "evidence": "The byte-identical focused oracle (SHA-256 6de18c140a86801460e58f52287e27a58b97f1576f9f387fa82e1bd4eb378f7b) fails 2/3 on review baseline aa6f945001a5f78a07663c854fabb95c55d8b40b and on the r5-disabled parent e21f4ca58e: local-first lookup returns /local/repo and folder activation has no runtime host. It passes 3/3 on the candidate. Main later advanced to 94cf2f1422f30fc309cb47c5e864a831d516fa8b without changing any of the candidate's 68 files or the focused oracle production boundary; the rebased disabled parent f247d961cab15237bc7fcf0598fe76007f78ec7c has the same stable patch ID as e21f4ca58e. The final paired spec and fixture have SHA-256 bd6d9014d1bed2715397bcd2121d5d7e01792347b13ff14778ccf608bf98789c and d1d78a82f868e2f3152777550825c0ca2d4dc3cba5c6de548e066d2931751fc7. With the final runtime-session owner fix disabled, the focused session test fails 3/43 and the byte-identical hidden paired oracle deterministically creates the host terminal but reports null active client owner while same-ID local/runtime worktrees remain. The integrated candidate passes the same focused test and both headed/hidden paired oracles with exact runtime ownership, server inventory, local exclusion, preserved catalogs, visible rows, and zero direct SSH fallback. Earlier Active Server preference paths retain deterministic coverage but do not yet have a saved intentional-break artifact."
       },
       "performanceBudget": {
-        "required": false,
-        "evidence": "Preference writes are explicit user actions; transient routing adds no polling and uses existing host/worktree indexes."
+        "required": true,
+        "evidence": "Preference writes are explicit user actions; transient routing adds no polling or provider fanout and retains one authoritative worktree refresh per completed add. Host-qualified owner indexes are WeakMap-cached and do not add subprocesses or network calls. The final headed journey measured 43 ms for three preference switches, 1,513 ms for Git add, 3,841 ms for folder add, 1,200 ms for Clone, 790 ms for Create with controlled exact-ID completion gates, 202 ms for disconnect/reconnect with overlapping catalog refreshes, and 1,312 ms for nested import. The final session-activation fix adds one execution-host string conversion per explicit terminal/browser activation and no provider call, scan, timer, or retry. Existing Zustand selector fan-out evidence remained 0 render invalidations across 5,000,000 selector runs."
       },
       "promotionCriteria": [
         "Run the focused gate in soak across macOS, Linux, and Windows.",
         "Attach a live Windows Local -> Windows 2 -> local reveal -> restart artifact.",
-        "Attach saved red/green evidence for generic settings mutation and transient connection routing."
+        "Attach saved red/green evidence for generic settings mutation and transient connection routing.",
+        "Run the paired Add Project journey on Linux and native Windows, plus live SSH and WSL hosts."
       ],
       "knownGaps": [
         "The exact journey is deterministic contract coverage, not a packaged Windows UI automation run.",
-        "Browser/mobile handoff is covered through transient routing state and preload contracts, not a live phone browser session."
+        "Browser/mobile handoff is covered through transient routing state and preload contracts, not a live phone browser session.",
+        "The paired Add Project journey is macOS-only; native Windows was unavailable.",
+        "SSH and WSL Add Project ownership is deterministic store/controller coverage, not a live host journey."
       ],
-      "demotionRule": "Demote or block release if any non-Advanced path mutates Active Server, if local reveal depends on the durable default instead of workspace ownership, or if transient host state survives restart."
+      "demotionRule": "Demote or block release if any non-Advanced path mutates Active Server, if local reveal or Add Project depends on the durable default instead of captured workspace/host ownership, if an Add Project operation reaches a different host after it begins, or if transient host state survives restart."
     },
     {
       "id": "terminal-geometry.visible-convergence",
diff --git a/src/renderer/src/components/WorktreeJumpPalette.tsx b/src/renderer/src/components/WorktreeJumpPalette.tsx
index efe91e4e7bc..9eee43a6a4b 100644
--- a/src/renderer/src/components/WorktreeJumpPalette.tsx
+++ b/src/renderer/src/components/WorktreeJumpPalette.tsx
@@ -1267,22 +1267,25 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
   )
 
   const handleSelectWorktree = useCallback(
-    (worktreeId: string) => {
-      const worktree = findWorktreeById(useAppStore.getState().worktreesByRepo, worktreeId)
-      if (!worktree) {
+    (worktree: Worktree) => {
+      const current = useAppStore.getState().getKnownWorktreeById(worktree.id, worktree.hostId)
+      if (!current) {
         toast.error(
           translate('auto.components.WorktreeJumpPalette.2c38630a01', 'Workspace no longer exists')
         )
         return
       }
-      const activation = activateAndRevealWorktree(worktreeId)
+      const activation = activateAndRevealWorktree(
+        worktree.id,
+        worktree.hostId ? { executionHostId: worktree.hostId } : {}
+      )
       recordFeatureInteraction('cmd-j-workspace-open')
       skipRestoreFocusRef.current = true
       closeModal()
       setSelectedItemId('')
       // Why: #9939 — the unscoped fallback grabs the first terminal in the document, which is
       // often the worktree we just left, now hidden. Focus the destination's own tab instead.
-      if (!queueWorkspaceActivationTerminalFocus(worktreeId, activation)) {
+      if (!queueWorkspaceActivationTerminalFocus(worktree.id, activation)) {
         focusFallbackSurface()
       }
     },
@@ -1304,7 +1307,10 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
       }
       // Why: capture page info before activateAndRevealWorktree mutates store state — a later findBrowserSelection would be unreliable.
       const { worktree, workspace, page } = selection
-      const activated = activateAndRevealWorktree(worktree.id)
+      const activated = activateAndRevealWorktree(
+        worktree.id,
+        worktree.hostId ? { executionHostId: worktree.hostId } : {}
+      )
       if (!activated) {
         toast.error(
           translate('auto.components.WorktreeJumpPalette.2c38630a01', 'Workspace no longer exists')
@@ -1470,7 +1476,7 @@ export default function WorktreeJumpPalette(): React.JSX.Element | null {
   const handleSelectItem = useCallback(
     (item: PaletteItem) => {
       if (item.type === 'worktree') {
-        handleSelectWorktree(item.worktree.id)
+        handleSelectWorktree(item.worktree)
       } else if (item.type === 'project-target') {
         handleSelectProjectTarget(item.result)
       } else if (item.type === 'browser-page') {
diff --git a/src/renderer/src/components/cmd-j/palette-activation-focus-routing.test.ts b/src/renderer/src/components/cmd-j/palette-activation-focus-routing.test.ts
index c63948e7c89..afe3b97da70 100644
--- a/src/renderer/src/components/cmd-j/palette-activation-focus-routing.test.ts
+++ b/src/renderer/src/components/cmd-j/palette-activation-focus-routing.test.ts
@@ -24,10 +24,10 @@ describe('Cmd+J activation focus routing (#9939)', () => {
       'const handleSelectBrowserPage'
     )
 
-    expect(handler).toContain('queueWorkspaceActivationTerminalFocus(worktreeId, activation)')
+    expect(handler).toContain('queueWorkspaceActivationTerminalFocus(worktree.id, activation)')
     // The fallback must be reachable only when the helper declines the destination.
     expect(handler).toMatch(
-      /if \(!queueWorkspaceActivationTerminalFocus\(worktreeId, activation\)\) \{\s*focusFallbackSurface\(\)\s*\}/
+      /if \(!queueWorkspaceActivationTerminalFocus\(worktree\.id, activation\)\) \{\s*focusFallbackSurface\(\)\s*\}/
     )
     // An unconditional fallback is the exact shape of the original bug, so the only bare call
     // allowed is the guarded one inside the if-block above.
diff --git a/src/renderer/src/components/sidebar/AddProjectFromFolderDialog.test.tsx b/src/renderer/src/components/sidebar/AddProjectFromFolderDialog.test.tsx
index 56d32c5aef8..ddff8f75246 100644
--- a/src/renderer/src/components/sidebar/AddProjectFromFolderDialog.test.tsx
+++ b/src/renderer/src/components/sidebar/AddProjectFromFolderDialog.test.tsx
@@ -152,12 +152,14 @@ describe('AddProjectFromFolderDialog', () => {
 
     expect(mocks.state.addRepoPath).toHaveBeenCalledWith('/projects/child')
     expect(mocks.state.fetchWorktrees).toHaveBeenCalledWith(repo.id, {
-      requireAuthoritative: true
+      requireAuthoritative: true,
+      executionHostId: 'local'
     })
     expect(mocks.finishProjectAddWithDefaultCheckout).toHaveBeenCalledWith({
       repoId: repo.id,
       source: 'local_folder_picker',
       selectedPath: '/projects/child',
+      executionHostId: 'local',
       closeModal: mocks.state.closeModal,
       setHideDefaultBranchWorkspace: mocks.state.setHideDefaultBranchWorkspace
     })
@@ -200,14 +202,16 @@ describe('AddProjectFromFolderDialog', () => {
       connectionId: 'ssh-target-1',
       remotePath: '/srv/projects/child'
     })
-    expect(mocks.state.repos).toEqual([repo])
+    expect(mocks.state.repos).toEqual([{ ...repo, executionHostId: 'ssh:ssh-target-1' }])
     expect(mocks.state.fetchWorktrees).toHaveBeenCalledWith(repo.id, {
-      requireAuthoritative: true
+      requireAuthoritative: true,
+      executionHostId: 'ssh:ssh-target-1'
     })
     expect(mocks.finishProjectAddWithDefaultCheckout).toHaveBeenCalledWith({
       repoId: repo.id,
       source: 'ssh_remote_path',
       selectedPath: '/srv/projects/child',
+      executionHostId: 'ssh:ssh-target-1',
       closeModal: mocks.state.closeModal,
       setHideDefaultBranchWorkspace: mocks.state.setHideDefaultBranchWorkspace
     })
@@ -226,12 +230,14 @@ describe('AddProjectFromFolderDialog', () => {
     await clickAddProject()
 
     expect(mocks.state.fetchWorktrees).toHaveBeenCalledWith(repo.id, {
-      requireAuthoritative: true
+      requireAuthoritative: true,
+      executionHostId: 'local'
     })
     expect(mocks.finishProjectAddWithDefaultCheckout).toHaveBeenCalledWith({
       repoId: repo.id,
       source: 'local_folder_picker',
       selectedPath: '/projects/child',
+      executionHostId: 'local',
       closeModal: mocks.state.closeModal,
       setHideDefaultBranchWorkspace: mocks.state.setHideDefaultBranchWorkspace
     })
@@ -252,7 +258,8 @@ describe('AddProjectFromFolderDialog', () => {
     const addPromise = getButton('Add Project').onClick?.()
     await Promise.resolve()
     expect(mocks.state.fetchWorktrees).toHaveBeenCalledWith(repo.id, {
-      requireAuthoritative: true
+      requireAuthoritative: true,
+      executionHostId: 'local'
     })
     getButton('Cancel').onClick?.()
     resolveRefresh(true)
diff --git a/src/renderer/src/components/sidebar/AddProjectFromFolderDialog.tsx b/src/renderer/src/components/sidebar/AddProjectFromFolderDialog.tsx
index 483476e9c83..78a0f2b02c1 100644
--- a/src/renderer/src/components/sidebar/AddProjectFromFolderDialog.tsx
+++ b/src/renderer/src/components/sidebar/AddProjectFromFolderDialog.tsx
@@ -16,6 +16,8 @@ import type { Repo } from '../../../../shared/types'
 import { isGitRepoKind } from '../../../../shared/repo-kind'
 import { finishProjectAddWithDefaultCheckout } from './project-added-default-checkout'
 import { translate } from '@/i18n/i18n'
+import { upsertAddedRepoWithProjectHostSetup } from './add-repo-store-upsert'
+import { worktreeRefreshOptions } from './add-repo-runtime-owner'
 
 const NON_GIT_REPO_ERROR = 'Not a valid git repository'
 
@@ -74,16 +76,12 @@ const AddProjectFromFolderDialog = React.memo(function AddProjectFromFolderDialo
         if ('error' in result) {
           throw new Error(result.error)
         }
-        repo = result.repo
-        const state = useAppStore.getState()
-        const existingIdx = state.repos.findIndex((r) => r.id === repo?.id)
-        if (existingIdx !== -1) {
-          state.clearOrcaHookTrustForRepo(repo.id)
-          const updated = [...state.repos]
-          updated[existingIdx] = repo
-          useAppStore.setState({ repos: updated })
-        } else {
-          useAppStore.setState({ repos: [...state.repos, repo] })
+        const upserted = upsertAddedRepoWithProjectHostSetup(result.repo, {
+          sshConnectionId: connectionId
+        })
+        repo = upserted.repo
+        if (upserted.alreadyPresent) {
+          useAppStore.getState().clearOrcaHookTrustForRepo(repo.id)
         }
         if (!mountedRef.current || gen !== addGenRef.current) {
           return
@@ -111,7 +109,8 @@ const AddProjectFromFolderDialog = React.memo(function AddProjectFromFolderDialo
       }
       // Why: after the repo is already added, a non-authoritative refresh
       // should still close onto the project row instead of trapping the user.
-      await fetchWorktrees(repo.id, { requireAuthoritative: true })
+      const ownerOptions = worktreeRefreshOptions(null, connectionId)
+      await fetchWorktrees(repo.id, ownerOptions)
       if (!mountedRef.current || gen !== addGenRef.current) {
         return
       }
@@ -119,6 +118,7 @@ const AddProjectFromFolderDialog = React.memo(function AddProjectFromFolderDialo
         repoId: repo.id,
         source: connectionId ? 'ssh_remote_path' : 'local_folder_picker',
         selectedPath: folderPath,
+        executionHostId: ownerOptions.executionHostId,
         closeModal,
         setHideDefaultBranchWorkspace
       })
diff --git a/src/renderer/src/components/sidebar/AddRepoDialog.default-checkout.test.ts b/src/renderer/src/components/sidebar/AddRepoDialog.default-checkout.test.ts
index 5ae2c36668d..edcfa01f12b 100644
--- a/src/renderer/src/components/sidebar/AddRepoDialog.default-checkout.test.ts
+++ b/src/renderer/src/components/sidebar/AddRepoDialog.default-checkout.test.ts
@@ -1,44 +1,27 @@
-import { readFileSync } from 'node:fs'
-import { join } from 'node:path'
 import { describe, expect, it } from 'vitest'
+import {
+  LOCAL_EXECUTION_HOST_ID,
+  toRuntimeExecutionHostId
+} from '../../../../shared/execution-host'
+import { worktreeRefreshOptions } from './add-repo-runtime-owner'
 
-const ADD_REPO_DIALOG_PATH = join(import.meta.dirname, 'AddRepoDialog.tsx')
-const ADD_REPO_FLOW_PATHS = [
-  ADD_REPO_DIALOG_PATH,
-  join(import.meta.dirname, 'AddRepoSteps.tsx'),
-  join(import.meta.dirname, 'useAddRepoCloneFlow.ts'),
-  join(import.meta.dirname, 'useAddRepoLocalFolderFlow.ts'),
-  join(import.meta.dirname, 'useAddRepoServerPathFlow.ts'),
-  join(import.meta.dirname, 'useAddRepoNestedImportFlow.ts')
-]
-
-function readAddRepoFlowSource(): string {
-  return ADD_REPO_FLOW_PATHS.map((path) => readFileSync(path, 'utf8')).join('\n')
-}
-
-describe('AddRepoDialog default-checkout handoff', () => {
-  it('does not retain the removed setup-step routing branch', () => {
-    const source = readFileSync(ADD_REPO_DIALOG_PATH, 'utf8')
-
-    expect(source).not.toContain("setStep('setup')")
-    expect(source).not.toContain('<SetupStep')
-    expect(source).not.toContain('AddRepoSetupStep')
+describe('AddRepo completion owner routing', () => {
+  it('routes an explicitly local completion to the local host', () => {
+    expect(worktreeRefreshOptions(null)).toEqual({
+      requireAuthoritative: true,
+      executionHostId: LOCAL_EXECUTION_HOST_ID
+    })
   })
 
-  it('requests authoritative worktree refresh before Git handoff paths complete', () => {
-    const source = readAddRepoFlowSource()
-
-    expect(source.match(/requireAuthoritative: true/g)?.length ?? 0).toBeGreaterThanOrEqual(4)
-    expect(source).toContain("onGitRepoReady(repo.id, 'clone_url')")
-    expect(source).toContain("onGitRepoReady(repo.id, 'runtime_server_path')")
-    expect(source).toContain('onGitRepoReady(repo.id, source)')
+  it('routes an explicitly runtime completion to its captured runtime', () => {
+    expect(worktreeRefreshOptions('runtime-1')).toEqual({
+      requireAuthoritative: true,
+      executionHostId: toRuntimeExecutionHostId('runtime-1')
+    })
   })
 
-  it('does not fail nested import completion on non-authoritative refresh', () => {
-    const source = readAddRepoFlowSource()
-
-    expect(source).not.toContain('Could not refresh project worktrees. Try again.')
-    expect(source).toContain('await fetchWorktrees(projectId, { requireAuthoritative: true })')
-    expect(source).toContain('await onGitRepoReady(repo.id, source)')
+  it('leaves an absent owner distinguishable from explicit local ownership', () => {
+    expect(worktreeRefreshOptions(undefined)).toEqual({ requireAuthoritative: true })
+    expect(worktreeRefreshOptions(undefined)).not.toEqual(worktreeRefreshOptions(null))
   })
 })
diff --git a/src/renderer/src/components/sidebar/AddRepoDialog.tsx b/src/renderer/src/components/sidebar/AddRepoDialog.tsx
index be41bb17534..54148a0d4a3 100644
--- a/src/renderer/src/components/sidebar/AddRepoDialog.tsx
+++ b/src/renderer/src/components/sidebar/AddRepoDialog.tsx
@@ -4,24 +4,22 @@ import { useRemoteRepo } from './AddRepoSteps'
 import { useCreateRepo } from './useCreateRepo'
 import { AddRepoDialogStepContent } from './AddRepoDialogStepContent'
 import type { AddRepoDialogStep } from './add-repo-dialog-types'
-import { useAddRepoNestedReviewState } from './useAddRepoNestedReviewState'
 import { useAddRepoCloneFlow } from './useAddRepoCloneFlow'
 import { useAddRepoLocalFolderFlow } from './useAddRepoLocalFolderFlow'
 import { useAddRepoServerPathFlow } from './useAddRepoServerPathFlow'
-import { useAddRepoNestedImportFlow } from './useAddRepoNestedImportFlow'
 import { useAddRepoHostSelection } from './use-add-repo-host-selection'
 import { useCompleteGitRepoAdd } from './use-complete-git-repo-add'
 import { useCreateProjectDefaults } from './useCreateProjectDefaults'
 import { useAddRepoHostChangeReset } from './use-add-repo-host-change-reset'
 import { AddRepoDialogChrome } from './AddRepoDialogChrome'
 import { AddRepoHostSelectorSlot } from './AddRepoHostSelectorSlot'
-import { useAddRepoRemoteNestedScan } from './use-add-repo-remote-nested-scan'
+import { useAddRepoNestedReviewController } from './useAddRepoNestedReviewController'
 import {
   useAddRepoHostedController,
   type AddRepoDialogHostedController
 } from './use-add-repo-hosted-controller'
 
-const AddRepoDialog = React.memo(function AddRepoDialog({
+export default React.memo(function AddRepoDialog({
   hosted
 }: {
   hosted?: AddRepoDialogHostedController
@@ -42,25 +40,25 @@ const AddRepoDialog = React.memo(function AddRepoDialog({
   const settings = useAppStore((s) => s.settings)
   const { closeModal, closeForFolderHandoff, finishProjectAdd, handleOpenSshSettings } =
     useAddRepoHostedController(hosted)
+  const [step, setStep] = useState<AddRepoDialogStep>('add')
+  const [isAdding, setIsAdding] = useState(false)
+  const [addProjectBusyLabel, setAddProjectBusyLabel] = useState<string | null>(null)
   const completeGitRepoAdd = useCompleteGitRepoAdd({
     closeModal,
     setHideDefaultBranchWorkspace,
     finishProjectAdd
   })
-
-  const [step, setStep] = useState<AddRepoDialogStep>('add')
-  const [isAdding, setIsAdding] = useState(false)
-  const [addProjectBusyLabel, setAddProjectBusyLabel] = useState<string | null>(null)
+  const hostSelection = useAddRepoHostSelection({ isOpen, setStep })
+  const selectedRuntimeEnvironmentId =
+    hostSelection.selectedParsedHost?.kind === 'runtime'
+      ? hostSelection.selectedParsedHost.environmentId
+      : null
   const {
     nestedScan,
     nestedSelectedPaths,
     nestedGroupName,
-    nestedConnectionId,
-    nestedAttemptId,
-    nestedRuntimeKind,
     nestedScanInProgress,
     nestedScanId,
-    nestedImportScanId,
     setNestedSelectedPaths,
     setNestedGroupName,
     setNestedScanInProgress,
@@ -68,22 +66,24 @@ const AddRepoDialog = React.memo(function AddRepoDialog({
     showNestedRepoReview,
     setActiveNestedScanId,
     handleStopNestedScan,
-    resetNestedRepoReviewState
-  } = useAddRepoNestedReviewState({
-    activeRuntimeEnvironmentId: settings?.activeRuntimeEnvironmentId,
+    resetNestedRepoReviewState,
+    showRemoteNestedRepoReview,
+    trackRemoteNestedScanResult,
+    handleImportNestedRepos,
+    handleOpenNestedRootFolder,
+    resetNestedImportFlow,
+    trackNestedBackAction
+  } = useAddRepoNestedReviewController({
+    reviewRuntimeEnvironmentId: selectedRuntimeEnvironmentId,
     cancelNestedRepoScan,
+    closeModal: closeForFolderHandoff,
+    fetchWorktrees,
+    importNestedRepos,
+    onGitRepoReady: completeGitRepoAdd,
+    setIsAdding,
+    activeRuntimeEnvironmentId: selectedRuntimeEnvironmentId,
     setStep
   })
-
-  const hostSelection = useAddRepoHostSelection({ isOpen, setStep })
-  const selectedRuntimeEnvironmentId =
-    hostSelection.selectedParsedHost?.kind === 'runtime'
-      ? hostSelection.selectedParsedHost.environmentId
-      : null
-  const { showRemoteNestedRepoReview, trackRemoteNestedScanResult } = useAddRepoRemoteNestedScan({
-    setActiveNestedScanId,
-    showNestedRepoReview
-  })
   const {
     sshTargets,
     selectedTargetId,
@@ -104,12 +104,11 @@ const AddRepoDialog = React.memo(function AddRepoDialog({
     setStep,
     // Why: useRemoteRepo closes only for the non-git → confirm-dialog handoff.
     closeForFolderHandoff,
-    (repoId) => completeGitRepoAdd(repoId, 'ssh_remote_path'),
+    (repoId, executionHostId) => completeGitRepoAdd(repoId, 'ssh_remote_path', executionHostId),
     scanNestedRepos,
     showRemoteNestedRepoReview,
     trackRemoteNestedScanResult
   )
-
   const {
     createName,
     createParent,
@@ -123,9 +122,8 @@ const AddRepoDialog = React.memo(function AddRepoDialog({
     handleCreate
   } = useCreateRepo(
     fetchWorktrees,
-    // Why: useCreateRepo closes only after a folder (non-git) create.
     closeForFolderHandoff,
-    (repoId) => completeGitRepoAdd(repoId, 'create_project'),
+    (repoId, executionHostId) => completeGitRepoAdd(repoId, 'create_project', executionHostId),
     {
       hostId: hostSelection.selectedHostId,
       runtimeEnvironmentId: selectedRuntimeEnvironmentId,
@@ -195,6 +193,7 @@ const AddRepoDialog = React.memo(function AddRepoDialog({
     handleAddServerPath
   } = useAddRepoServerPathFlow({
     addRepoPath,
+    activeRuntimeEnvironmentId: selectedRuntimeEnvironmentId,
     // Why: closes only after a folder add, which activates the folder workspace.
     closeModal: closeForFolderHandoff,
     fetchWorktrees,
@@ -206,29 +205,6 @@ const AddRepoDialog = React.memo(function AddRepoDialog({
     onGitRepoReady: completeGitRepoAdd,
     setAddProjectBusyLabel
   })
-  const {
-    handleImportNestedRepos,
-    handleOpenNestedRootFolder,
-    resetNestedImportFlow,
-    trackNestedBackAction
-  } = useAddRepoNestedImportFlow({
-    nestedAttemptId,
-    nestedScan,
-    nestedSelectedPaths,
-    nestedRuntimeKind,
-    nestedConnectionId,
-    nestedGroupName,
-    nestedImportScanId,
-    activeRuntimeEnvironmentId: selectedRuntimeEnvironmentId,
-    // Why: open-as-folder outcomes navigate; git imports finish via
-    // completeGitRepoAdd instead.
-    closeModal: closeForFolderHandoff,
-    fetchWorktrees,
-    importNestedRepos,
-    getNestedRepoRuntimeKind,
-    onGitRepoReady: completeGitRepoAdd,
-    setIsAdding
-  })
 
   const resetState = useCallback(() => {
     // Why: kill the git clone process if one is running, so backing out
@@ -259,6 +235,7 @@ const AddRepoDialog = React.memo(function AddRepoDialog({
   const resetHostScopedState = useCallback(() => {
     setIsAdding(false)
     setAddProjectBusyLabel(null)
+    resetLocalFolderFlow()
     resetServerPathFlow()
     resetCloneFlow()
     resetCreateDefaultState()
@@ -269,6 +246,7 @@ const AddRepoDialog = React.memo(function AddRepoDialog({
     resetCreateDefaultState,
     resetCreateState,
     resetRemoteState,
+    resetLocalFolderFlow,
     resetServerPathFlow
   ])
 
@@ -420,5 +398,3 @@ const AddRepoDialog = React.memo(function AddRepoDialog({
     </AddRepoDialogChrome>
   )
 })
-
-export default AddRepoDialog
diff --git a/src/renderer/src/components/sidebar/AddRepoSteps.default-checkout.test.ts b/src/renderer/src/components/sidebar/AddRepoSteps.default-checkout.test.ts
index db874556e9d..fc8829474ee 100644
--- a/src/renderer/src/components/sidebar/AddRepoSteps.default-checkout.test.ts
+++ b/src/renderer/src/components/sidebar/AddRepoSteps.default-checkout.test.ts
@@ -135,7 +135,12 @@ describe('useRemoteRepo default-checkout handoff', () => {
       remotePath: '/srv/repo'
     })
     expect(mocks.fetchWorktrees).toHaveBeenCalledWith(repo.id, {
-      requireAuthoritative: true
+      requireAuthoritative: true,
+      executionHostId: 'ssh:ssh-1'
+    })
+    expect(mocks.storeState.repos).toContainEqual({
+      ...repo,
+      executionHostId: 'ssh:ssh-1'
     })
     expect(mocks.storeState.projects).toEqual(
       expect.arrayContaining([expect.objectContaining({ sourceRepoIds: [repo.id] })])
@@ -143,7 +148,7 @@ describe('useRemoteRepo default-checkout handoff', () => {
     expect(mocks.storeState.projectHostSetups).toEqual(
       expect.arrayContaining([expect.objectContaining({ repoId: repo.id, path: repo.path })])
     )
-    expect(mocks.onGitRepoReady).toHaveBeenCalledWith(repo.id)
+    expect(mocks.onGitRepoReady).toHaveBeenCalledWith(repo.id, 'ssh:ssh-1')
   })
 
   it('continues to completion when refresh is not authoritative after remote add', async () => {
@@ -162,9 +167,10 @@ describe('useRemoteRepo default-checkout handoff', () => {
     await result.handleAddRemoteRepo()
 
     expect(mocks.fetchWorktrees).toHaveBeenCalledWith(repo.id, {
-      requireAuthoritative: true
+      requireAuthoritative: true,
+      executionHostId: 'ssh:ssh-1'
     })
-    expect(mocks.onGitRepoReady).toHaveBeenCalledWith(repo.id)
+    expect(mocks.onGitRepoReady).toHaveBeenCalledWith(repo.id, 'ssh:ssh-1')
     expect(mocks.stateSetters[3]).not.toHaveBeenCalledWith(
       'Could not refresh project worktrees. Try again.'
     )
@@ -188,4 +194,36 @@ describe('useRemoteRepo default-checkout handoff', () => {
     expect(mocks.getState).toHaveBeenCalledWith({ targetId: 'ssh-2' })
     expect(mocks.stateSetters[1]).toHaveBeenCalledWith('ssh-2')
   })
+
+  it('pins SSH nested scans and cancellation to the local provider', async () => {
+    const scanNestedRepos = vi.fn().mockResolvedValue(null)
+    mocks.addRemote.mockResolvedValue({ repo: makeRepo() })
+    mocks.fetchWorktrees.mockResolvedValue(true)
+    const { useRemoteRepo } = await import('./AddRepoSteps')
+
+    const result = useRemoteRepo(
+      mocks.fetchWorktrees,
+      vi.fn(),
+      vi.fn(),
+      mocks.onGitRepoReady,
+      scanNestedRepos
+    )
+    await result.handleAddRemoteRepo()
+
+    expect(scanNestedRepos).toHaveBeenCalledWith(
+      '/srv/repo',
+      'ssh-1',
+      expect.objectContaining({ runtimeEnvironmentId: null })
+    )
+
+    mocks.stateIndex = 0
+    mocks.stateValues = [[], 'ssh-1', '/srv/repo', null, false, 'scan-ssh']
+    const active = useRemoteRepo(mocks.fetchWorktrees, vi.fn(), vi.fn())
+    active.stopRemoteNestedScan()
+    active.resetRemoteState()
+
+    expect(mocks.storeState.cancelNestedRepoScan).toHaveBeenCalledWith('scan-ssh', {
+      runtimeEnvironmentId: null
+    })
+  })
 })
diff --git a/src/renderer/src/components/sidebar/AddRepoSteps.tsx b/src/renderer/src/components/sidebar/AddRepoSteps.tsx
index 5ab96be88ca..0acdaa888b1 100644
--- a/src/renderer/src/components/sidebar/AddRepoSteps.tsx
+++ b/src/renderer/src/components/sidebar/AddRepoSteps.tsx
@@ -8,21 +8,27 @@ import { createNestedRepoTelemetryAttemptId } from '../../../../shared/nested-re
 import { translate } from '@/i18n/i18n'
 import { extractIpcErrorMessage } from '@/lib/ipc-error'
 import { upsertAddedRepoWithProjectHostSetup } from './add-repo-store-upsert'
+import { worktreeRefreshOptions } from './add-repo-runtime-owner'
+import type { ExecutionHostId } from '../../../../shared/execution-host'
 
 // ── SSH host project hook ───────────────────────────────────────────
 
 export function useRemoteRepo(
   fetchWorktrees: (
     repoId: string,
-    options?: { requireAuthoritative?: boolean }
+    options?: { requireAuthoritative?: boolean; executionHostId?: ExecutionHostId }
   ) => Promise<unknown>,
   setStep: (step: 'add' | 'clone' | 'remote' | 'create' | 'nested') => void,
   closeModal: () => void,
-  onGitRepoReady?: (repoId: string) => void | Promise<void>,
+  onGitRepoReady?: (repoId: string, executionHostId?: ExecutionHostId) => void | Promise<void>,
   scanNestedRepos?: (
     path: string,
     connectionId?: string,
-    controls?: { scanId?: string; onProgress?: (scan: NestedRepoScanResult) => void }
+    controls?: {
+      scanId?: string
+      onProgress?: (scan: NestedRepoScanResult) => void
+      runtimeEnvironmentId?: string | null
+    }
   ) => Promise<NestedRepoScanResult | null>,
   showNestedRepoReview?: (
     scan: NestedRepoScanResult,
@@ -52,7 +58,7 @@ export function useRemoteRepo(
     setRemoteError(null)
     setIsAddingRemote(false)
     if (remoteNestedScanId) {
-      void cancelNestedRepoScan(remoteNestedScanId)
+      void cancelNestedRepoScan(remoteNestedScanId, { runtimeEnvironmentId: null })
     }
     setRemoteNestedScanId(null)
   }, [cancelNestedRepoScan, remoteNestedScanId])
@@ -61,7 +67,7 @@ export function useRemoteRepo(
     if (!remoteNestedScanId) {
       return
     }
-    void cancelNestedRepoScan(remoteNestedScanId)
+    void cancelNestedRepoScan(remoteNestedScanId, { runtimeEnvironmentId: null })
   }, [cancelNestedRepoScan, remoteNestedScanId])
 
   const handleOpenRemoteStep = useCallback(
@@ -146,6 +152,7 @@ export function useRemoteRepo(
       setRemoteNestedScanId(scanId)
       const scan = await scanNestedRepos?.(trimmedRemotePath, selectedTargetId, {
         scanId,
+        runtimeEnvironmentId: null,
         onProgress: (progressScan) => {
           if (
             gen !== remoteGenRef.current ||
@@ -182,14 +189,13 @@ export function useRemoteRepo(
       if ('error' in result) {
         throw new Error(result.error)
       }
-      const repo = result.repo
+      const { alreadyPresent, repo } = upsertAddedRepoWithProjectHostSetup(result.repo, {
+        sshConnectionId: selectedTargetId
+      })
 
-      const state = useAppStore.getState()
-      const existingIdx = state.repos.findIndex((r) => r.id === repo.id)
-      if (existingIdx !== -1) {
-        state.clearOrcaHookTrustForRepo(repo.id)
+      if (alreadyPresent) {
+        useAppStore.getState().clearOrcaHookTrustForRepo(repo.id)
       }
-      upsertAddedRepoWithProjectHostSetup(repo)
 
       if (!mountedRef.current || gen !== remoteGenRef.current) {
         return
@@ -200,11 +206,12 @@ export function useRemoteRepo(
       )
       // Why: the repo is already persisted here; if SSH refresh is temporarily
       // non-authoritative, finish onto the project row instead of stranding the dialog.
-      await fetchWorktrees(repo.id, { requireAuthoritative: true })
+      const ownerOptions = worktreeRefreshOptions(undefined, selectedTargetId)
+      await fetchWorktrees(repo.id, ownerOptions)
       if (!mountedRef.current || gen !== remoteGenRef.current) {
         return
       }
-      await onGitRepoReady?.(repo.id)
+      await onGitRepoReady?.(repo.id, ownerOptions.executionHostId)
     } catch (err) {
       const message = extractIpcErrorMessage(err, String(err))
       if (message.includes('Not a valid git repository')) {
diff --git a/src/renderer/src/components/sidebar/NonGitFolderDialog.test.tsx b/src/renderer/src/components/sidebar/NonGitFolderDialog.test.tsx
index a6f7bbff33b..a392374762d 100644
--- a/src/renderer/src/components/sidebar/NonGitFolderDialog.test.tsx
+++ b/src/renderer/src/components/sidebar/NonGitFolderDialog.test.tsx
@@ -1,6 +1,7 @@
 import { renderToStaticMarkup } from 'react-dom/server'
 import type * as ReactModule from 'react'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { Repo, Worktree } from '../../../../shared/types'
 
 type ButtonCapture = {
   label: string
@@ -17,8 +18,17 @@ const mocks = vi.hoisted(() => ({
     } as Record<string, unknown>,
     closeModal: vi.fn(),
     addNonGitFolder: vi.fn(),
-    runtimeEnvironments: [{ id: 'env-1', name: 'Remote Mac' }]
-  }
+    runtimeEnvironments: [{ id: 'env-1', name: 'Remote Mac' }],
+    repos: [] as Repo[],
+    projects: [],
+    projectHostSetups: [],
+    worktreesByRepo: {} as Record<string, Worktree[]>,
+    fetchWorktrees: vi.fn(),
+    settings: {}
+  },
+  addRemote: vi.fn(),
+  onboardingGet: vi.fn(),
+  activateAndRevealWorktree: vi.fn()
 }))
 
 function textContent(node: ReactModule.ReactNode): string {
@@ -74,11 +84,34 @@ vi.mock('sonner', () => ({
 }))
 
 vi.mock('@/lib/worktree-activation', () => ({
-  activateAndRevealWorktree: vi.fn()
+  activateAndRevealWorktree: mocks.activateAndRevealWorktree
 }))
 
 import NonGitFolderDialog from './NonGitFolderDialog'
 
+function makeWorktree(id: string, path: string, hostId: Worktree['hostId']): Worktree {
+  return {
+    id,
+    repoId: 'shared-repo',
+    path,
+    hostId,
+    displayName: 'Folder',
+    comment: '',
+    linkedIssue: null,
+    linkedPR: null,
+    linkedLinearIssue: null,
+    isArchived: false,
+    isUnread: false,
+    isPinned: false,
+    sortOrder: 0,
+    lastActivityAt: 0,
+    head: '',
+    branch: '',
+    isBare: false,
+    isMainWorktree: true
+  }
+}
+
 describe('NonGitFolderDialog', () => {
   beforeEach(() => {
     vi.clearAllMocks()
@@ -89,6 +122,18 @@ describe('NonGitFolderDialog', () => {
       runtimeEnvironmentId: 'env-1'
     }
     mocks.state.runtimeEnvironments = [{ id: 'env-1', name: 'Remote Mac' }]
+    mocks.state.repos = []
+    mocks.state.projects = []
+    mocks.state.projectHostSetups = []
+    mocks.state.worktreesByRepo = {}
+    mocks.state.fetchWorktrees.mockResolvedValue(true)
+    mocks.onboardingGet.mockResolvedValue(null)
+    vi.stubGlobal('window', {
+      api: {
+        repos: { addRemote: mocks.addRemote },
+        onboarding: { get: mocks.onboardingGet }
+      }
+    })
   })
 
   it('shows the checked host in the folder confirmation', () => {
@@ -109,4 +154,54 @@ describe('NonGitFolderDialog', () => {
     })
     expect(mocks.state.closeModal).toHaveBeenCalled()
   })
+
+  it('activates only the selected SSH folder when repo IDs collide', async () => {
+    const repo: Repo = {
+      id: 'shared-repo',
+      path: '/srv/non-git',
+      displayName: 'SSH folder',
+      badgeColor: '#111',
+      addedAt: 1,
+      kind: 'folder',
+      connectionId: 'ssh-1'
+    }
+    const localWorktree = makeWorktree('shared-repo::/local/non-git', '/local/non-git', 'local')
+    const sshWorktree = makeWorktree('shared-repo::/srv/non-git', '/srv/non-git', 'ssh:ssh-1')
+    mocks.state.modalData = {
+      folderPath: '/srv/non-git',
+      connectionId: 'ssh-1'
+    }
+    mocks.state.repos = [
+      {
+        ...repo,
+        path: '/local/non-git',
+        connectionId: null,
+        executionHostId: 'local'
+      }
+    ]
+    mocks.addRemote.mockResolvedValue({ repo })
+    mocks.state.fetchWorktrees.mockImplementation(async () => {
+      mocks.state.worktreesByRepo = { [repo.id]: [localWorktree, sshWorktree] }
+      return true
+    })
+    renderToStaticMarkup(<NonGitFolderDialog />)
+
+    const button = mocks.buttons.find((entry) => entry.label.includes('Open as Folder'))
+    button?.onClick?.()
+
+    await vi.waitFor(() =>
+      expect(mocks.activateAndRevealWorktree).toHaveBeenCalledWith(sshWorktree.id, {
+        sidebarRevealBehavior: 'auto',
+        executionHostId: 'ssh:ssh-1'
+      })
+    )
+    expect(mocks.state.fetchWorktrees).toHaveBeenCalledWith(repo.id, {
+      requireAuthoritative: true,
+      executionHostId: 'ssh:ssh-1'
+    })
+    expect(mocks.activateAndRevealWorktree).not.toHaveBeenCalledWith(
+      localWorktree.id,
+      expect.anything()
+    )
+  })
 })
diff --git a/src/renderer/src/components/sidebar/NonGitFolderDialog.tsx b/src/renderer/src/components/sidebar/NonGitFolderDialog.tsx
index 5ec3354ec22..8cc5ed91d69 100644
--- a/src/renderer/src/components/sidebar/NonGitFolderDialog.tsx
+++ b/src/renderer/src/components/sidebar/NonGitFolderDialog.tsx
@@ -14,6 +14,8 @@ import { activateAndRevealWorktree } from '@/lib/worktree-activation'
 import { buildDismissedOnboardingFolderAgentStartup } from '@/lib/onboarding-folder-agent-startup'
 import { markOnboardingProjectAdded } from '@/lib/onboarding-project-checklist'
 import { translate } from '@/i18n/i18n'
+import { upsertAddedRepoWithProjectHostSetup } from './add-repo-store-upsert'
+import { worktreeRefreshOptions } from './add-repo-runtime-owner'
 
 const NonGitFolderDialog = React.memo(function NonGitFolderDialog() {
   const activeModal = useAppStore((s) => s.activeModal)
@@ -60,19 +62,23 @@ const NonGitFolderDialog = React.memo(function NonGitFolderDialog() {
           if ('error' in result) {
             throw new Error(result.error)
           }
-          const repo = result.repo
+          const { repo } = upsertAddedRepoWithProjectHostSetup(result.repo, {
+            sshConnectionId: connectionId
+          })
           const state = useAppStore.getState()
           const hadProjectBeforeAdd = stateBeforeAdd.repos.length > 0
-          if (!state.repos.some((r) => r.id === repo.id)) {
-            useAppStore.setState({ repos: [...state.repos, repo] })
-          }
           await markOnboardingProjectAdded('addedFolder')
-          await state.fetchWorktrees(repo.id)
+          const ownerOptions = worktreeRefreshOptions(undefined, connectionId)
+          await state.fetchWorktrees(repo.id, ownerOptions)
           // Why: mirror the local non-git folder flow — without this the
           // dialog closes and the UI shows no visible change, making the
           // add feel like a no-op. Activating the synthetic folder
           // worktree reveals it in the sidebar and opens the workspace.
-          const folderWorktree = useAppStore.getState().worktreesByRepo[repo.id]?.[0]
+          const folderWorktree = useAppStore
+            .getState()
+            .worktreesByRepo[repo.id]?.find(
+              (worktree) => worktree.hostId === ownerOptions.executionHostId
+            )
           if (folderWorktree) {
             const onboarding = await window.api.onboarding.get().catch(() => null)
             // Why: SSH users can hit this dialog from Add Project after
@@ -84,6 +90,7 @@ const NonGitFolderDialog = React.memo(function NonGitFolderDialog() {
             )
             activateAndRevealWorktree(folderWorktree.id, {
               sidebarRevealBehavior: 'auto',
+              executionHostId: ownerOptions.executionHostId,
               ...(startup ? { startup } : {})
             })
           }
diff --git a/src/renderer/src/components/sidebar/WorktreeCard.affiliate-list-mode.test.tsx b/src/renderer/src/components/sidebar/WorktreeCard.affiliate-list-mode.test.tsx
index 31e29c83984..1f15663a5ee 100644
--- a/src/renderer/src/components/sidebar/WorktreeCard.affiliate-list-mode.test.tsx
+++ b/src/renderer/src/components/sidebar/WorktreeCard.affiliate-list-mode.test.tsx
@@ -206,7 +206,8 @@ describe('WorktreeCard affiliate list mode', () => {
     })
 
     expect(testDoubles.activateWorktreeFromSidebar).toHaveBeenCalledWith(
-      'repo-1::/repo/worktrees/affiliate'
+      'repo-1::/repo/worktrees/affiliate',
+      'local'
     )
   })
 
diff --git a/src/renderer/src/components/sidebar/WorktreeCard.tsx b/src/renderer/src/components/sidebar/WorktreeCard.tsx
index 2dfd73a211c..9cc437fc513 100644
--- a/src/renderer/src/components/sidebar/WorktreeCard.tsx
+++ b/src/renderer/src/components/sidebar/WorktreeCard.tsx
@@ -84,6 +84,7 @@ import { translate } from '@/i18n/i18n'
 import { recordRendererCrashBreadcrumb } from '@/lib/crash-diagnostics'
 import { folderWorkspaceKey, parseWorkspaceKey } from '../../../../shared/workspace-scope'
 import {
+  getRepoExecutionHostId,
   isRuntimeOwnedSshTargetId,
   parseExecutionHostId,
   toRuntimeExecutionHostId
@@ -872,7 +873,10 @@ const WorktreeCard = React.memo(function WorktreeCard({
         sshDisconnected: isSshDisconnected
       })
       onImmediateActivate?.(worktree.id, activationRowKey)
-      void activateWorktreeFromSidebar(worktree.id)
+      void activateWorktreeFromSidebar(
+        worktree.id,
+        worktree.hostId ?? (repo ? getRepoExecutionHostId(repo) : undefined)
+      )
       // Why: a deliberate card click warrants the blocking reconnect prompt; skip it when a terminal already shows the overlay.
       if (isSshDisconnected && !activeViewIsTerminal) {
         setShowDisconnectedDialog(true)
@@ -883,6 +887,8 @@ const WorktreeCard = React.memo(function WorktreeCard({
       affiliateListMode,
       worktree.id,
       worktree.repoId,
+      worktree.hostId,
+      repo,
       isActive,
       isDeleting,
       activationRowKey,
diff --git a/src/renderer/src/components/sidebar/add-repo-runtime-owner.ts b/src/renderer/src/components/sidebar/add-repo-runtime-owner.ts
new file mode 100644
index 00000000000..3bcc06d4a35
--- /dev/null
+++ b/src/renderer/src/components/sidebar/add-repo-runtime-owner.ts
@@ -0,0 +1,35 @@
+import {
+  LOCAL_EXECUTION_HOST_ID,
+  toRuntimeExecutionHostId,
+  toSshExecutionHostId,
+  type ExecutionHostId
+} from '../../../../shared/execution-host'
+
+export type CapturedRuntimeOwner = string | null | undefined
+
+export function capturedAddRepoExecutionHostId(
+  owner: CapturedRuntimeOwner,
+  sshConnectionId?: string | null
+): ExecutionHostId | undefined {
+  return sshConnectionId
+    ? toSshExecutionHostId(sshConnectionId)
+    : owner !== undefined
+      ? owner
+        ? toRuntimeExecutionHostId(owner)
+        : LOCAL_EXECUTION_HOST_ID
+      : undefined
+}
+
+export function worktreeRefreshOptions(
+  owner: CapturedRuntimeOwner,
+  sshConnectionId?: string | null
+): {
+  requireAuthoritative: true
+  executionHostId?: ExecutionHostId
+} {
+  const executionHostId = capturedAddRepoExecutionHostId(owner, sshConnectionId)
+  return {
+    requireAuthoritative: true,
+    ...(executionHostId ? { executionHostId } : {})
+  }
+}
diff --git a/src/renderer/src/components/sidebar/add-repo-store-upsert.ts b/src/renderer/src/components/sidebar/add-repo-store-upsert.ts
index 664d5e3e93e..1593b3cda1c 100644
--- a/src/renderer/src/components/sidebar/add-repo-store-upsert.ts
+++ b/src/renderer/src/components/sidebar/add-repo-store-upsert.ts
@@ -1,12 +1,46 @@
 import { projectHostSetupProjectionFromRepos } from '../../../../shared/project-host-setup-projection'
+import {
+  LOCAL_EXECUTION_HOST_ID,
+  toRuntimeExecutionHostId,
+  toSshExecutionHostId
+} from '../../../../shared/execution-host'
 import type { Repo } from '../../../../shared/types'
 import { useAppStore } from '@/store'
+import { getRepoHostIdentity } from '@/store/slices/repo-host-identity'
 
-export function upsertAddedRepoWithProjectHostSetup(repo: Repo): void {
+type AddedRepoOwner = {
+  runtimeEnvironmentId?: string | null
+  sshConnectionId?: string | null
+}
+
+function repoWithCapturedOwner(repo: Repo, owner: AddedRepoOwner): Repo {
+  const sshConnectionId = owner.sshConnectionId?.trim()
+  if (sshConnectionId) {
+    return { ...repo, executionHostId: toSshExecutionHostId(sshConnectionId) }
+  }
+  if (owner.runtimeEnvironmentId !== undefined) {
+    const runtimeEnvironmentId = owner.runtimeEnvironmentId?.trim()
+    return {
+      ...repo,
+      executionHostId: runtimeEnvironmentId
+        ? toRuntimeExecutionHostId(runtimeEnvironmentId)
+        : LOCAL_EXECUTION_HOST_ID
+    }
+  }
+  return repo
+}
+
+export function upsertAddedRepoWithProjectHostSetup(
+  repo: Repo,
+  owner: AddedRepoOwner = {}
+): { alreadyPresent: boolean; repo: Repo } {
   const state = useAppStore.getState()
-  const repos = state.repos.some((entry) => entry.id === repo.id)
-    ? state.repos.map((entry) => (entry.id === repo.id ? repo : entry))
-    : [...state.repos, repo]
+  const ownedRepo = repoWithCapturedOwner(repo, owner)
+  const repoIdentity = getRepoHostIdentity(ownedRepo)
+  const alreadyPresent = state.repos.some((entry) => getRepoHostIdentity(entry) === repoIdentity)
+  const repos = alreadyPresent
+    ? state.repos.map((entry) => (getRepoHostIdentity(entry) === repoIdentity ? ownedRepo : entry))
+    : [...state.repos, ownedRepo]
   const projection = projectHostSetupProjectionFromRepos(repos)
 
   // Why: these Add Project flows call IPC directly, bypassing the repo slice
@@ -16,4 +50,5 @@ export function upsertAddedRepoWithProjectHostSetup(repo: Repo): void {
     projects: projection.projects,
     projectHostSetups: projection.setups
   })
+  return { alreadyPresent, repo: ownedRepo }
 }
diff --git a/src/renderer/src/components/sidebar/complete-nested-folder-open.ts b/src/renderer/src/components/sidebar/complete-nested-folder-open.ts
new file mode 100644
index 00000000000..329027b6af2
--- /dev/null
+++ b/src/renderer/src/components/sidebar/complete-nested-folder-open.ts
@@ -0,0 +1,51 @@
+import { toast } from 'sonner'
+import { useAppStore } from '@/store'
+import type { NestedRepoScanResult } from '../../../../shared/types'
+import type { CapturedRuntimeOwner } from './add-repo-runtime-owner'
+import { trackNestedFolderOpen } from './track-nested-folder-open'
+
+export async function completeNestedFolderOpen(args: {
+  scan: NestedRepoScanResult
+  generation: number
+  currentGeneration: () => number
+  attemptId: string | null
+  runtimeKind: Parameters<typeof trackNestedFolderOpen>[0]['runtimeKind']
+  connectionId: string | null
+  selectedCount: number
+  getRuntimeKind: Parameters<typeof trackNestedFolderOpen>[0]['getRuntimeKind']
+  owner: CapturedRuntimeOwner
+  closeModal: () => void
+  setIsAdding: (value: boolean) => void
+}): Promise<void> {
+  trackNestedFolderOpen(args)
+  args.setIsAdding(true)
+  try {
+    const state = useAppStore.getState()
+    if (args.connectionId) {
+      args.closeModal()
+      state.openModal('confirm-non-git-folder', {
+        folderPath: args.scan.selectedPath,
+        connectionId: args.connectionId,
+        runtimeEnvironmentId: args.owner
+      })
+      return
+    }
+    const repo = await state.addNonGitFolder(args.scan.selectedPath, {
+      runtimeEnvironmentId: args.owner ?? null
+    })
+    if (args.generation !== args.currentGeneration()) {
+      return
+    }
+    if (repo) {
+      args.closeModal()
+    }
+  } catch (err) {
+    if (args.generation === args.currentGeneration()) {
+      toast.error(err instanceof Error ? err.message : String(err))
+    }
+  } finally {
+    if (args.generation === args.currentGeneration()) {
+      args.setIsAdding(false)
+    }
+  }
+}
diff --git a/src/renderer/src/components/sidebar/project-added-default-checkout.test.ts b/src/renderer/src/components/sidebar/project-added-default-checkout.test.ts
index d4a2831f25a..0f5ad7cfebb 100644
--- a/src/renderer/src/components/sidebar/project-added-default-checkout.test.ts
+++ b/src/renderer/src/components/sidebar/project-added-default-checkout.test.ts
@@ -3,6 +3,7 @@ import { getDefaultOnboardingState } from '../../../../shared/constants'
 import type {
   DetectedWorktree,
   DetectedWorktreeListResult,
+  Repo,
   Worktree
 } from '../../../../shared/types'
 import {
@@ -17,6 +18,7 @@ const mocks = vi.hoisted(() => ({
     filterRepoIds: [] as string[],
     showActiveOnly: false,
     hideDefaultBranchWorkspace: false,
+    repos: [] as Repo[],
     worktreesByRepo: {} as Record<string, Worktree[]>,
     detectedWorktreesByRepo: {} as Record<string, DetectedWorktreeListResult>,
     setActiveRepo: vi.fn(),
@@ -125,6 +127,7 @@ describe('finishProjectAddWithDefaultCheckout', () => {
     mocks.state.filterRepoIds = []
     mocks.state.showActiveOnly = false
     mocks.state.hideDefaultBranchWorkspace = false
+    mocks.state.repos = []
     mocks.state.worktreesByRepo = {}
     mocks.state.detectedWorktreesByRepo = {}
     mocks.state.updateRepo.mockResolvedValue(true)
@@ -173,6 +176,51 @@ describe('finishProjectAddWithDefaultCheckout', () => {
     expect(mocks.activateAndRevealWorktree).toHaveBeenCalledWith('repo-1::/repo')
   })
 
+  it('activates only the captured host default checkout when repo IDs collide', async () => {
+    const localMain = makeWorktree({
+      id: 'repo-1::same-id',
+      path: '/local/repo',
+      hostId: 'local'
+    })
+    const runtimeMain = makeWorktree({
+      id: 'repo-1::same-id',
+      path: '/runtime/repo',
+      hostId: 'runtime:env-1'
+    })
+    mocks.state.repos = [
+      {
+        id: 'repo-1',
+        path: '/local/repo',
+        displayName: 'local',
+        badgeColor: '#111',
+        addedAt: 1,
+        executionHostId: 'local'
+      },
+      {
+        id: 'repo-1',
+        path: '/runtime/repo',
+        displayName: 'runtime',
+        badgeColor: '#222',
+        addedAt: 2,
+        executionHostId: 'runtime:env-1'
+      }
+    ]
+    mocks.state.worktreesByRepo = {
+      'repo-1': [localMain, runtimeMain]
+    }
+
+    await openProjectDefaultCheckout({
+      repoId: 'repo-1',
+      source: 'clone_url',
+      executionHostId: 'runtime:env-1',
+      setHideDefaultBranchWorkspace: vi.fn()
+    })
+
+    expect(mocks.activateAndRevealWorktree).toHaveBeenCalledWith(runtimeMain.id, {
+      executionHostId: 'runtime:env-1'
+    })
+  })
+
   it('passes a contained selected path through as the initial terminal cwd', async () => {
     mocks.state.worktreesByRepo = {
       'repo-1': [makeWorktree()]
diff --git a/src/renderer/src/components/sidebar/project-added-default-checkout.ts b/src/renderer/src/components/sidebar/project-added-default-checkout.ts
index b30ca0bb24d..0c7fc74f7d6 100644
--- a/src/renderer/src/components/sidebar/project-added-default-checkout.ts
+++ b/src/renderer/src/components/sidebar/project-added-default-checkout.ts
@@ -9,6 +9,7 @@ import type { DetectedWorktreeListResult, Worktree } from '../../../../shared/ty
 import { relativePathInsideRoot } from '../../../../shared/cross-platform-path'
 import { markOnboardingProjectAdded } from '@/lib/onboarding-project-checklist'
 import { finalizeImportedRepoAfterSkip } from './add-repo-skip-finalization'
+import type { ExecutionHostId } from '../../../../shared/execution-host'
 
 type DefaultCheckoutHandoffReason = EventProps<'add_repo_default_checkout_handoff'>['reason']
 
@@ -16,22 +17,53 @@ export function getProjectDefaultCheckout(worktrees: readonly Worktree[]): Workt
   return worktrees.find((worktree) => worktree.isMainWorktree) ?? null
 }
 
+function getProjectWorktreesForHost<T extends Worktree>(
+  worktrees: readonly T[],
+  executionHostId?: ExecutionHostId
+): T[] {
+  if (!executionHostId) {
+    return [...worktrees]
+  }
+  return worktrees.filter((worktree) => {
+    if (worktree.hostId) {
+      return worktree.hostId === executionHostId
+    }
+    if (worktree.runtimeOwnerEnvironmentId) {
+      return executionHostId === `runtime:${encodeURIComponent(worktree.runtimeOwnerEnvironmentId)}`
+    }
+    return executionHostId === 'local'
+  })
+}
+
+function ownerRefreshOptions(executionHostId?: ExecutionHostId) {
+  return {
+    requireAuthoritative: true as const,
+    ...(executionHostId ? { executionHostId } : {})
+  }
+}
+
 function getDetectedProjectDefaultCheckout(
-  detected: DetectedWorktreeListResult | undefined
+  detected: DetectedWorktreeListResult | undefined,
+  executionHostId?: ExecutionHostId
 ): DetectedWorktreeListResult['worktrees'][number] | null {
   if (detected?.authoritative !== true) {
     return null
   }
-  return detected.worktrees.find((worktree) => worktree.isMainWorktree) ?? null
+  return (
+    getProjectWorktreesForHost(detected.worktrees, executionHostId).find(
+      (worktree) => worktree.isMainWorktree
+    ) ?? null
+  )
 }
 
 function hasDetectedHiddenLinkedExternalWorktrees(
-  detected: DetectedWorktreeListResult | undefined
+  detected: DetectedWorktreeListResult | undefined,
+  executionHostId?: ExecutionHostId
 ): boolean {
   if (detected?.authoritative !== true) {
     return false
   }
-  return detected.worktrees.some(
+  return getProjectWorktreesForHost(detected.worktrees, executionHostId).some(
     (worktree) =>
       !worktree.isMainWorktree &&
       !worktree.selectedCheckout &&
@@ -44,32 +76,47 @@ function hasDetectedHiddenLinkedExternalWorktrees(
 }
 
 async function revealDetectedHiddenLinkedExternalWorktrees(
-  repoId: string
+  repoId: string,
+  executionHostId?: ExecutionHostId
 ): Promise<DefaultCheckoutHandoffReason | null> {
   const state = useAppStore.getState()
-  if (!hasDetectedHiddenLinkedExternalWorktrees(state.detectedWorktreesByRepo[repoId])) {
+  if (
+    !hasDetectedHiddenLinkedExternalWorktrees(
+      state.detectedWorktreesByRepo[repoId],
+      executionHostId
+    )
+  ) {
     return null
   }
 
   // Why: the removed setup step's existing-worktree path made linked external
   // worktrees visible; the automatic handoff must preserve that import result.
-  const updated = await state.updateRepo(repoId, { externalWorktreeVisibility: 'show' })
+  const updated = executionHostId
+    ? await state.updateRepo(
+        repoId,
+        { externalWorktreeVisibility: 'show' },
+        { hostId: executionHostId }
+      )
+    : await state.updateRepo(repoId, { externalWorktreeVisibility: 'show' })
   if (!updated) {
     return 'show_detected_linked_failed'
   }
-  const refreshed = await useAppStore.getState().fetchWorktrees(repoId, {
-    requireAuthoritative: true
-  })
+  const refreshed = await useAppStore
+    .getState()
+    .fetchWorktrees(repoId, ownerRefreshOptions(executionHostId))
   return refreshed ? null : 'linked_external_refresh_failed'
 }
 
-async function findDetectedDefaultCheckout(repoId: string): Promise<{
+async function findDetectedDefaultCheckout(
+  repoId: string,
+  executionHostId?: ExecutionHostId
+): Promise<{
   worktree: Worktree | null
   reason: DefaultCheckoutHandoffReason
 }> {
   const state = useAppStore.getState()
   const detected = state.detectedWorktreesByRepo[repoId]
-  const detectedDefaultCheckout = getDetectedProjectDefaultCheckout(detected)
+  const detectedDefaultCheckout = getDetectedProjectDefaultCheckout(detected, executionHostId)
   if (!detectedDefaultCheckout) {
     return {
       worktree: null,
@@ -80,18 +127,29 @@ async function findDetectedDefaultCheckout(repoId: string): Promise<{
   if (!detectedDefaultCheckout.visible) {
     // Why: a freshly cloned primary checkout can be detected as a hidden
     // external worktree; adding a project should make that checkout usable.
-    const updated = await state.updateRepo(repoId, { externalWorktreeVisibility: 'show' })
+    const updated = executionHostId
+      ? await state.updateRepo(
+          repoId,
+          { externalWorktreeVisibility: 'show' },
+          { hostId: executionHostId }
+        )
+      : await state.updateRepo(repoId, { externalWorktreeVisibility: 'show' })
     if (!updated) {
       return { worktree: null, reason: 'show_detected_default_failed' }
     }
   }
-  const refreshed = await useAppStore.getState().fetchWorktrees(repoId, {
-    requireAuthoritative: true
-  })
+  const refreshed = await useAppStore
+    .getState()
+    .fetchWorktrees(repoId, ownerRefreshOptions(executionHostId))
   if (!refreshed) {
     return { worktree: null, reason: 'authoritative_refresh_failed' }
   }
-  const worktree = getProjectDefaultCheckout(useAppStore.getState().worktreesByRepo[repoId] ?? [])
+  const worktree = getProjectDefaultCheckout(
+    getProjectWorktreesForHost(
+      useAppStore.getState().worktreesByRepo[repoId] ?? [],
+      executionHostId
+    )
+  )
   return {
     worktree,
     reason: worktree ? 'detected_default_checkout' : 'refreshed_default_missing'
@@ -113,25 +171,33 @@ export async function openProjectDefaultCheckout({
   repoId,
   source,
   selectedPath,
-  setHideDefaultBranchWorkspace
+  setHideDefaultBranchWorkspace,
+  executionHostId
 }: {
   repoId: string
   source: AddRepoDefaultCheckoutHandoffSource
   selectedPath?: string
   setHideDefaultBranchWorkspace: (value: boolean) => void
+  executionHostId?: ExecutionHostId
 }): Promise<void> {
   let defaultCheckout = getProjectDefaultCheckout(
-    useAppStore.getState().worktreesByRepo[repoId] ?? []
+    getProjectWorktreesForHost(
+      useAppStore.getState().worktreesByRepo[repoId] ?? [],
+      executionHostId
+    )
   )
   let reason: DefaultCheckoutHandoffReason = 'loaded_default_checkout'
   if (!defaultCheckout) {
-    const detectedDefaultCheckout = await findDetectedDefaultCheckout(repoId)
+    const detectedDefaultCheckout = await findDetectedDefaultCheckout(repoId, executionHostId)
     defaultCheckout = detectedDefaultCheckout.worktree
     reason = detectedDefaultCheckout.reason
   }
 
   if (defaultCheckout) {
-    const revealLinkedFailureReason = await revealDetectedHiddenLinkedExternalWorktrees(repoId)
+    const revealLinkedFailureReason = await revealDetectedHiddenLinkedExternalWorktrees(
+      repoId,
+      executionHostId
+    )
     if (revealLinkedFailureReason) {
       track('add_repo_default_checkout_handoff', {
         source,
@@ -153,8 +219,11 @@ export async function openProjectDefaultCheckout({
       reason
     })
     const initialCwd = resolveInitialCwdForDefaultCheckout(defaultCheckout, selectedPath)
-    if (initialCwd) {
-      activateAndRevealWorktree(defaultCheckout.id, { initialCwd })
+    if (initialCwd || executionHostId) {
+      activateAndRevealWorktree(defaultCheckout.id, {
+        ...(initialCwd ? { initialCwd } : {}),
+        ...(executionHostId ? { executionHostId } : {})
+      })
     } else {
       activateAndRevealWorktree(defaultCheckout.id)
     }
@@ -174,13 +243,15 @@ export async function finishProjectAddWithDefaultCheckout({
   source,
   selectedPath,
   closeModal,
-  setHideDefaultBranchWorkspace
+  setHideDefaultBranchWorkspace,
+  executionHostId
 }: {
   repoId: string
   source: AddRepoDefaultCheckoutHandoffSource
   selectedPath?: string
   closeModal: () => void
   setHideDefaultBranchWorkspace: (value: boolean) => void
+  executionHostId?: ExecutionHostId
 }): Promise<void> {
   await markOnboardingProjectAdded('addedRepo')
   closeModal()
@@ -188,6 +259,7 @@ export async function finishProjectAddWithDefaultCheckout({
     repoId,
     source,
     selectedPath,
+    executionHostId,
     setHideDefaultBranchWorkspace
   })
 }
diff --git a/src/renderer/src/components/sidebar/track-nested-folder-open.ts b/src/renderer/src/components/sidebar/track-nested-folder-open.ts
new file mode 100644
index 00000000000..add9c4aae19
--- /dev/null
+++ b/src/renderer/src/components/sidebar/track-nested-folder-open.ts
@@ -0,0 +1,30 @@
+import { track } from '@/lib/telemetry'
+import {
+  buildNestedRepoImportActionTelemetry,
+  type NestedRepoTelemetryRuntimeKind
+} from '../../../../shared/nested-repo-telemetry'
+import type { NestedRepoScanResult } from '../../../../shared/types'
+
+export function trackNestedFolderOpen(args: {
+  attemptId: string | null
+  runtimeKind: NestedRepoTelemetryRuntimeKind | null
+  connectionId: string | null
+  scan: NestedRepoScanResult
+  selectedCount: number
+  getRuntimeKind: (connectionId: string | null) => NestedRepoTelemetryRuntimeKind
+}): void {
+  if (!args.attemptId) {
+    return
+  }
+  track(
+    'add_repo_nested_import_action',
+    buildNestedRepoImportActionTelemetry({
+      attemptId: args.attemptId,
+      surface: 'sidebar',
+      runtimeKind: args.runtimeKind ?? args.getRuntimeKind(args.connectionId),
+      action: 'open_as_folder',
+      foundCount: args.scan.repos.length,
+      selectedCount: args.selectedCount
+    })
+  )
+}
diff --git a/src/renderer/src/components/sidebar/use-add-repo-remote-nested-scan.ts b/src/renderer/src/components/sidebar/use-add-repo-remote-nested-scan.ts
index 1f451b0a115..c57557f0cc1 100644
--- a/src/renderer/src/components/sidebar/use-add-repo-remote-nested-scan.ts
+++ b/src/renderer/src/components/sidebar/use-add-repo-remote-nested-scan.ts
@@ -7,7 +7,7 @@ export function useAddRepoRemoteNestedScan({
   setActiveNestedScanId,
   showNestedRepoReview
 }: {
-  setActiveNestedScanId: (scanId: string | null) => void
+  setActiveNestedScanId: (scanId: string | null, runtimeEnvironmentId?: string | null) => void
   showNestedRepoReview: (options: {
     scan: NestedRepoScanResult
     selectedPath: string
@@ -16,6 +16,7 @@ export function useAddRepoRemoteNestedScan({
     runtimeKind: 'ssh'
     inProgress: boolean
     scanId: string | null
+    runtimeEnvironmentId?: string | null
   }) => void
 }) {
   const showRemoteNestedRepoReview = useCallback(
@@ -27,7 +28,7 @@ export function useAddRepoRemoteNestedScan({
       inProgress: boolean,
       scanId: string | null
     ) => {
-      setActiveNestedScanId(inProgress ? scanId : null)
+      setActiveNestedScanId(inProgress ? scanId : null, null)
       showNestedRepoReview({
         scan,
         selectedPath,
@@ -35,7 +36,8 @@ export function useAddRepoRemoteNestedScan({
         attemptId,
         runtimeKind: 'ssh',
         inProgress,
-        scanId
+        scanId,
+        runtimeEnvironmentId: null
       })
     },
     [setActiveNestedScanId, showNestedRepoReview]
diff --git a/src/renderer/src/components/sidebar/use-complete-git-repo-add.ts b/src/renderer/src/components/sidebar/use-complete-git-repo-add.ts
index fe16881c7a4..a7ec91232c0 100644
--- a/src/renderer/src/components/sidebar/use-complete-git-repo-add.ts
+++ b/src/renderer/src/components/sidebar/use-complete-git-repo-add.ts
@@ -8,6 +8,7 @@ import {
 } from './add-repo-existing-workspaces-telemetry'
 import { compareWorktreeDisplayName } from '@/lib/worktree-display-name-order'
 import { finishProjectAddWithDefaultCheckout } from './project-added-default-checkout'
+import type { ExecutionHostId } from '../../../../shared/execution-host'
 
 type CompleteGitRepoAddOptions = {
   closeModal: () => void
@@ -15,7 +16,11 @@ type CompleteGitRepoAddOptions = {
   /** Why: the nested Add Project flow (hosted inside the workspace composer)
    *  keeps the composer open and selects the new project instead of running
    *  the default-checkout navigation handoff. Telemetry above still applies. */
-  finishProjectAdd?: (repoId: string, source: AddRepoExistingWorkspaceSource) => Promise<void>
+  finishProjectAdd?: (
+    repoId: string,
+    source: AddRepoExistingWorkspaceSource,
+    executionHostId?: ExecutionHostId
+  ) => Promise<void>
 }
 
 export function useCompleteGitRepoAdd({
@@ -24,13 +29,23 @@ export function useCompleteGitRepoAdd({
   finishProjectAdd
 }: CompleteGitRepoAddOptions): (
   repoId: string,
-  source: AddRepoExistingWorkspaceSource
+  source: AddRepoExistingWorkspaceSource,
+  executionHostId?: ExecutionHostId
 ) => Promise<void> {
   const detectedTelemetryTrackedRef = useRef<Set<string>>(new Set())
 
   return useCallback(
-    async (repoId: string, source: AddRepoExistingWorkspaceSource): Promise<void> => {
-      const worktrees = useAppStore.getState().worktreesByRepo[repoId] ?? []
+    async (
+      repoId: string,
+      source: AddRepoExistingWorkspaceSource,
+      executionHostId?: ExecutionHostId
+    ): Promise<void> => {
+      const worktrees = (useAppStore.getState().worktreesByRepo[repoId] ?? []).filter(
+        (worktree) =>
+          executionHostId === undefined ||
+          worktree.hostId === executionHostId ||
+          (!worktree.hostId && executionHostId === 'local')
+      )
       const sortedWorktrees = [...worktrees].sort((a, b) => {
         if (a.lastActivityAt !== b.lastActivityAt) {
           return b.lastActivityAt - a.lastActivityAt
@@ -50,12 +65,13 @@ export function useCompleteGitRepoAdd({
         track('add_repo_existing_workspaces_detected', existingWorkspaceTelemetry)
       }
       if (finishProjectAdd) {
-        await finishProjectAdd(repoId, source)
+        await finishProjectAdd(repoId, source, executionHostId)
         return
       }
       await finishProjectAddWithDefaultCheckout({
         repoId,
         source,
+        executionHostId,
         closeModal,
         setHideDefaultBranchWorkspace
       })
diff --git a/src/renderer/src/components/sidebar/useAddRepoCloneFlow.test.ts b/src/renderer/src/components/sidebar/useAddRepoCloneFlow.test.ts
index 3d02f5fe1a9..57958126563 100644
--- a/src/renderer/src/components/sidebar/useAddRepoCloneFlow.test.ts
+++ b/src/renderer/src/components/sidebar/useAddRepoCloneFlow.test.ts
@@ -136,7 +136,12 @@ describe('useAddRepoCloneFlow', () => {
     })
     expect(mocks.cloneLocal).not.toHaveBeenCalled()
     expect(mocks.fetchWorktrees).toHaveBeenCalledWith(repo.id, {
-      requireAuthoritative: true
+      requireAuthoritative: true,
+      executionHostId: 'ssh:ssh-1'
+    })
+    expect(mocks.storeState.repos).toContainEqual({
+      ...repo,
+      executionHostId: 'ssh:ssh-1'
     })
     expect(mocks.storeState.projects).toEqual(
       expect.arrayContaining([expect.objectContaining({ sourceRepoIds: [repo.id] })])
@@ -144,7 +149,7 @@ describe('useAddRepoCloneFlow', () => {
     expect(mocks.storeState.projectHostSetups).toEqual(
       expect.arrayContaining([expect.objectContaining({ repoId: repo.id, path: repo.path })])
     )
-    expect(mocks.onGitRepoReady).toHaveBeenCalledWith(repo.id, 'clone_url')
+    expect(mocks.onGitRepoReady).toHaveBeenCalledWith(repo.id, 'clone_url', 'ssh:ssh-1')
   })
 
   it('does not prefill SSH clone destinations from the local workspace directory', async () => {
@@ -186,7 +191,13 @@ describe('useAddRepoCloneFlow', () => {
   })
 
   it('clones through the selected runtime environment', async () => {
-    const repo = makeRepo({ id: 'runtime-repo', executionHostId: 'runtime:env-1' })
+    const repo = makeRepo({ id: 'runtime-repo' })
+    const localRepo = makeRepo({
+      id: repo.id,
+      path: '/local/runtime-repo',
+      executionHostId: 'local'
+    })
+    mocks.storeState.repos = [localRepo]
     mocks.callRuntimeRpc.mockResolvedValue({ repo })
     mocks.fetchWorktrees.mockResolvedValue(true)
     const { useAddRepoCloneFlow } = await import('./useAddRepoCloneFlow')
@@ -213,8 +224,14 @@ describe('useAddRepoCloneFlow', () => {
     expect(mocks.cloneLocal).not.toHaveBeenCalled()
     expect(mocks.cloneRemote).not.toHaveBeenCalled()
     expect(mocks.fetchWorktrees).toHaveBeenCalledWith(repo.id, {
-      requireAuthoritative: true
+      requireAuthoritative: true,
+      executionHostId: 'runtime:env-1'
     })
-    expect(mocks.onGitRepoReady).toHaveBeenCalledWith(repo.id, 'clone_url')
+    expect(mocks.storeState.repos).toContainEqual({
+      ...repo,
+      executionHostId: 'runtime:env-1'
+    })
+    expect(mocks.storeState.repos).toContainEqual(localRepo)
+    expect(mocks.onGitRepoReady).toHaveBeenCalledWith(repo.id, 'clone_url', 'runtime:env-1')
   })
 })
diff --git a/src/renderer/src/components/sidebar/useAddRepoCloneFlow.ts b/src/renderer/src/components/sidebar/useAddRepoCloneFlow.ts
index cd376a014fa..24d27523942 100644
--- a/src/renderer/src/components/sidebar/useAddRepoCloneFlow.ts
+++ b/src/renderer/src/components/sidebar/useAddRepoCloneFlow.ts
@@ -9,6 +9,8 @@ import type { AddRepoDialogStep } from './add-repo-dialog-types'
 import { translate } from '@/i18n/i18n'
 import { extractIpcErrorMessage } from '@/lib/ipc-error'
 import { upsertAddedRepoWithProjectHostSetup } from './add-repo-store-upsert'
+import { worktreeRefreshOptions } from './add-repo-runtime-owner'
+import type { ExecutionHostId } from '../../../../shared/execution-host'
 
 export function useAddRepoCloneFlow({
   step,
@@ -22,8 +24,15 @@ export function useAddRepoCloneFlow({
   activeRuntimeEnvironmentId: string | null | undefined
   sshTargetId?: string | null
   workspaceDir: string | null | undefined
-  fetchWorktrees: (repoId: string, options?: { requireAuthoritative?: boolean }) => Promise<unknown>
-  onGitRepoReady: (repoId: string, source: AddRepoExistingWorkspaceSource) => Promise<void>
+  fetchWorktrees: (
+    repoId: string,
+    options?: { requireAuthoritative?: boolean; executionHostId?: ExecutionHostId }
+  ) => Promise<unknown>
+  onGitRepoReady: (
+    repoId: string,
+    source: AddRepoExistingWorkspaceSource,
+    executionHostId?: ExecutionHostId
+  ) => Promise<void>
 }): {
   cloneUrl: string
   cloneDestination: string
@@ -148,18 +157,22 @@ export function useAddRepoCloneFlow({
       if (gen !== cloneGenRef.current || requestHostToken !== hostTokenRef.current) {
         return
       }
+      const { repo: ownedRepo } = upsertAddedRepoWithProjectHostSetup(repo, {
+        runtimeEnvironmentId: activeRuntimeEnvironmentId,
+        sshConnectionId: sshTargetId
+      })
       toast.success(
         translate('auto.components.sidebar.useAddRepoCloneFlow.4d0013cc93', 'Repository cloned'),
-        { description: repo.displayName }
+        { description: ownedRepo.displayName }
       )
-      upsertAddedRepoWithProjectHostSetup(repo)
       // Why: once the repo exists, a transient non-authoritative refresh
       // should fall through to project reveal instead of leaving the add flow open.
-      await fetchWorktrees(repo.id, { requireAuthoritative: true })
+      const ownerOptions = worktreeRefreshOptions(activeRuntimeEnvironmentId, sshTargetId)
+      await fetchWorktrees(ownedRepo.id, ownerOptions)
       if (gen !== cloneGenRef.current || requestHostToken !== hostTokenRef.current) {
         return
       }
-      await onGitRepoReady(repo.id, 'clone_url')
+      await onGitRepoReady(ownedRepo.id, 'clone_url', ownerOptions.executionHostId)
     } catch (err) {
       if (gen !== cloneGenRef.current || requestHostToken !== hostTokenRef.current) {
         return
diff --git a/src/renderer/src/components/sidebar/useAddRepoLocalFolderFlow.test.ts b/src/renderer/src/components/sidebar/useAddRepoLocalFolderFlow.test.ts
index 799c655f0fe..acc96258cb6 100644
--- a/src/renderer/src/components/sidebar/useAddRepoLocalFolderFlow.test.ts
+++ b/src/renderer/src/components/sidebar/useAddRepoLocalFolderFlow.test.ts
@@ -106,12 +106,27 @@ describe('useAddRepoLocalFolderFlow', () => {
 
     expect(pickFolders).toHaveBeenCalledTimes(1)
     expect(addRepoPath).toHaveBeenCalledTimes(2)
-    expect(addRepoPath).toHaveBeenNthCalledWith(1, '/projects/alpha')
-    expect(addRepoPath).toHaveBeenNthCalledWith(2, '/projects/beta')
-    expect(fetchWorktrees).toHaveBeenCalledWith('alpha', { requireAuthoritative: true })
-    expect(fetchWorktrees).toHaveBeenCalledWith('beta', { requireAuthoritative: true })
+    expect(addRepoPath).toHaveBeenNthCalledWith(1, '/projects/alpha', undefined, {
+      runtimeEnvironmentId: null
+    })
+    expect(addRepoPath).toHaveBeenNthCalledWith(2, '/projects/beta', undefined, {
+      runtimeEnvironmentId: null
+    })
+    expect(scanNestedRepos).toHaveBeenCalledWith(
+      '/projects/alpha',
+      undefined,
+      expect.objectContaining({ runtimeEnvironmentId: null })
+    )
+    expect(fetchWorktrees).toHaveBeenCalledWith('alpha', {
+      requireAuthoritative: true,
+      executionHostId: 'local'
+    })
+    expect(fetchWorktrees).toHaveBeenCalledWith('beta', {
+      requireAuthoritative: true,
+      executionHostId: 'local'
+    })
     expect(onGitRepoReady).toHaveBeenCalledTimes(1)
-    expect(onGitRepoReady).toHaveBeenCalledWith('alpha', 'local_folder_picker')
+    expect(onGitRepoReady).toHaveBeenCalledWith('alpha', 'local_folder_picker', 'local')
   })
 
   it('skips nested-review folders in a multi-folder add and continues with git folders', async () => {
@@ -146,9 +161,11 @@ describe('useAddRepoLocalFolderFlow', () => {
 
     expect(showNestedRepoReview).not.toHaveBeenCalled()
     expect(addRepoPath).toHaveBeenCalledTimes(1)
-    expect(addRepoPath).toHaveBeenCalledWith('/projects/later')
+    expect(addRepoPath).toHaveBeenCalledWith('/projects/later', undefined, {
+      runtimeEnvironmentId: null
+    })
     expect(scanNestedRepos).toHaveBeenCalledTimes(2)
-    expect(onGitRepoReady).toHaveBeenCalledWith('later', 'local_folder_picker')
+    expect(onGitRepoReady).toHaveBeenCalledWith('later', 'local_folder_picker', 'local')
   })
 
   it('still completes handoff when a later selected folder is skipped', async () => {
@@ -181,7 +198,44 @@ describe('useAddRepoLocalFolderFlow', () => {
 
     expect(showNestedRepoReview).not.toHaveBeenCalled()
     expect(addRepoPath).toHaveBeenCalledTimes(1)
-    expect(addRepoPath).toHaveBeenCalledWith('/projects/git')
-    expect(onGitRepoReady).toHaveBeenCalledWith('git', 'local_folder_picker')
+    expect(addRepoPath).toHaveBeenCalledWith('/projects/git', undefined, {
+      runtimeEnvironmentId: null
+    })
+    expect(onGitRepoReady).toHaveBeenCalledWith('git', 'local_folder_picker', 'local')
+  })
+
+  it('drops a local scan completion after host-scoped reset', async () => {
+    pickFolders.mockResolvedValue(['/projects/stale'])
+    let resolveScan!: (scan: NestedRepoScanResult) => void
+    scanNestedRepos.mockReturnValueOnce(
+      new Promise((resolve) => {
+        resolveScan = resolve
+      })
+    )
+    const { useAddRepoLocalFolderFlow } = await import('./useAddRepoLocalFolderFlow')
+    const flow = useAddRepoLocalFolderFlow({
+      isOpen: true,
+      droppedLocalPath: '',
+      activeRuntimeEnvironmentId: null,
+      addRepoPath,
+      closeModal,
+      fetchWorktrees,
+      scanNestedRepos,
+      setActiveNestedScanId,
+      setNestedScanInProgress,
+      showNestedRepoReview,
+      onGitRepoReady,
+      setIsAdding,
+      setAddProjectBusyLabel
+    })
+
+    const adding = flow.handleBrowse()
+    await vi.waitFor(() => expect(scanNestedRepos).toHaveBeenCalled())
+    flow.resetLocalFolderFlow()
+    resolveScan(makeScan('/projects/stale'))
+    await adding
+
+    expect(addRepoPath).not.toHaveBeenCalled()
+    expect(onGitRepoReady).not.toHaveBeenCalled()
   })
 })
diff --git a/src/renderer/src/components/sidebar/useAddRepoLocalFolderFlow.ts b/src/renderer/src/components/sidebar/useAddRepoLocalFolderFlow.ts
index 844eb11ad6b..859698f19f8 100644
--- a/src/renderer/src/components/sidebar/useAddRepoLocalFolderFlow.ts
+++ b/src/renderer/src/components/sidebar/useAddRepoLocalFolderFlow.ts
@@ -9,8 +9,12 @@ import {
 } from '../../../../shared/nested-repo-telemetry'
 import type { AddRepoExistingWorkspaceSource } from '../../../../shared/telemetry-events'
 import type { NestedRepoScanResult, Repo } from '../../../../shared/types'
+import type { WorktreeFetchOptions } from '@/store/slices/worktree-helpers'
+import type { RepoSlice } from '@/store/slices/repos'
 import { createNestedRepoScanId } from './add-repo-dialog-types'
 import { translate } from '@/i18n/i18n'
+import { worktreeRefreshOptions } from './add-repo-runtime-owner'
+import type { ExecutionHostId } from '../../../../shared/execution-host'
 
 type ShowNestedRepoReview = (args: {
   scan: NestedRepoScanResult
@@ -20,6 +24,7 @@ type ShowNestedRepoReview = (args: {
   runtimeKind: NestedRepoTelemetryRuntimeKind
   inProgress: boolean
   scanId: string | null
+  runtimeEnvironmentId?: string | null
 }) => void
 
 type LocalPathAddResult =
@@ -46,18 +51,18 @@ export function useAddRepoLocalFolderFlow({
   isOpen: boolean
   droppedLocalPath: string
   activeRuntimeEnvironmentId: string | null | undefined
-  addRepoPath: (path: string, kind?: 'git' | 'folder') => Promise<Repo | null>
+  addRepoPath: RepoSlice['addRepoPath']
   closeModal: () => void
-  fetchWorktrees: (repoId: string, options?: { requireAuthoritative?: boolean }) => Promise<unknown>
-  scanNestedRepos: (
-    path: string,
-    connectionId?: string,
-    controls?: { scanId?: string; onProgress?: (scan: NestedRepoScanResult) => void }
-  ) => Promise<NestedRepoScanResult | null>
-  setActiveNestedScanId: (scanId: string | null) => void
+  fetchWorktrees: (repoId: string, options?: WorktreeFetchOptions) => Promise<unknown>
+  scanNestedRepos: RepoSlice['scanNestedRepos']
+  setActiveNestedScanId: (scanId: string | null, runtimeEnvironmentId?: string | null) => void
   setNestedScanInProgress: (inProgress: boolean) => void
   showNestedRepoReview: ShowNestedRepoReview
-  onGitRepoReady: (repoId: string, source: AddRepoExistingWorkspaceSource) => Promise<void>
+  onGitRepoReady: (
+    repoId: string,
+    source: AddRepoExistingWorkspaceSource,
+    executionHostId?: ExecutionHostId
+  ) => Promise<void>
   setIsAdding: (isAdding: boolean) => void
   setAddProjectBusyLabel: (label: string | null) => void
 }): {
@@ -98,10 +103,11 @@ export function useAddRepoLocalFolderFlow({
       try {
         const attemptId = createNestedRepoTelemetryAttemptId()
         const scanId = createNestedRepoScanId()
-        setActiveNestedScanId(scanId)
+        setActiveNestedScanId(scanId, activeRuntimeEnvironmentId ?? null)
         setNestedScanInProgress(true)
         const scan = await scanNestedRepos(path, undefined, {
           scanId,
+          runtimeEnvironmentId: activeRuntimeEnvironmentId ?? null,
           onProgress: (progressScan) => {
             if (
               gen !== localAddGenRef.current ||
@@ -118,7 +124,8 @@ export function useAddRepoLocalFolderFlow({
               attemptId,
               runtimeKind: 'local',
               inProgress: true,
-              scanId
+              scanId,
+              runtimeEnvironmentId: activeRuntimeEnvironmentId
             })
           }
         })
@@ -139,8 +146,7 @@ export function useAddRepoLocalFolderFlow({
           return { status: 'skipped' }
         }
         if (scan?.selectedPathKind === 'non_git_folder' && scan.repos.length > 0) {
-          // Why: the existing nested-repo review is a single-folder decision point.
-          // Pause batch imports here instead of queueing competing review states.
+          // Why: a single-folder decision point cannot queue competing batch review states.
           showNestedRepoReview({
             scan,
             selectedPath: path,
@@ -148,12 +154,15 @@ export function useAddRepoLocalFolderFlow({
             attemptId,
             runtimeKind: 'local',
             inProgress: false,
-            scanId
+            scanId,
+            runtimeEnvironmentId: activeRuntimeEnvironmentId
           })
           return { status: 'paused' }
         }
         setAddProjectBusyLabel('Opening project...')
-        const repo = await addRepoPath(path)
+        const repo = await addRepoPath(path, undefined, {
+          runtimeEnvironmentId: activeRuntimeEnvironmentId ?? null
+        })
         if (gen !== localAddGenRef.current) {
           return { status: 'cancelled' }
         }
@@ -161,16 +170,16 @@ export function useAddRepoLocalFolderFlow({
           return { status: 'paused' }
         }
         if (isGitRepoKind(repo)) {
-          // Why: once the repo exists, a transient non-authoritative refresh
-          // should fall through to project reveal instead of leaving the add flow open.
-          await fetchWorktrees(repo.id, { requireAuthoritative: true })
+          // Why: a transient non-authoritative refresh must not strand a persisted repo.
+          const ownerOptions = worktreeRefreshOptions(activeRuntimeEnvironmentId ?? null)
+          await fetchWorktrees(repo.id, ownerOptions)
           if (gen !== localAddGenRef.current) {
             return { status: 'cancelled' }
           }
           if (mode === 'batch') {
             return { status: 'completed', repo }
           }
-          await onGitRepoReady(repo.id, source)
+          await onGitRepoReady(repo.id, source, ownerOptions.executionHostId)
         } else {
           // Why: folder repos skip the Git default-checkout handoff and activate
           // their synthetic root workspace in the folder add flow.
@@ -260,10 +269,14 @@ export function useAddRepoLocalFolderFlow({
         )
       }
       if (shouldDeferGitRepoReady && gitRepoIds.length > 0) {
-        await onGitRepoReady(gitRepoIds[0], source)
+        await onGitRepoReady(
+          gitRepoIds[0],
+          source,
+          worktreeRefreshOptions(activeRuntimeEnvironmentId ?? null).executionHostId
+        )
       }
     },
-    [addLocalPathForGeneration, onGitRepoReady]
+    [activeRuntimeEnvironmentId, addLocalPathForGeneration, onGitRepoReady]
   )
 
   useEffect(() => {
diff --git a/src/renderer/src/components/sidebar/useAddRepoNestedImportFlow.test.ts b/src/renderer/src/components/sidebar/useAddRepoNestedImportFlow.test.ts
index aa5a4b9fdbf..6f56f454edd 100644
--- a/src/renderer/src/components/sidebar/useAddRepoNestedImportFlow.test.ts
+++ b/src/renderer/src/components/sidebar/useAddRepoNestedImportFlow.test.ts
@@ -111,7 +111,8 @@ describe('useAddRepoNestedImportFlow open folder fallback', () => {
 
   it('keeps runtime folder opens on the runtime that produced the scan', async () => {
     const { handleOpenNestedRootFolder } = useTestAddRepoNestedImportFlow({
-      activeRuntimeEnvironmentId: 'env-1'
+      activeRuntimeEnvironmentId: 'env-1',
+      nestedRuntimeEnvironmentId: 'env-1'
     })
 
     await handleOpenNestedRootFolder()
@@ -153,4 +154,52 @@ describe('useAddRepoNestedImportFlow open folder fallback', () => {
       connectionId: 'ssh-builder'
     })
   })
+
+  it('keeps SSH import and completion pinned when repo hydration is missing', async () => {
+    const importedRepo: Repo = {
+      ...folderRepo,
+      id: 'ssh-app',
+      path: scan.repos[0].path,
+      kind: 'git',
+      connectionId: 'ssh-builder'
+    }
+    const importNestedRepos = vi.fn().mockResolvedValue({
+      projects: [
+        { path: importedRepo.path, projectId: importedRepo.id, status: 'imported' as const }
+      ],
+      importedCount: 1,
+      alreadyKnownCount: 0,
+      failedCount: 0
+    })
+    const fetchWorktrees = vi.fn()
+    const onGitRepoReady = vi.fn()
+    mocks.state.repos = []
+    const { handleImportNestedRepos } = useTestAddRepoNestedImportFlow({
+      activeRuntimeEnvironmentId: null,
+      nestedConnectionId: 'ssh-builder',
+      nestedRuntimeEnvironmentId: null,
+      nestedRuntimeKind: 'ssh',
+      nestedSelectedPaths: new Set([importedRepo.path]),
+      importNestedRepos,
+      fetchWorktrees,
+      onGitRepoReady
+    })
+
+    await handleImportNestedRepos('group')
+
+    expect(importNestedRepos).toHaveBeenCalledWith({
+      parentPath: scan.selectedPath,
+      groupName: 'platform',
+      projectPaths: [importedRepo.path],
+      connectionId: 'ssh-builder',
+      scanId: 'scan-1',
+      runtimeEnvironmentId: null,
+      mode: 'group'
+    })
+    expect(fetchWorktrees).toHaveBeenCalledWith(importedRepo.id, {
+      requireAuthoritative: true,
+      executionHostId: 'ssh:ssh-builder'
+    })
+    expect(onGitRepoReady).not.toHaveBeenCalled()
+  })
 })
diff --git a/src/renderer/src/components/sidebar/useAddRepoNestedImportFlow.ts b/src/renderer/src/components/sidebar/useAddRepoNestedImportFlow.ts
index c0a69751814..c0c505cc97c 100644
--- a/src/renderer/src/components/sidebar/useAddRepoNestedImportFlow.ts
+++ b/src/renderer/src/components/sidebar/useAddRepoNestedImportFlow.ts
@@ -11,7 +11,11 @@ import {
 } from '../../../../shared/nested-repo-telemetry'
 import type { AddRepoExistingWorkspaceSource } from '../../../../shared/telemetry-events'
 import type { NestedRepoScanResult, ProjectGroupImportResult } from '../../../../shared/types'
+import type { WorktreeFetchOptions } from '@/store/slices/worktree-helpers'
 import { translate } from '@/i18n/i18n'
+import { worktreeRefreshOptions, type CapturedRuntimeOwner } from './add-repo-runtime-owner'
+import { completeNestedFolderOpen } from './complete-nested-folder-open'
+import type { ExecutionHostId } from '../../../../shared/execution-host'
 
 export function useAddRepoNestedImportFlow({
   nestedAttemptId,
@@ -21,6 +25,7 @@ export function useAddRepoNestedImportFlow({
   nestedConnectionId,
   nestedGroupName,
   nestedImportScanId,
+  nestedRuntimeEnvironmentId,
   activeRuntimeEnvironmentId,
   closeModal,
   fetchWorktrees,
@@ -36,21 +41,25 @@ export function useAddRepoNestedImportFlow({
   nestedConnectionId: string | null
   nestedGroupName: string
   nestedImportScanId: string | null
+  nestedRuntimeEnvironmentId?: CapturedRuntimeOwner
   activeRuntimeEnvironmentId: string | null | undefined
-  /** Why: hosted (composer-nested) mode routes this to closing only the
-   *  nested dialog; store-modal mode routes it to the activeModal slot. */
   closeModal: () => void
-  fetchWorktrees: (repoId: string, options?: { requireAuthoritative?: boolean }) => Promise<unknown>
+  fetchWorktrees: (repoId: string, options?: WorktreeFetchOptions) => Promise<unknown>
   importNestedRepos: (args: {
     parentPath: string
     groupName: string
     projectPaths: string[]
     connectionId?: string
     scanId?: string
+    runtimeEnvironmentId?: string | null
     mode: 'group' | 'separate'
   }) => Promise<ProjectGroupImportResult | null>
   getNestedRepoRuntimeKind: (connectionId: string | null) => NestedRepoTelemetryRuntimeKind
-  onGitRepoReady: (repoId: string, source: AddRepoExistingWorkspaceSource) => Promise<void>
+  onGitRepoReady: (
+    repoId: string,
+    source: AddRepoExistingWorkspaceSource,
+    executionHostId?: ExecutionHostId
+  ) => Promise<void>
   setIsAdding: (isAdding: boolean) => void
 }): {
   handleImportNestedRepos: (mode: 'group' | 'separate') => Promise<void>
@@ -59,11 +68,9 @@ export function useAddRepoNestedImportFlow({
   trackNestedBackAction: () => void
 } {
   const nestedImportGenRef = useRef(0)
-
   const resetNestedImportFlow = useCallback((): void => {
     nestedImportGenRef.current++
   }, [])
-
   const trackNestedBackAction = useCallback((): void => {
     if (!nestedScan || !nestedAttemptId) {
       return
@@ -126,11 +133,10 @@ export function useAddRepoNestedImportFlow({
         const result = await importNestedRepos({
           parentPath: nestedScan.selectedPath,
           groupName: nestedGroupName,
-          // Why: Set insertion order can drift after deselect/reselect; import
-          // ordering should match the visible scan order users reviewed.
           projectPaths: selectedProjectPaths,
           ...(nestedConnectionId ? { connectionId: nestedConnectionId } : {}),
           ...(nestedImportScanId ? { scanId: nestedImportScanId } : {}),
+          runtimeEnvironmentId: nestedRuntimeEnvironmentId,
           mode
         })
         track(
@@ -168,10 +174,10 @@ export function useAddRepoNestedImportFlow({
           }
           return
         }
+        const completionOwner = nestedConnectionId === null ? nestedRuntimeEnvironmentId : undefined
+        const completionOwnerOptions = worktreeRefreshOptions(completionOwner, nestedConnectionId)
         for (const projectId of importedRepoIds) {
-          // Why: imported repos are already persisted; non-authoritative SSH
-          // refreshes should not block revealing the first imported project.
-          await fetchWorktrees(projectId, { requireAuthoritative: true })
+          await fetchWorktrees(projectId, completionOwnerOptions)
         }
         if (gen !== nestedImportGenRef.current) {
           return
@@ -198,7 +204,7 @@ export function useAddRepoNestedImportFlow({
             : activeRuntimeEnvironmentId?.trim()
               ? 'runtime_server_path'
               : 'local_folder_picker'
-          await onGitRepoReady(repo.id, source)
+          await onGitRepoReady(repo.id, source, completionOwnerOptions.executionHostId)
         }
       } catch (err) {
         if (gen === nestedImportGenRef.current) {
@@ -232,6 +238,7 @@ export function useAddRepoNestedImportFlow({
       nestedConnectionId,
       nestedGroupName,
       nestedImportScanId,
+      nestedRuntimeEnvironmentId,
       nestedRuntimeKind,
       nestedScan,
       nestedSelectedPaths,
@@ -240,70 +247,35 @@ export function useAddRepoNestedImportFlow({
       setIsAdding
     ]
   )
-
-  const handleOpenNestedRootFolder = useCallback(async (): Promise<void> => {
+  const handleOpenNestedRootFolder = useCallback(() => {
     if (!nestedScan) {
-      return
-    }
-    const gen = ++nestedImportGenRef.current
-    const path = nestedScan.selectedPath
-    if (nestedAttemptId) {
-      track(
-        'add_repo_nested_import_action',
-        buildNestedRepoImportActionTelemetry({
-          attemptId: nestedAttemptId,
-          surface: 'sidebar',
-          runtimeKind: nestedRuntimeKind ?? getNestedRepoRuntimeKind(nestedConnectionId),
-          action: 'open_as_folder',
-          foundCount: nestedScan.repos.length,
-          selectedCount: nestedSelectedPaths.size
-        })
-      )
-    }
-    setIsAdding(true)
-    try {
-      const state = useAppStore.getState()
-      if (nestedConnectionId) {
-        // Why: the non-git confirm dialog is a store-modal handoff that ends
-        // in folder-workspace activation; close this add flow (nested dialog
-        // or store modal) before handing over.
-        closeModal()
-        state.openModal('confirm-non-git-folder', {
-          folderPath: path,
-          connectionId: nestedConnectionId
-        })
-        return
-      }
-      const repo = await state.addNonGitFolder(path, {
-        runtimeEnvironmentId: activeRuntimeEnvironmentId?.trim() || null
-      })
-      if (gen !== nestedImportGenRef.current) {
-        return
-      }
-      if (repo) {
-        closeModal()
-      }
-    } catch (err) {
-      if (gen === nestedImportGenRef.current) {
-        toast.error(err instanceof Error ? err.message : String(err))
-      }
-    } finally {
-      if (gen === nestedImportGenRef.current) {
-        setIsAdding(false)
-      }
+      return Promise.resolve()
     }
+    const generation = ++nestedImportGenRef.current
+    return completeNestedFolderOpen({
+      scan: nestedScan,
+      generation,
+      currentGeneration: () => nestedImportGenRef.current,
+      attemptId: nestedAttemptId,
+      runtimeKind: nestedRuntimeKind,
+      connectionId: nestedConnectionId,
+      selectedCount: nestedSelectedPaths.size,
+      getRuntimeKind: getNestedRepoRuntimeKind,
+      owner: nestedRuntimeEnvironmentId,
+      closeModal,
+      setIsAdding
+    })
   }, [
-    activeRuntimeEnvironmentId,
     closeModal,
     getNestedRepoRuntimeKind,
     nestedAttemptId,
     nestedConnectionId,
     nestedRuntimeKind,
+    nestedRuntimeEnvironmentId,
     nestedScan,
     nestedSelectedPaths.size,
     setIsAdding
   ])
-
   return {
     handleImportNestedRepos,
     handleOpenNestedRootFolder,
diff --git a/src/renderer/src/components/sidebar/useAddRepoNestedReviewController.ts b/src/renderer/src/components/sidebar/useAddRepoNestedReviewController.ts
new file mode 100644
index 00000000000..a5f47153736
--- /dev/null
+++ b/src/renderer/src/components/sidebar/useAddRepoNestedReviewController.ts
@@ -0,0 +1,82 @@
+import type { Dispatch, SetStateAction } from 'react'
+import type { AddRepoExistingWorkspaceSource } from '../../../../shared/telemetry-events'
+import type { ProjectGroupImportResult } from '../../../../shared/types'
+import type { WorktreeFetchOptions } from '@/store/slices/worktree-helpers'
+import { useAddRepoNestedImportFlow } from './useAddRepoNestedImportFlow'
+import { useAddRepoNestedReviewState } from './useAddRepoNestedReviewState'
+import { useAddRepoRemoteNestedScan } from './use-add-repo-remote-nested-scan'
+import type { AddRepoDialogStep } from './add-repo-dialog-types'
+import type { ExecutionHostId } from '../../../../shared/execution-host'
+
+export function useAddRepoNestedReviewController({
+  activeRuntimeEnvironmentId,
+  cancelNestedRepoScan,
+  closeModal,
+  fetchWorktrees,
+  importNestedRepos,
+  onGitRepoReady,
+  setIsAdding,
+  setStep,
+  reviewRuntimeEnvironmentId
+}: {
+  activeRuntimeEnvironmentId: string | null | undefined
+  reviewRuntimeEnvironmentId: string | null | undefined
+  cancelNestedRepoScan: (
+    scanId: string,
+    options?: { runtimeEnvironmentId?: string | null }
+  ) => Promise<unknown>
+  closeModal: () => void
+  fetchWorktrees: (repoId: string, options?: WorktreeFetchOptions) => Promise<unknown>
+  importNestedRepos: (args: {
+    parentPath: string
+    groupName: string
+    projectPaths: string[]
+    connectionId?: string
+    scanId?: string
+    runtimeEnvironmentId?: string | null
+    mode: 'group' | 'separate'
+  }) => Promise<ProjectGroupImportResult | null>
+  onGitRepoReady: (
+    repoId: string,
+    source: AddRepoExistingWorkspaceSource,
+    executionHostId?: ExecutionHostId
+  ) => Promise<void>
+  setIsAdding: (isAdding: boolean) => void
+  setStep: Dispatch<SetStateAction<AddRepoDialogStep>>
+}): ReturnType<typeof useAddRepoNestedReviewState> &
+  Pick<
+    ReturnType<typeof useAddRepoNestedImportFlow>,
+    | 'handleImportNestedRepos'
+    | 'handleOpenNestedRootFolder'
+    | 'resetNestedImportFlow'
+    | 'trackNestedBackAction'
+  > &
+  ReturnType<typeof useAddRepoRemoteNestedScan> {
+  const review = useAddRepoNestedReviewState({
+    activeRuntimeEnvironmentId: reviewRuntimeEnvironmentId,
+    cancelNestedRepoScan,
+    setStep
+  })
+  const remote = useAddRepoRemoteNestedScan({
+    setActiveNestedScanId: review.setActiveNestedScanId,
+    showNestedRepoReview: review.showNestedRepoReview
+  })
+  const imports = useAddRepoNestedImportFlow({
+    activeRuntimeEnvironmentId,
+    closeModal,
+    fetchWorktrees,
+    importNestedRepos,
+    onGitRepoReady,
+    setIsAdding,
+    nestedAttemptId: review.nestedAttemptId,
+    nestedScan: review.nestedScan,
+    nestedSelectedPaths: review.nestedSelectedPaths,
+    nestedRuntimeKind: review.nestedRuntimeKind,
+    nestedConnectionId: review.nestedConnectionId,
+    nestedGroupName: review.nestedGroupName,
+    nestedImportScanId: review.nestedImportScanId,
+    nestedRuntimeEnvironmentId: review.nestedRuntimeEnvironmentId,
+    getNestedRepoRuntimeKind: review.getNestedRepoRuntimeKind
+  })
+  return { ...review, ...remote, ...imports }
+}
diff --git a/src/renderer/src/components/sidebar/useAddRepoNestedReviewState.ts b/src/renderer/src/components/sidebar/useAddRepoNestedReviewState.ts
index 967229e9565..a8f41592fbd 100644
--- a/src/renderer/src/components/sidebar/useAddRepoNestedReviewState.ts
+++ b/src/renderer/src/components/sidebar/useAddRepoNestedReviewState.ts
@@ -11,6 +11,7 @@ type ShowNestedRepoReviewArgs = {
   runtimeKind: NestedRepoTelemetryRuntimeKind
   inProgress: boolean
   scanId: string | null
+  runtimeEnvironmentId?: string | null
 }
 
 export function useAddRepoNestedReviewState({
@@ -19,7 +20,10 @@ export function useAddRepoNestedReviewState({
   setStep
 }: {
   activeRuntimeEnvironmentId: string | null | undefined
-  cancelNestedRepoScan: (scanId: string) => Promise<unknown>
+  cancelNestedRepoScan: (
+    scanId: string,
+    options?: { runtimeEnvironmentId?: string | null }
+  ) => Promise<unknown>
   setStep: (step: AddRepoDialogStep) => void
 }): {
   nestedScan: NestedRepoScanResult | null
@@ -31,12 +35,13 @@ export function useAddRepoNestedReviewState({
   nestedScanInProgress: boolean
   nestedScanId: string | null
   nestedImportScanId: string | null
+  nestedRuntimeEnvironmentId: string | null | undefined
   setNestedSelectedPaths: Dispatch<SetStateAction<Set<string>>>
   setNestedGroupName: Dispatch<SetStateAction<string>>
   setNestedScanInProgress: Dispatch<SetStateAction<boolean>>
   getNestedRepoRuntimeKind: (connectionId: string | null) => NestedRepoTelemetryRuntimeKind
   showNestedRepoReview: (args: ShowNestedRepoReviewArgs) => void
-  setActiveNestedScanId: (scanId: string | null) => void
+  setActiveNestedScanId: (scanId: string | null, runtimeEnvironmentId?: string | null) => void
   handleStopNestedScan: () => void
   resetNestedRepoReviewState: () => void
 } {
@@ -51,7 +56,11 @@ export function useAddRepoNestedReviewState({
   const [nestedScanInProgress, setNestedScanInProgress] = useState(false)
   const [nestedScanId, setNestedScanId] = useState<string | null>(null)
   const [nestedImportScanId, setNestedImportScanId] = useState<string | null>(null)
+  const [nestedRuntimeEnvironmentId, setNestedRuntimeEnvironmentId] = useState<
+    string | null | undefined
+  >(undefined)
   const nestedScanIdRef = useRef<string | null>(null)
+  const nestedScanRuntimeEnvironmentIdRef = useRef<string | null | undefined>(undefined)
 
   const getNestedRepoRuntimeKind = useCallback(
     (connectionId: string | null): NestedRepoTelemetryRuntimeKind => {
@@ -75,28 +84,37 @@ export function useAddRepoNestedReviewState({
       setNestedRuntimeKind(args.runtimeKind)
       setNestedScanInProgress(args.inProgress)
       setNestedImportScanId(args.scanId)
+      setNestedRuntimeEnvironmentId(args.runtimeEnvironmentId ?? null)
       setStep('nested')
     },
     [setStep]
   )
 
-  const setActiveNestedScanId = useCallback((scanId: string | null): void => {
-    nestedScanIdRef.current = scanId
-    setNestedScanId(scanId)
-  }, [])
+  const setActiveNestedScanId = useCallback(
+    (scanId: string | null, runtimeEnvironmentId?: string | null): void => {
+      nestedScanIdRef.current = scanId
+      nestedScanRuntimeEnvironmentIdRef.current = scanId ? runtimeEnvironmentId : undefined
+      setNestedScanId(scanId)
+    },
+    []
+  )
 
   const handleStopNestedScan = useCallback(() => {
     const scanId = nestedScanIdRef.current
     if (!scanId) {
       return
     }
-    void cancelNestedRepoScan(scanId)
+    void cancelNestedRepoScan(scanId, {
+      runtimeEnvironmentId: nestedScanRuntimeEnvironmentIdRef.current
+    })
   }, [cancelNestedRepoScan])
 
   const resetNestedRepoReviewState = useCallback((): void => {
     const activeNestedScanId = nestedScanIdRef.current
     if (activeNestedScanId) {
-      void cancelNestedRepoScan(activeNestedScanId)
+      void cancelNestedRepoScan(activeNestedScanId, {
+        runtimeEnvironmentId: nestedScanRuntimeEnvironmentIdRef.current
+      })
     }
     setNestedScan(null)
     setNestedSelectedPaths(new Set())
@@ -106,6 +124,7 @@ export function useAddRepoNestedReviewState({
     setNestedRuntimeKind(null)
     setNestedScanInProgress(false)
     setNestedImportScanId(null)
+    setNestedRuntimeEnvironmentId(null)
     setActiveNestedScanId(null)
   }, [cancelNestedRepoScan, setActiveNestedScanId])
 
@@ -119,6 +138,7 @@ export function useAddRepoNestedReviewState({
     nestedScanInProgress,
     nestedScanId,
     nestedImportScanId,
+    nestedRuntimeEnvironmentId,
     setNestedSelectedPaths,
     setNestedGroupName,
     setNestedScanInProgress,
diff --git a/src/renderer/src/components/sidebar/useAddRepoServerPathFlow.test.ts b/src/renderer/src/components/sidebar/useAddRepoServerPathFlow.test.ts
index b6b50008fcc..53d2b334112 100644
--- a/src/renderer/src/components/sidebar/useAddRepoServerPathFlow.test.ts
+++ b/src/renderer/src/components/sidebar/useAddRepoServerPathFlow.test.ts
@@ -76,6 +76,7 @@ describe('useAddRepoServerPathFlow', () => {
 
     const result = useAddRepoServerPathFlow({
       addRepoPath: mocks.addRepoPath,
+      activeRuntimeEnvironmentId: 'box1-environment-id',
       closeModal: mocks.closeModal,
       fetchWorktrees: mocks.fetchWorktrees,
       getNestedRepoRuntimeKind: mocks.getNestedRepoRuntimeKind,
@@ -88,11 +89,53 @@ describe('useAddRepoServerPathFlow', () => {
     })
     await result.handleAddServerPath('folder')
 
-    expect(mocks.addRepoPath).toHaveBeenCalledWith('/server/docs', 'folder')
+    expect(mocks.addRepoPath).toHaveBeenCalledWith('/server/docs', 'folder', {
+      runtimeEnvironmentId: 'box1-environment-id'
+    })
     expect(mocks.scanNestedRepos).not.toHaveBeenCalled()
     expect(mocks.fetchWorktrees).not.toHaveBeenCalled()
     expect(mocks.onGitRepoReady).not.toHaveBeenCalled()
     expect(mocks.markOnboardingProjectAdded).toHaveBeenCalledWith('addedFolder')
     expect(mocks.closeModal).toHaveBeenCalled()
   })
+
+  it('routes the nested Git pre-scan and add through the selected runtime', async () => {
+    const repo = makeRepo({ id: 'server-git', kind: 'git' })
+    mocks.getNestedRepoRuntimeKind.mockReturnValue('runtime')
+    mocks.scanNestedRepos.mockResolvedValue({
+      selectedPath: '/server/docs',
+      selectedPathKind: 'git_repo',
+      repos: []
+    })
+    mocks.addRepoPath.mockResolvedValue(repo)
+    const { useAddRepoServerPathFlow } = await import('./useAddRepoServerPathFlow')
+
+    const result = useAddRepoServerPathFlow({
+      addRepoPath: mocks.addRepoPath,
+      activeRuntimeEnvironmentId: 'box1-environment-id',
+      closeModal: mocks.closeModal,
+      fetchWorktrees: mocks.fetchWorktrees,
+      getNestedRepoRuntimeKind: mocks.getNestedRepoRuntimeKind,
+      scanNestedRepos: mocks.scanNestedRepos,
+      setActiveNestedScanId: mocks.setActiveNestedScanId,
+      setNestedScanInProgress: mocks.setNestedScanInProgress,
+      showNestedRepoReview: mocks.showNestedRepoReview,
+      onGitRepoReady: mocks.onGitRepoReady,
+      setAddProjectBusyLabel: mocks.setAddProjectBusyLabel
+    })
+    await result.handleAddServerPath('git')
+
+    expect(mocks.scanNestedRepos).toHaveBeenCalledWith(
+      '/server/docs',
+      undefined,
+      expect.objectContaining({ runtimeEnvironmentId: 'box1-environment-id' })
+    )
+    expect(mocks.addRepoPath).toHaveBeenCalledWith('/server/docs', 'git', {
+      runtimeEnvironmentId: 'box1-environment-id'
+    })
+    expect(mocks.fetchWorktrees).toHaveBeenCalledWith('server-git', {
+      requireAuthoritative: true,
+      executionHostId: 'runtime:box1-environment-id'
+    })
+  })
 })
diff --git a/src/renderer/src/components/sidebar/useAddRepoServerPathFlow.ts b/src/renderer/src/components/sidebar/useAddRepoServerPathFlow.ts
index 9f2d49dc9a8..a02bdbcf3f4 100644
--- a/src/renderer/src/components/sidebar/useAddRepoServerPathFlow.ts
+++ b/src/renderer/src/components/sidebar/useAddRepoServerPathFlow.ts
@@ -9,7 +9,10 @@ import {
 } from '../../../../shared/nested-repo-telemetry'
 import type { AddRepoExistingWorkspaceSource } from '../../../../shared/telemetry-events'
 import type { NestedRepoScanResult, Repo } from '../../../../shared/types'
+import type { WorktreeFetchOptions } from '@/store/slices/worktree-helpers'
 import { createNestedRepoScanId } from './add-repo-dialog-types'
+import { worktreeRefreshOptions } from './add-repo-runtime-owner'
+import type { ExecutionHostId } from '../../../../shared/execution-host'
 
 type ShowNestedRepoReview = (args: {
   scan: NestedRepoScanResult
@@ -19,10 +22,12 @@ type ShowNestedRepoReview = (args: {
   runtimeKind: NestedRepoTelemetryRuntimeKind
   inProgress: boolean
   scanId: string | null
+  runtimeEnvironmentId?: string | null
 }) => void
 
 export function useAddRepoServerPathFlow({
   addRepoPath,
+  activeRuntimeEnvironmentId,
   closeModal,
   fetchWorktrees,
   getNestedRepoRuntimeKind,
@@ -33,19 +38,32 @@ export function useAddRepoServerPathFlow({
   onGitRepoReady,
   setAddProjectBusyLabel
 }: {
-  addRepoPath: (path: string, kind?: 'git' | 'folder') => Promise<Repo | null>
+  addRepoPath: (
+    path: string,
+    kind?: 'git' | 'folder',
+    options?: { runtimeEnvironmentId?: string | null }
+  ) => Promise<Repo | null>
+  activeRuntimeEnvironmentId: string | null
   closeModal: () => void
-  fetchWorktrees: (repoId: string, options?: { requireAuthoritative?: boolean }) => Promise<unknown>
+  fetchWorktrees: (repoId: string, options?: WorktreeFetchOptions) => Promise<unknown>
   getNestedRepoRuntimeKind: (connectionId: string | null) => NestedRepoTelemetryRuntimeKind
   scanNestedRepos: (
     path: string,
     connectionId?: string,
-    controls?: { scanId?: string; onProgress?: (scan: NestedRepoScanResult) => void }
+    controls?: {
+      scanId?: string
+      onProgress?: (scan: NestedRepoScanResult) => void
+      runtimeEnvironmentId?: string | null
+    }
   ) => Promise<NestedRepoScanResult | null>
-  setActiveNestedScanId: (scanId: string | null) => void
+  setActiveNestedScanId: (scanId: string | null, runtimeEnvironmentId?: string | null) => void
   setNestedScanInProgress: (inProgress: boolean) => void
   showNestedRepoReview: ShowNestedRepoReview
-  onGitRepoReady: (repoId: string, source: AddRepoExistingWorkspaceSource) => Promise<void>
+  onGitRepoReady: (
+    repoId: string,
+    source: AddRepoExistingWorkspaceSource,
+    executionHostId?: ExecutionHostId
+  ) => Promise<void>
   setAddProjectBusyLabel: (label: string | null) => void
 }): {
   serverPath: string
@@ -80,16 +98,15 @@ export function useAddRepoServerPathFlow({
           const supportsStreamingScan = runtimeKind !== 'runtime'
           const scanId = supportsStreamingScan ? createNestedRepoScanId() : null
           if (scanId) {
-            setActiveNestedScanId(scanId)
+            setActiveNestedScanId(scanId, activeRuntimeEnvironmentId)
             setNestedScanInProgress(true)
           }
-          const scan = await scanNestedRepos(
-            path,
-            undefined,
-            scanId
+          const scan = await scanNestedRepos(path, undefined, {
+            runtimeEnvironmentId: activeRuntimeEnvironmentId,
+            ...(scanId
               ? {
                   scanId,
-                  onProgress: (progressScan) => {
+                  onProgress: (progressScan: NestedRepoScanResult) => {
                     if (
                       gen !== serverAddGenRef.current ||
                       progressScan.selectedPathKind !== 'non_git_folder' ||
@@ -104,12 +121,13 @@ export function useAddRepoServerPathFlow({
                       attemptId,
                       runtimeKind,
                       inProgress: true,
-                      scanId
+                      scanId,
+                      runtimeEnvironmentId: activeRuntimeEnvironmentId
                     })
                   }
                 }
-              : undefined
-          )
+              : {})
+          })
           if (gen !== serverAddGenRef.current) {
             return
           }
@@ -132,24 +150,28 @@ export function useAddRepoServerPathFlow({
               attemptId,
               runtimeKind,
               inProgress: false,
-              scanId
+              scanId,
+              runtimeEnvironmentId: activeRuntimeEnvironmentId
             })
             return
           }
         }
         setAddProjectBusyLabel(kind === 'git' ? 'Opening project...' : 'Opening folder...')
-        const repo = await addRepoPath(path, kind)
+        const repo = await addRepoPath(path, kind, {
+          runtimeEnvironmentId: activeRuntimeEnvironmentId
+        })
         if (gen !== serverAddGenRef.current) {
           return
         }
         if (repo && isGitRepoKind(repo)) {
           // Why: once the repo exists, a transient non-authoritative refresh
           // should fall through to project reveal instead of leaving the add flow open.
-          await fetchWorktrees(repo.id, { requireAuthoritative: true })
+          const ownerOptions = worktreeRefreshOptions(activeRuntimeEnvironmentId ?? null)
+          await fetchWorktrees(repo.id, ownerOptions)
           if (gen !== serverAddGenRef.current) {
             return
           }
-          await onGitRepoReady(repo.id, 'runtime_server_path')
+          await onGitRepoReady(repo.id, 'runtime_server_path', ownerOptions.executionHostId)
         } else if (repo) {
           // Why: folder repos skip the Git default-checkout handoff; their synthetic
           // root workspace is opened by the folder add flow.
@@ -167,6 +189,7 @@ export function useAddRepoServerPathFlow({
     },
     [
       addRepoPath,
+      activeRuntimeEnvironmentId,
       closeModal,
       fetchWorktrees,
       getNestedRepoRuntimeKind,
diff --git a/src/renderer/src/components/sidebar/useCreateRepo.default-checkout.test.ts b/src/renderer/src/components/sidebar/useCreateRepo.default-checkout.test.ts
index 51a5ad755b5..832ce5b26dc 100644
--- a/src/renderer/src/components/sidebar/useCreateRepo.default-checkout.test.ts
+++ b/src/renderer/src/components/sidebar/useCreateRepo.default-checkout.test.ts
@@ -240,13 +240,18 @@ describe('useCreateRepo default-checkout handoff', () => {
     })
     expect(mocks.createRepo).not.toHaveBeenCalled()
     expect(mocks.fetchWorktrees).toHaveBeenCalledWith(repo.id, {
-      requireAuthoritative: true
+      requireAuthoritative: true,
+      executionHostId: 'ssh:ssh-1'
     })
-    expect(mocks.onGitRepoReady).toHaveBeenCalledWith(repo.id)
+    expect(mocks.storeState.repos).toContainEqual({
+      ...repo,
+      executionHostId: 'ssh:ssh-1'
+    })
+    expect(mocks.onGitRepoReady).toHaveBeenCalledWith(repo.id, 'ssh:ssh-1')
   })
 
   it('creates projects through the selected runtime environment', async () => {
-    const repo = makeRepo({ executionHostId: 'runtime:env-1', path: '/srv/created' })
+    const repo = makeRepo({ path: '/srv/created' })
     mocks.callRuntimeRpc.mockResolvedValue({ repo })
     mocks.fetchWorktrees.mockResolvedValue(true)
     const { useCreateRepo } = await import('./useCreateRepo')
@@ -270,8 +275,13 @@ describe('useCreateRepo default-checkout handoff', () => {
     expect(mocks.createRepo).not.toHaveBeenCalled()
     expect(mocks.createRemoteRepo).not.toHaveBeenCalled()
     expect(mocks.fetchWorktrees).toHaveBeenCalledWith(repo.id, {
-      requireAuthoritative: true
+      requireAuthoritative: true,
+      executionHostId: 'runtime:env-1'
     })
-    expect(mocks.onGitRepoReady).toHaveBeenCalledWith(repo.id)
+    expect(mocks.storeState.repos).toContainEqual({
+      ...repo,
+      executionHostId: 'runtime:env-1'
+    })
+    expect(mocks.onGitRepoReady).toHaveBeenCalledWith(repo.id, 'runtime:env-1')
   })
 })
diff --git a/src/renderer/src/components/sidebar/useCreateRepo.ts b/src/renderer/src/components/sidebar/useCreateRepo.ts
index abf35db7e66..a9c6c8c6525 100644
--- a/src/renderer/src/components/sidebar/useCreateRepo.ts
+++ b/src/renderer/src/components/sidebar/useCreateRepo.ts
@@ -12,14 +12,16 @@ import type { Repo } from '../../../../shared/types'
 import { translate } from '@/i18n/i18n'
 import { extractIpcErrorMessage } from '@/lib/ipc-error'
 import { upsertAddedRepoWithProjectHostSetup } from './add-repo-store-upsert'
+import { worktreeRefreshOptions } from './add-repo-runtime-owner'
+import type { ExecutionHostId } from '../../../../shared/execution-host'
 
 export function useCreateRepo(
   fetchWorktrees: (
     repoId: string,
-    options?: { requireAuthoritative?: boolean }
+    options?: { requireAuthoritative?: boolean; executionHostId?: ExecutionHostId }
   ) => Promise<boolean>,
   closeModal: () => void,
-  onGitRepoReady?: (repoId: string) => void | Promise<void>,
+  onGitRepoReady?: (repoId: string, executionHostId?: ExecutionHostId) => void | Promise<void>,
   options: {
     hostId?: string | null
     runtimeEnvironmentId?: string | null
@@ -137,15 +139,17 @@ export function useCreateRepo(
         setCreateError(result.error)
         return
       }
-      const repo = result.repo
-      const state = useAppStore.getState()
-      const existingIdx = state.repos.findIndex((r) => r.id === repo.id)
+      const { alreadyPresent: wasDeduped, repo } = upsertAddedRepoWithProjectHostSetup(
+        result.repo,
+        {
+          runtimeEnvironmentId: options.runtimeEnvironmentId,
+          sshConnectionId: options.sshTargetId
+        }
+      )
       // Why: the IPC handler dedupes by path (see repos:create) and returns
-      // the existing repo unchanged. If its ID is already in our store, the
+      // the existing repo unchanged. If its host identity is already in our store, the
       // handler took the dedup path — no new project was created, so don't
       // claim one was.
-      const wasDeduped = existingIdx !== -1
-      upsertAddedRepoWithProjectHostSetup(repo)
       if (wasDeduped) {
         toast.info(
           translate(
@@ -168,7 +172,11 @@ export function useCreateRepo(
         // Why: Git repos use the shared default-checkout completion path.
         // Why: if refresh is temporarily non-authoritative, the shared opener
         // still reveals the project so the user is not left in a completed add flow.
-        await fetchWorktrees(repo.id, { requireAuthoritative: true })
+        const ownerOptions = worktreeRefreshOptions(
+          options.runtimeEnvironmentId,
+          options.sshTargetId
+        )
+        await fetchWorktrees(repo.id, ownerOptions)
         if (
           gen !== createGenRef.current ||
           requestHostToken !== hostTokenRef.current ||
@@ -176,11 +184,19 @@ export function useCreateRepo(
         ) {
           return
         }
-        await onGitRepoReady?.(repo.id)
+        await (ownerOptions.executionHostId
+          ? onGitRepoReady?.(repo.id, ownerOptions.executionHostId)
+          : onGitRepoReady?.(repo.id))
       } else {
         // Why: folder repos skip the Git default-checkout handoff, so activate the synthetic
         // root workspace before closing. Matches addNonGitFolder's behavior.
-        await fetchWorktrees(repo.id)
+        const ownerOptions = worktreeRefreshOptions(
+          options.runtimeEnvironmentId,
+          options.sshTargetId
+        )
+        await (ownerOptions.executionHostId
+          ? fetchWorktrees(repo.id, { executionHostId: ownerOptions.executionHostId })
+          : fetchWorktrees(repo.id))
         if (
           gen !== createGenRef.current ||
           requestHostToken !== hostTokenRef.current ||
@@ -188,9 +204,20 @@ export function useCreateRepo(
         ) {
           return
         }
-        const folderWorktree = useAppStore.getState().worktreesByRepo[repo.id]?.[0]
+        const folderWorktree = useAppStore
+          .getState()
+          .worktreesByRepo[repo.id]?.find(
+            (worktree) =>
+              ownerOptions.executionHostId === undefined ||
+              worktree.hostId === ownerOptions.executionHostId
+          )
         if (folderWorktree) {
-          activateAndRevealWorktree(folderWorktree.id, { sidebarRevealBehavior: 'auto' })
+          activateAndRevealWorktree(folderWorktree.id, {
+            sidebarRevealBehavior: 'auto',
+            ...(ownerOptions.executionHostId
+              ? { executionHostId: ownerOptions.executionHostId }
+              : {})
+          })
         }
         await markOnboardingProjectAdded('addedFolder')
         closeModal()
diff --git a/src/renderer/src/components/sidebar/worktree-list-host-filtering.ts b/src/renderer/src/components/sidebar/worktree-list-host-filtering.ts
index 30273957969..655c4e4f2ff 100644
--- a/src/renderer/src/components/sidebar/worktree-list-host-filtering.ts
+++ b/src/renderer/src/components/sidebar/worktree-list-host-filtering.ts
@@ -72,10 +72,14 @@ export function getFolderWorkspaceExecutionHostIdForRows({
   projectGroup,
   defaultHostId
 }: {
-  folderWorkspace: Pick<FolderWorkspace, 'connectionId'>
+  folderWorkspace: Pick<FolderWorkspace, 'connectionId' | 'executionHostId'>
   projectGroup: Pick<ProjectGroup, 'connectionId' | 'executionHostId'> | undefined
   defaultHostId: ExecutionHostId
 }): ExecutionHostId {
+  const explicitFolderHostId = normalizeExecutionHostId(folderWorkspace.executionHostId)
+  if (explicitFolderHostId) {
+    return explicitFolderHostId
+  }
   if (projectGroup) {
     const explicitProjectGroupHostId = normalizeExecutionHostId(projectGroup.executionHostId)
     if (explicitProjectGroupHostId) {
@@ -132,7 +136,7 @@ export function getFolderPathStatusRouteOptionsForRows({
     request.scope === 'project-group'
       ? getProjectGroupExecutionHostIdForFolderPathStatus(group)
       : getFolderWorkspaceExecutionHostIdForRows({
-          folderWorkspace: folderWorkspace ?? { connectionId: null },
+          folderWorkspace: folderWorkspace ?? { connectionId: null, executionHostId: null },
           projectGroup: group,
           defaultHostId: getProjectGroupExecutionHostIdForFolderPathStatus(group)
         })
diff --git a/src/renderer/src/hooks/runtime-project-refresh-scheduler.test.ts b/src/renderer/src/hooks/runtime-project-refresh-scheduler.test.ts
index 55cb0f28674..8b20968441c 100644
--- a/src/renderer/src/hooks/runtime-project-refresh-scheduler.test.ts
+++ b/src/renderer/src/hooks/runtime-project-refresh-scheduler.test.ts
@@ -1,5 +1,28 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { createRuntimeProjectRefreshScheduler } from './runtime-project-refresh-scheduler'
+import {
+  createRuntimeProjectRefreshScheduler,
+  refreshRuntimeProjectWorktrees
+} from './runtime-project-refresh-scheduler'
+
+describe('refreshRuntimeProjectWorktrees', () => {
+  it('pins same-ID repo refreshes to the event runtime', async () => {
+    const fetchWorktrees = vi.fn().mockResolvedValue(true)
+
+    await refreshRuntimeProjectWorktrees(
+      'env-1',
+      [{ id: 'same-repo' }, { id: 'same-repo' }],
+      fetchWorktrees
+    )
+
+    expect(fetchWorktrees).toHaveBeenCalledTimes(2)
+    expect(fetchWorktrees).toHaveBeenNthCalledWith(1, 'same-repo', {
+      executionHostId: 'runtime:env-1'
+    })
+    expect(fetchWorktrees).toHaveBeenNthCalledWith(2, 'same-repo', {
+      executionHostId: 'runtime:env-1'
+    })
+  })
+})
 
 describe('createRuntimeProjectRefreshScheduler', () => {
   beforeEach(() => {
diff --git a/src/renderer/src/hooks/runtime-project-refresh-scheduler.ts b/src/renderer/src/hooks/runtime-project-refresh-scheduler.ts
index 46bf354667f..e02305d20eb 100644
--- a/src/renderer/src/hooks/runtime-project-refresh-scheduler.ts
+++ b/src/renderer/src/hooks/runtime-project-refresh-scheduler.ts
@@ -1,3 +1,5 @@
+import { toRuntimeExecutionHostId, type ExecutionHostId } from '../../../shared/execution-host'
+
 export type RuntimeProjectRefreshSchedulerDeps = {
   refresh: (environmentId: string) => Promise<void>
   debounceMs?: number
@@ -20,6 +22,46 @@ type RefreshEntry = {
 
 const DEFAULT_DEBOUNCE_MS = 250
 const DEFAULT_MIN_INTERVAL_MS = 5_000
+const DEFAULT_REFRESH_CONCURRENCY = 5
+
+export async function refreshRuntimeProjectWorktrees(
+  environmentId: string,
+  repos: readonly { id: string }[],
+  fetchWorktrees: (
+    repoId: string,
+    options: { executionHostId: ExecutionHostId }
+  ) => Promise<unknown>,
+  concurrency = DEFAULT_REFRESH_CONCURRENCY
+): Promise<void> {
+  let nextIndex = 0
+  const failures: { repoId: string; error: unknown }[] = []
+  const workerCount = Math.min(concurrency, repos.length)
+  const executionHostId = toRuntimeExecutionHostId(environmentId)
+
+  // Why: one coalesced event can represent many repos; bound probes without dropping host identity.
+  await Promise.all(
+    Array.from({ length: workerCount }, async () => {
+      while (nextIndex < repos.length) {
+        const index = nextIndex
+        nextIndex += 1
+        const repoId = repos[index].id
+        try {
+          await fetchWorktrees(repoId, { executionHostId })
+        } catch (error) {
+          failures.push({ repoId, error })
+        }
+      }
+    })
+  )
+  if (failures.length > 0) {
+    throw new AggregateError(
+      failures.map((failure) => failure.error),
+      `Failed to refresh ${failures.length} runtime project worktree(s): ${failures
+        .map((failure) => failure.repoId)
+        .join(', ')}`
+    )
+  }
+}
 
 export function createRuntimeProjectRefreshScheduler(
   deps: RuntimeProjectRefreshSchedulerDeps
diff --git a/src/renderer/src/hooks/useIpcEvents.test.ts b/src/renderer/src/hooks/useIpcEvents.test.ts
index cfc4bd5d8fc..1d956f716cb 100644
--- a/src/renderer/src/hooks/useIpcEvents.test.ts
+++ b/src/renderer/src/hooks/useIpcEvents.test.ts
@@ -4904,7 +4904,7 @@ describe('useIpcEvents CLI-created worktree activation', () => {
 
     fetchWorktrees.mockClear()
     fetchWorktreeLineage.mockClear()
-    mockSettings.activeRuntimeEnvironmentId = 'env-1'
+    mockSettings.activeRuntimeEnvironmentId = null
     if (!runtimeOnResponse) {
       throw new Error('Expected runtime client event callbacks')
     }
@@ -4915,8 +4915,12 @@ describe('useIpcEvents CLI-created worktree activation', () => {
     await new Promise((resolve) => setTimeout(resolve, 0))
     await new Promise((resolve) => setTimeout(resolve, 0))
 
-    expect(fetchWorktrees).toHaveBeenCalledWith('repo-1', undefined)
-    expect(fetchWorktreeLineage).toHaveBeenCalledWith(undefined)
+    expect(fetchWorktrees).toHaveBeenCalledWith('repo-1', {
+      executionHostId: 'runtime:env-1'
+    })
+    expect(fetchWorktreeLineage).toHaveBeenCalledWith({
+      executionHostId: 'runtime:env-1'
+    })
   })
 })
 
diff --git a/src/renderer/src/hooks/useIpcEvents.ts b/src/renderer/src/hooks/useIpcEvents.ts
index ba500554ae2..3c8b19068c2 100644
--- a/src/renderer/src/hooks/useIpcEvents.ts
+++ b/src/renderer/src/hooks/useIpcEvents.ts
@@ -31,7 +31,11 @@ import type {
 } from '../../../shared/types'
 import type { RateLimitState } from '../../../shared/rate-limit-types'
 import type { DirectSshAuthority, SshConnectionState } from '../../../shared/ssh-types'
-import { toSshExecutionHostId } from '../../../shared/execution-host'
+import {
+  toRuntimeExecutionHostId,
+  toSshExecutionHostId,
+  type ExecutionHostId
+} from '../../../shared/execution-host'
 import { isWslHookRelayConnectionId } from '../../../shared/wsl-hook-relay-contract'
 import type {
   RuntimeBrowserDriverState,
@@ -96,7 +100,10 @@ import {
   applyRuntimeEnvironmentSshStateChanged,
   hydrateRuntimeEnvironmentSshState
 } from '@/runtime/runtime-environment-ssh-state'
-import { createRuntimeProjectRefreshScheduler } from './runtime-project-refresh-scheduler'
+import {
+  createRuntimeProjectRefreshScheduler,
+  refreshRuntimeProjectWorktrees
+} from './runtime-project-refresh-scheduler'
 import { createRuntimeClientEventsSync } from './runtime-client-events-sync'
 import { detectLanguage } from '@/lib/language-detect'
 import { makePaneKey, parsePaneKey } from '../../../shared/stable-pane-id'
@@ -184,7 +191,6 @@ function getShortcutPlatform(): NodeJS.Platform {
 }
 
 const BROWSER_AUTOMATION_BOOTSTRAP_LEASE_MS = 10_000
-const RUNTIME_PROJECT_REFRESH_CONCURRENCY = 5
 const browserAutomationBootstrapLeaseByPageId = new Map<string, { token: string; timer: number }>()
 
 function resolveTerminalPresentation(data: {
@@ -588,36 +594,6 @@ export function getRuntimeProjectRefreshEnvironmentIds(args: {
   ]
 }
 
-async function refreshRuntimeProjectWorktrees(repos: readonly { id: string }[]): Promise<void> {
-  let nextIndex = 0
-  const failures: { repoId: string; error: unknown }[] = []
-  const workerCount = Math.min(RUNTIME_PROJECT_REFRESH_CONCURRENCY, repos.length)
-
-  // Why: one coalesced repo event can represent many repos; bound the probes so idle refresh never floods the renderer.
-  await Promise.all(
-    Array.from({ length: workerCount }, async () => {
-      while (nextIndex < repos.length) {
-        const index = nextIndex
-        nextIndex += 1
-        const repoId = repos[index].id
-        try {
-          await useAppStore.getState().fetchWorktrees(repoId)
-        } catch (error) {
-          failures.push({ repoId, error })
-        }
-      }
-    })
-  )
-  if (failures.length > 0) {
-    throw new AggregateError(
-      failures.map((failure) => failure.error),
-      `Failed to refresh ${failures.length} runtime project worktree(s): ${failures
-        .map((failure) => failure.repoId)
-        .join(', ')}`
-    )
-  }
-}
-
 function getWorktreeRuntimeEnvironmentId(worktreeId: string | null | undefined): string | null {
   return getRuntimeEnvironmentIdForWorktree(useAppStore.getState(), worktreeId)
 }
@@ -788,7 +764,7 @@ export function useIpcEvents(): void {
     const handleWorktreesChanged = async (
       repoId: string,
       renamed?: { oldWorktreeId: string; newWorktreeId: string },
-      options?: { forceLocalOwner?: boolean }
+      options?: { forceLocalOwner?: boolean; executionHostId?: ExecutionHostId }
     ): Promise<void> => {
       const localRefreshStartedWithRuntime =
         options?.forceLocalOwner === true && isRuntimeEnvironmentActive()
@@ -809,11 +785,21 @@ export function useIpcEvents(): void {
         getVisibleWorktreeIdsForRepo(state, repoId)
       await state.fetchWorktrees(
         repoId,
-        options?.forceLocalOwner ? { forceLocalOwner: true } : undefined
+        options?.forceLocalOwner
+          ? { forceLocalOwner: true }
+          : options?.executionHostId
+            ? { executionHostId: options.executionHostId }
+            : undefined
       )
       await useAppStore
         .getState()
-        .fetchWorktreeLineage(options?.forceLocalOwner ? { forceLocalOwner: true } : undefined)
+        .fetchWorktreeLineage(
+          options?.forceLocalOwner
+            ? { forceLocalOwner: true }
+            : options?.executionHostId
+              ? { executionHostId: options.executionHostId }
+              : undefined
+        )
       // Why: an id change unmounts the active pane; re-activate so the tab reconciles, else it vanishes until re-select.
       if (renamedWasActive && renamed) {
         useAppStore.getState().setActiveWorktree(renamed.newWorktreeId)
@@ -909,8 +895,12 @@ export function useIpcEvents(): void {
         // Why: refresh the env's SSH bucket on (re)connect so a pre-drop snapshot can't keep a reconnect overlay stale.
         void hydrateRuntimeEnvironmentSshState(environmentId, { force: true }).catch(() => {})
         const repos = await useAppStore.getState().fetchRuntimeEnvironmentRepos(environmentId)
-        await refreshRuntimeProjectWorktrees(repos)
-        await useAppStore.getState().fetchWorktreeLineage()
+        await refreshRuntimeProjectWorktrees(environmentId, repos, (repoId, options) =>
+          useAppStore.getState().fetchWorktrees(repoId, options)
+        )
+        await useAppStore.getState().fetchWorktreeLineage({
+          executionHostId: toRuntimeExecutionHostId(environmentId)
+        })
       },
       onError: (error) => {
         console.error('Failed to refresh runtime projects:', error)
@@ -956,7 +946,10 @@ export function useIpcEvents(): void {
       }
       if (event.type === 'worktreesChanged') {
         void ensureRuntimeEventRepoKnown(environmentId, event.repoId).then(() =>
-          worktreeChangeRefreshQueue.enqueue({ repoId: event.repoId })
+          worktreeChangeRefreshQueue.enqueue({
+            repoId: event.repoId,
+            executionHostId: toRuntimeExecutionHostId(environmentId)
+          })
         )
         return
       }
diff --git a/src/renderer/src/hooks/worktree-change-refresh-queue.test.ts b/src/renderer/src/hooks/worktree-change-refresh-queue.test.ts
index 7c04b18cfca..c0422585975 100644
--- a/src/renderer/src/hooks/worktree-change-refresh-queue.test.ts
+++ b/src/renderer/src/hooks/worktree-change-refresh-queue.test.ts
@@ -173,6 +173,29 @@ describe('createWorktreeChangeRefreshQueue', () => {
     expect(handler).toHaveBeenNthCalledWith(3, 'repo-1', undefined, { forceLocalOwner: true })
   })
 
+  it('does not coalesce same-ID refreshes from different runtime hosts', async () => {
+    const firstRefresh = deferred()
+    const handler = vi.fn().mockReturnValueOnce(firstRefresh.promise).mockResolvedValue(undefined)
+    const queue = createWorktreeChangeRefreshQueue(handler)
+
+    queue.enqueue({ repoId: 'same-repo', executionHostId: 'runtime:env-1' })
+    queue.enqueue({ repoId: 'same-repo', executionHostId: 'runtime:env-1' })
+    queue.enqueue({ repoId: 'same-repo', executionHostId: 'runtime:env-2' })
+
+    firstRefresh.resolve()
+    await flushPromises()
+
+    expect(handler).toHaveBeenCalledTimes(3)
+    expect(handler).toHaveBeenNthCalledWith(2, 'same-repo', undefined, {
+      forceLocalOwner: undefined,
+      executionHostId: 'runtime:env-1'
+    })
+    expect(handler).toHaveBeenNthCalledWith(3, 'same-repo', undefined, {
+      forceLocalOwner: undefined,
+      executionHostId: 'runtime:env-2'
+    })
+  })
+
   it('drops queued trailing refreshes after disposal', async () => {
     const firstRefresh = deferred()
     const handler = vi.fn().mockReturnValueOnce(firstRefresh.promise).mockResolvedValue(undefined)
diff --git a/src/renderer/src/hooks/worktree-change-refresh-queue.ts b/src/renderer/src/hooks/worktree-change-refresh-queue.ts
index ef69da6dd05..b3ff2b58638 100644
--- a/src/renderer/src/hooks/worktree-change-refresh-queue.ts
+++ b/src/renderer/src/hooks/worktree-change-refresh-queue.ts
@@ -1,26 +1,31 @@
+import type { ExecutionHostId } from '../../../shared/execution-host'
+
 type WorktreeRename = {
   oldWorktreeId: string
   newWorktreeId: string
 }
 
+type WorktreeChangeOwner = {
+  forceLocalOwner?: boolean
+  executionHostId?: ExecutionHostId
+}
+
 type WorktreeChangeEvent = {
   repoId: string
   renamed?: WorktreeRename
   // Why: set on local worktrees:changed while a remote runtime is active, so the
   // refresh pins to the local host instead of dropping the event (see useIpcEvents).
   forceLocalOwner?: boolean
+  executionHostId?: ExecutionHostId
 }
 
 type WorktreeChangeRefreshHandler = (
   repoId: string,
   renamed?: WorktreeRename,
-  options?: { forceLocalOwner?: boolean }
+  options?: WorktreeChangeOwner
 ) => Promise<void>
 
-type QueuedWorktreeChange = {
-  renamed?: WorktreeRename
-  forceLocalOwner?: boolean
-}
+type QueuedWorktreeChange = WorktreeChangeOwner & { renamed?: WorktreeRename }
 
 type RepoRefreshState = {
   running: boolean
@@ -44,7 +49,10 @@ export function createWorktreeChangeRefreshQueue(
       while (!disposed && state.queue.length > 0) {
         const next = state.queue.shift()
         try {
-          await handler(repoId, next?.renamed, { forceLocalOwner: next?.forceLocalOwner })
+          await handler(repoId, next?.renamed, {
+            forceLocalOwner: next?.forceLocalOwner,
+            ...(next?.executionHostId ? { executionHostId: next.executionHostId } : {})
+          })
         } catch (error) {
           console.error('Failed to refresh changed worktrees:', error)
         }
@@ -76,7 +84,11 @@ export function createWorktreeChangeRefreshQueue(
       }
 
       if (event.renamed) {
-        state.queue.push({ renamed: event.renamed, forceLocalOwner: event.forceLocalOwner })
+        state.queue.push({
+          renamed: event.renamed,
+          forceLocalOwner: event.forceLocalOwner,
+          executionHostId: event.executionHostId
+        })
       } else {
         const lastQueued = state.queue.at(-1)
         // Why: Windows/OneDrive can emit a burst for one checkout change. Keep a
@@ -86,9 +98,13 @@ export function createWorktreeChangeRefreshQueue(
         if (
           !lastQueued ||
           lastQueued.renamed !== undefined ||
-          Boolean(lastQueued.forceLocalOwner) !== Boolean(event.forceLocalOwner)
+          Boolean(lastQueued.forceLocalOwner) !== Boolean(event.forceLocalOwner) ||
+          lastQueued.executionHostId !== event.executionHostId
         ) {
-          state.queue.push({ forceLocalOwner: event.forceLocalOwner })
+          state.queue.push({
+            forceLocalOwner: event.forceLocalOwner,
+            executionHostId: event.executionHostId
+          })
         }
       }
 
diff --git a/src/renderer/src/lib/ai-vault-resume-target.ts b/src/renderer/src/lib/ai-vault-resume-target.ts
index 3c9206ae372..fca20f25cc8 100644
--- a/src/renderer/src/lib/ai-vault-resume-target.ts
+++ b/src/renderer/src/lib/ai-vault-resume-target.ts
@@ -178,7 +178,7 @@ function getAiVaultResumeFolderTargetStatus(
   }
 
   const group = state.projectGroups.find((entry) => entry.id === workspace.projectGroupId)
-  const groupHostId = normalizeExecutionHostId(group?.executionHostId)
+  const groupHostId = normalizeExecutionHostId(workspace.executionHostId ?? group?.executionHostId)
   if (groupHostId) {
     return getAiVaultResumeExecutionHostTargetStatus(groupHostId)
   }
@@ -202,7 +202,7 @@ function getAiVaultResumeFolderExecutionHostId(
   }
 
   const group = state.projectGroups.find((entry) => entry.id === workspace.projectGroupId)
-  const groupHostId = normalizeExecutionHostId(group?.executionHostId)
+  const groupHostId = normalizeExecutionHostId(workspace.executionHostId ?? group?.executionHostId)
   if (groupHostId) {
     return groupHostId
   }
diff --git a/src/renderer/src/lib/direct-ssh-target-scope-types.ts b/src/renderer/src/lib/direct-ssh-target-scope-types.ts
index e063a64c42c..1c12e0a25c5 100644
--- a/src/renderer/src/lib/direct-ssh-target-scope-types.ts
+++ b/src/renderer/src/lib/direct-ssh-target-scope-types.ts
@@ -31,7 +31,7 @@ export type DirectSshWorktreeOwner = Pick<
 >
 export type DirectSshFolderOwner = Pick<
   FolderWorkspace,
-  'id' | 'projectGroupId' | 'folderPath' | 'connectionId'
+  'id' | 'projectGroupId' | 'folderPath' | 'connectionId' | 'executionHostId'
 >
 export type DirectSshGroupOwner = Pick<
   ProjectGroup,
diff --git a/src/renderer/src/lib/folder-workspace-connection.ts b/src/renderer/src/lib/folder-workspace-connection.ts
index 6b74c701f85..4afb696d700 100644
--- a/src/renderer/src/lib/folder-workspace-connection.ts
+++ b/src/renderer/src/lib/folder-workspace-connection.ts
@@ -1,6 +1,7 @@
 import type { FolderWorkspace, ProjectGroup, Repo } from '../../../shared/types'
 import { isPathInsideOrEqual } from '../../../shared/cross-platform-path'
 import { getProjectGroupSubtreeIds } from '../../../shared/project-groups'
+import { parseExecutionHostId } from '../../../shared/execution-host'
 
 export type FolderWorkspaceConnectionState = {
   folderWorkspaces: FolderWorkspace[]
@@ -66,6 +67,10 @@ export function getFolderWorkspaceConnectionId(
   if (!workspace) {
     return undefined
   }
+  const explicitHost = parseExecutionHostId(workspace.executionHostId)
+  if (explicitHost) {
+    return explicitHost.kind === 'ssh' ? explicitHost.targetId : null
+  }
   const scopeConnectionId =
     workspace.connectionId ??
     state.projectGroups.find((entry) => entry.id === workspace.projectGroupId)?.connectionId ??
diff --git a/src/renderer/src/lib/folder-workspace-runtime-owner.ts b/src/renderer/src/lib/folder-workspace-runtime-owner.ts
index eaa36c44e2e..4bf99a1b780 100644
--- a/src/renderer/src/lib/folder-workspace-runtime-owner.ts
+++ b/src/renderer/src/lib/folder-workspace-runtime-owner.ts
@@ -14,27 +14,60 @@ import {
 type RuntimeExecutionHost = Extract<ParsedExecutionHost, { kind: 'runtime' }>
 
 export type FolderWorkspaceRuntimeOwnerState = SingleRuntimeLegacyOwnerState & {
-  folderWorkspaces?: readonly Pick<FolderWorkspace, 'id' | 'projectGroupId' | 'connectionId'>[]
+  folderWorkspaces?: readonly Pick<
+    FolderWorkspace,
+    'id' | 'projectGroupId' | 'connectionId' | 'executionHostId'
+  >[]
   projectGroups?: readonly Pick<ProjectGroup, 'id' | 'connectionId' | 'executionHostId'>[]
   restoredRuntimeHostIdByWorkspaceSessionKey?: Record<string, ExecutionHostId>
+  activeWorktreeId?: string | null
+  activeWorkspaceExecutionHostId?: ExecutionHostId | null
+}
+
+function getPreferredFolderExecutionHostId(
+  state: FolderWorkspaceRuntimeOwnerState,
+  folderWorkspaceId: string,
+  executionHostId?: ExecutionHostId
+): ExecutionHostId | undefined {
+  if (executionHostId) {
+    return executionHostId
+  }
+  return state.activeWorktreeId === folderWorkspaceKey(folderWorkspaceId)
+    ? (state.activeWorkspaceExecutionHostId ?? undefined)
+    : undefined
 }
 
 export function findFolderWorkspaceOwner(
   state: FolderWorkspaceRuntimeOwnerState,
-  folderWorkspaceId: string
-): Pick<FolderWorkspace, 'id' | 'projectGroupId' | 'connectionId'> | null {
-  return findIndexedFolderWorkspaceOwner(state.folderWorkspaces, folderWorkspaceId)
+  folderWorkspaceId: string,
+  executionHostId?: ExecutionHostId
+): Pick<FolderWorkspace, 'id' | 'projectGroupId' | 'connectionId' | 'executionHostId'> | null {
+  return findIndexedFolderWorkspaceOwner(
+    state.folderWorkspaces,
+    folderWorkspaceId,
+    getPreferredFolderExecutionHostId(state, folderWorkspaceId, executionHostId)
+  )
 }
 
 function findFolderProjectGroup(
   state: FolderWorkspaceRuntimeOwnerState,
-  folderWorkspaceId: string
+  folderWorkspaceId: string,
+  executionHostId?: ExecutionHostId
 ): Pick<ProjectGroup, 'id' | 'connectionId' | 'executionHostId'> | null {
-  const folderWorkspace = findFolderWorkspaceOwner(state, folderWorkspaceId)
+  const preferredHostId = getPreferredFolderExecutionHostId(
+    state,
+    folderWorkspaceId,
+    executionHostId
+  )
+  const folderWorkspace = findFolderWorkspaceOwner(state, folderWorkspaceId, preferredHostId)
   if (!folderWorkspace) {
     return null
   }
-  return findIndexedProjectGroupOwner(state.projectGroups, folderWorkspace.projectGroupId)
+  return findIndexedProjectGroupOwner(
+    state.projectGroups,
+    folderWorkspace.projectGroupId,
+    preferredHostId
+  )
 }
 
 function getRestoredRuntimeHostForFolderWorkspace(
@@ -52,11 +85,14 @@ function getRestoredRuntimeHostForFolderWorkspace(
 
 export function getRuntimeEnvironmentIdForFolderWorkspace(
   state: FolderWorkspaceRuntimeOwnerState,
-  folderWorkspaceId: string
+  folderWorkspaceId: string,
+  executionHostId?: ExecutionHostId
 ): string | null {
-  const folderWorkspace = findFolderWorkspaceOwner(state, folderWorkspaceId)
-  const projectGroup = findFolderProjectGroup(state, folderWorkspaceId)
-  const parsed = parseExecutionHostId(projectGroup?.executionHostId)
+  const folderWorkspace = findFolderWorkspaceOwner(state, folderWorkspaceId, executionHostId)
+  const projectGroup = findFolderProjectGroup(state, folderWorkspaceId, executionHostId)
+  const parsed = parseExecutionHostId(
+    folderWorkspace?.executionHostId ?? projectGroup?.executionHostId
+  )
   if (parsed?.kind === 'runtime') {
     return parsed.environmentId
   }
@@ -77,11 +113,14 @@ export function getRuntimeEnvironmentIdForFolderWorkspace(
 
 export function getExplicitRuntimeEnvironmentIdForFolderWorkspace(
   state: FolderWorkspaceRuntimeOwnerState,
-  folderWorkspaceId: string
+  folderWorkspaceId: string,
+  executionHostId?: ExecutionHostId
 ): string | null {
-  const folderWorkspace = findFolderWorkspaceOwner(state, folderWorkspaceId)
-  const projectGroup = findFolderProjectGroup(state, folderWorkspaceId)
-  const parsed = parseExecutionHostId(projectGroup?.executionHostId)
+  const folderWorkspace = findFolderWorkspaceOwner(state, folderWorkspaceId, executionHostId)
+  const projectGroup = findFolderProjectGroup(state, folderWorkspaceId, executionHostId)
+  const parsed = parseExecutionHostId(
+    folderWorkspace?.executionHostId ?? projectGroup?.executionHostId
+  )
   if (parsed) {
     return parsed.kind === 'runtime' ? parsed.environmentId : null
   }
@@ -93,11 +132,19 @@ export function getExplicitRuntimeEnvironmentIdForFolderWorkspace(
 
 export function getExecutionHostIdForFolderWorkspace(
   state: FolderWorkspaceRuntimeOwnerState,
-  folderWorkspaceId: string
+  folderWorkspaceId: string,
+  executionHostId?: ExecutionHostId
 ): ExecutionHostId {
-  const folderWorkspace = findFolderWorkspaceOwner(state, folderWorkspaceId)
-  const projectGroup = findFolderProjectGroup(state, folderWorkspaceId)
-  const parsed = parseExecutionHostId(projectGroup?.executionHostId)
+  const preferredHostId = getPreferredFolderExecutionHostId(
+    state,
+    folderWorkspaceId,
+    executionHostId
+  )
+  const folderWorkspace = findFolderWorkspaceOwner(state, folderWorkspaceId, preferredHostId)
+  const projectGroup = findFolderProjectGroup(state, folderWorkspaceId, preferredHostId)
+  const parsed = parseExecutionHostId(
+    folderWorkspace?.executionHostId ?? projectGroup?.executionHostId
+  )
   if (parsed) {
     return parsed.id
   }
@@ -105,6 +152,9 @@ export function getExecutionHostIdForFolderWorkspace(
   if (connectionId) {
     return toSshExecutionHostId(connectionId)
   }
+  if (preferredHostId && folderWorkspace) {
+    return preferredHostId
+  }
   const restoredRuntimeHost = getRestoredRuntimeHostForFolderWorkspace(state, folderWorkspaceId)
   if (restoredRuntimeHost) {
     return restoredRuntimeHost.id
diff --git a/src/renderer/src/lib/resolved-worktree-execution-host.test.ts b/src/renderer/src/lib/resolved-worktree-execution-host.test.ts
index fab9ccbf7ce..12b15d63a51 100644
--- a/src/renderer/src/lib/resolved-worktree-execution-host.test.ts
+++ b/src/renderer/src/lib/resolved-worktree-execution-host.test.ts
@@ -56,4 +56,25 @@ describe('getResolvedExecutionHostIdForWorktree', () => {
       )
     ).toBe('runtime:runtime-1')
   })
+
+  it('uses the folder host stamp when same-ID project groups exist on different hosts', () => {
+    expect(
+      getResolvedExecutionHostIdForWorktree(
+        {
+          folderWorkspaces: [
+            {
+              id: 'same-folder',
+              projectGroupId: 'same-group',
+              executionHostId: 'runtime:runtime-1'
+            }
+          ],
+          projectGroups: [
+            { id: 'same-group', executionHostId: 'local' },
+            { id: 'same-group', executionHostId: 'runtime:runtime-1' }
+          ]
+        },
+        'folder:same-folder'
+      )
+    ).toBe('runtime:runtime-1')
+  })
 })
diff --git a/src/renderer/src/lib/resolved-worktree-execution-host.ts b/src/renderer/src/lib/resolved-worktree-execution-host.ts
index df86e8f4763..8052ccec6e6 100644
--- a/src/renderer/src/lib/resolved-worktree-execution-host.ts
+++ b/src/renderer/src/lib/resolved-worktree-execution-host.ts
@@ -10,7 +10,9 @@ import {
   findIndexedFolderWorkspaceOwner,
   findIndexedProjectGroupOwner,
   findIndexedRepoOwner,
-  findIndexedWorktreeOwner
+  findIndexedRepoOwnerForHost,
+  findIndexedWorktreeOwner,
+  findIndexedWorktreeOwnerForHost
 } from './worktree-runtime-owner-index'
 import type { WorktreeRuntimeOwnerState } from './worktree-runtime-owner'
 
@@ -18,11 +20,19 @@ function getResolvedFolderHost(
   state: WorktreeRuntimeOwnerState,
   folderWorkspaceId: string
 ): ExecutionHostId | null {
-  const folder = findIndexedFolderWorkspaceOwner(state.folderWorkspaces, folderWorkspaceId)
+  const preferredHostId =
+    state.activeWorktreeId === folderWorkspaceKey(folderWorkspaceId)
+      ? (state.activeWorkspaceExecutionHostId ?? undefined)
+      : undefined
+  const folder = findIndexedFolderWorkspaceOwner(
+    state.folderWorkspaces,
+    folderWorkspaceId,
+    preferredHostId
+  )
   const group = folder
-    ? findIndexedProjectGroupOwner(state.projectGroups, folder.projectGroupId)
+    ? findIndexedProjectGroupOwner(state.projectGroups, folder.projectGroupId, preferredHostId)
     : null
-  const explicitHost = parseExecutionHostId(group?.executionHostId)
+  const explicitHost = parseExecutionHostId(folder?.executionHostId ?? group?.executionHostId)
   if (explicitHost) {
     return explicitHost.id
   }
@@ -36,7 +46,7 @@ function getResolvedFolderHost(
   if (restoredHost?.kind === 'runtime') {
     return restoredHost.id
   }
-  return folder && group ? LOCAL_EXECUTION_HOST_ID : null
+  return folder && (group || preferredHostId) ? (preferredHostId ?? LOCAL_EXECUTION_HOST_ID) : null
 }
 
 /**
@@ -57,7 +67,13 @@ export function getResolvedExecutionHostIdForWorktree(
   if (scope?.type === 'folder') {
     return getResolvedFolderHost(state, scope.folderWorkspaceId)
   }
-  const worktree = findIndexedWorktreeOwner(state.worktreesByRepo, worktreeId)
+  const preferredHostId =
+    state.activeWorktreeId === worktreeId
+      ? (state.activeWorkspaceExecutionHostId ?? undefined)
+      : undefined
+  const worktree = preferredHostId
+    ? findIndexedWorktreeOwnerForHost(state.worktreesByRepo, worktreeId, preferredHostId)
+    : findIndexedWorktreeOwner(state.worktreesByRepo, worktreeId)
   const worktreeHost = parseExecutionHostId(worktree?.hostId)
   if (worktreeHost) {
     return worktreeHost.id
@@ -65,7 +81,9 @@ export function getResolvedExecutionHostIdForWorktree(
   if (!worktree) {
     return null
   }
-  const repo = findIndexedRepoOwner(state.repos, worktree.repoId)
+  const repo = preferredHostId
+    ? findIndexedRepoOwnerForHost(state.repos, worktree.repoId, preferredHostId)
+    : findIndexedRepoOwner(state.repos, worktree.repoId)
   if (!repo) {
     return null
   }
diff --git a/src/renderer/src/lib/sidebar-worktree-activation.ts b/src/renderer/src/lib/sidebar-worktree-activation.ts
index a668909fe44..664895013b3 100644
--- a/src/renderer/src/lib/sidebar-worktree-activation.ts
+++ b/src/renderer/src/lib/sidebar-worktree-activation.ts
@@ -5,11 +5,21 @@ import {
 import { parseWorkspaceKey } from '../../../shared/workspace-scope'
 import { toast } from 'sonner'
 import { translate } from '@/i18n/i18n'
+import type { ExecutionHostId } from '../../../shared/execution-host'
 
-export async function activateWorktreeFromSidebar(worktreeId: string): Promise<void> {
+export async function activateWorktreeFromSidebar(
+  worktreeId: string,
+  executionHostId?: ExecutionHostId
+): Promise<void> {
   const workspaceScope = parseWorkspaceKey(worktreeId)
   if (workspaceScope?.type === 'folder') {
-    activateAndRevealFolderWorkspace(workspaceScope.folderWorkspaceId)
+    if (executionHostId) {
+      activateAndRevealFolderWorkspace(workspaceScope.folderWorkspaceId, {
+        executionHostId
+      })
+    } else {
+      activateAndRevealFolderWorkspace(workspaceScope.folderWorkspaceId)
+    }
     return
   }
 
@@ -37,5 +47,8 @@ export async function activateWorktreeFromSidebar(worktreeId: string): Promise<v
 
   // Why: sidebar clicks already happen on a visible row; revealing again can
   // jump duplicate pinned/canonical entries back to the first mounted copy.
-  activateAndRevealWorktree(worktreeId, { revealInSidebar: false })
+  activateAndRevealWorktree(worktreeId, {
+    revealInSidebar: false,
+    ...(executionHostId ? { executionHostId } : {})
+  })
 }
diff --git a/src/renderer/src/lib/workspace-session-host-field-ownership.ts b/src/renderer/src/lib/workspace-session-host-field-ownership.ts
index 1f5c4098e85..db1ffe835bd 100644
--- a/src/renderer/src/lib/workspace-session-host-field-ownership.ts
+++ b/src/renderer/src/lib/workspace-session-host-field-ownership.ts
@@ -15,6 +15,7 @@ export type WorkspaceSessionFieldOwnership =
 export const WORKSPACE_SESSION_FIELD_OWNERSHIP = {
   activeRepoId: 'global',
   activeWorktreeId: 'global',
+  activeWorkspaceExecutionHostId: 'global',
   activeTabId: 'global',
   browserUrlHistory: 'global',
   // Why: SSH remains local-owned, so its connection identifiers stay in the local slice.
diff --git a/src/renderer/src/lib/workspace-session-host-persistence.ts b/src/renderer/src/lib/workspace-session-host-persistence.ts
index 35c2dfc3fed..445ef2917e4 100644
--- a/src/renderer/src/lib/workspace-session-host-persistence.ts
+++ b/src/renderer/src/lib/workspace-session-host-persistence.ts
@@ -21,7 +21,11 @@ import {
 export type HostPersistenceState = {
   repos: readonly Pick<Repo, 'id' | 'connectionId' | 'executionHostId'>[]
   projectGroups?: readonly { id: string; executionHostId?: string | null }[]
-  folderWorkspaces?: readonly { id: string; projectGroupId: string }[]
+  folderWorkspaces?: readonly {
+    id: string
+    projectGroupId: string
+    executionHostId?: ExecutionHostId | null
+  }[]
   worktreesByRepo: Record<string, readonly WorkspaceRuntimeOwnerProjection[]>
   restoredRuntimeHostIdByWorkspaceSessionKey?: Record<string, ExecutionHostId>
 }
@@ -145,7 +149,7 @@ function getFolderWorkspaceRuntimeHostId(
   const group = workspace
     ? state.projectGroups?.find((entry) => entry.id === workspace.projectGroupId)
     : null
-  const parsed = parseExecutionHostId(group?.executionHostId)
+  const parsed = parseExecutionHostId(workspace?.executionHostId ?? group?.executionHostId)
   if (parsed) {
     return parsed.kind === 'runtime' ? parsed.id : LOCAL_EXECUTION_HOST_ID
   }
diff --git a/src/renderer/src/lib/workspace-session-relevant-fields.test.ts b/src/renderer/src/lib/workspace-session-relevant-fields.test.ts
index 84b874a096d..0a15b8207e0 100644
--- a/src/renderer/src/lib/workspace-session-relevant-fields.test.ts
+++ b/src/renderer/src/lib/workspace-session-relevant-fields.test.ts
@@ -7,6 +7,7 @@ describe('SESSION_RELEVANT_FIELDS', () => {
   const fixture: Record<keyof WorkspaceSessionSnapshot, true> = {
     activeRepoId: true,
     activeWorkspaceKey: true,
+    activeWorkspaceExecutionHostId: true,
     activeWorktreeId: true,
     activeTabId: true,
     tabsByWorktree: true,
diff --git a/src/renderer/src/lib/workspace-session.ts b/src/renderer/src/lib/workspace-session.ts
index 1324a8891b8..cfe1bbf3034 100644
--- a/src/renderer/src/lib/workspace-session.ts
+++ b/src/renderer/src/lib/workspace-session.ts
@@ -53,6 +53,7 @@ export type WorkspaceSessionSnapshot = Pick<
   | 'lastVisitedAtByWorktreeId'
   | 'defaultTerminalTabsAppliedByWorktreeId'
 > & {
+  activeWorkspaceExecutionHostId?: AppState['activeWorkspaceExecutionHostId']
   sleepingAgentSessionsByPaneKey?: AppState['sleepingAgentSessionsByPaneKey']
 }
 
@@ -60,6 +61,7 @@ export type WorkspaceSessionSnapshot = Pick<
 export const SESSION_RELEVANT_FIELDS = [
   'activeRepoId',
   'activeWorkspaceKey',
+  'activeWorkspaceExecutionHostId',
   'activeWorktreeId',
   'activeTabId',
   'tabsByWorktree',
@@ -92,8 +94,7 @@ type _MissingSessionField = Exclude<
   keyof WorkspaceSessionSnapshot,
   (typeof SESSION_RELEVANT_FIELDS)[number]
 >
-const _exhaustive: [_MissingSessionField] extends [never] ? true : never = true
-void _exhaustive
+void (true satisfies [_MissingSessionField] extends [never] ? true : never)
 
 /** Build the editor-file portion of the workspace session for persistence.
  *  Only edit-mode files are saved — diffs and conflict views are transient. */
@@ -298,6 +299,7 @@ export function buildWorkspaceSessionPayload(
   const payload = {
     activeRepoId: snapshot.activeRepoId,
     activeWorkspaceKey: snapshot.activeWorkspaceKey,
+    activeWorkspaceExecutionHostId: snapshot.activeWorkspaceExecutionHostId,
     activeWorktreeId: snapshot.activeWorktreeId,
     activeTabId: snapshot.activeTabId,
     tabsByWorktree: buildSanitizedTabsByWorktree(snapshot.tabsByWorktree),
diff --git a/src/renderer/src/lib/worktree-activation.ts b/src/renderer/src/lib/worktree-activation.ts
index e2a268f1c27..0be0503c9e9 100644
--- a/src/renderer/src/lib/worktree-activation.ts
+++ b/src/renderer/src/lib/worktree-activation.ts
@@ -56,6 +56,8 @@ import { isDetachedHeadWorkspace } from '@/components/sidebar/visible-worktrees'
 import { isNativeChatTranscriptLocalReadable } from '@/lib/native-chat-transcript-readability'
 import { seedNativeChatAppliedSessionOptions } from '@/components/native-chat/native-chat-session-option-cache'
 import type { SessionOptionValue } from '../../../shared/native-chat-session-options'
+import type { ExecutionHostId } from '../../../shared/execution-host'
+import { findFolderWorkspaceOwner } from './folder-workspace-runtime-owner'
 
 /** Telemetry threaded from the launch site to `pty:spawn`; main fires `agent_started`
  *  only after the spawn succeeds. See telemetry-plan.md§Agent launch semantics. */
@@ -195,11 +197,17 @@ export function activateAndRevealFolderWorkspace(
     sidebarRevealBehavior?: PendingSidebarWorktreeReveal['behavior']
     startup?: WorktreeStartupPayload
     runtimeEnvironmentId?: string | null
+    executionHostId?: ExecutionHostId
   }
 ): ActivateAndRevealResult | false {
   const state = useAppStore.getState()
+  const folderWorkspaceOwner = findFolderWorkspaceOwner(
+    state,
+    folderWorkspaceId,
+    opts?.executionHostId
+  )
   const folderWorkspace = state.folderWorkspaces.find(
-    (workspace) => workspace.id === folderWorkspaceId
+    (workspace) => workspace === folderWorkspaceOwner
   )
   if (!folderWorkspace) {
     return false
@@ -226,7 +234,7 @@ export function activateAndRevealFolderWorkspace(
     state.setActiveView('terminal')
   }
 
-  state.setActiveFolderWorkspace(folderWorkspaceId)
+  state.setActiveFolderWorkspace(folderWorkspaceId, opts?.executionHostId)
 
   const workspaceKey = folderWorkspaceKey(folderWorkspaceId)
   state.markWorktreeVisited(workspaceKey)
@@ -256,10 +264,11 @@ export function activateAndRevealWorktree(
     sidebarRevealBehavior?: PendingSidebarWorktreeReveal['behavior']
     notifyHostRuntime?: boolean
     revealInSidebar?: boolean
+    executionHostId?: ExecutionHostId
   }
 ): ActivateAndRevealResult | false {
   const state = useAppStore.getState()
-  const wt = state.getKnownWorktreeById(worktreeId)
+  const wt = state.getKnownWorktreeById(worktreeId, opts?.executionHostId)
   if (!wt) {
     return false
   }
@@ -271,6 +280,7 @@ export function activateAndRevealWorktree(
     !hasActivationWork &&
     state.activeRepoId === wt.repoId &&
     state.activeWorktreeId === worktreeId &&
+    state.activeWorkspaceExecutionHostId === (opts?.executionHostId ?? null) &&
     state.activeView === 'terminal'
 
   // 1. Set activeRepoId if crossing repos
@@ -284,7 +294,7 @@ export function activateAndRevealWorktree(
   }
 
   // 3. Core activation: setActiveWorktree also restores per-worktree state, clears unread, bumps dead PTY generations, refreshes GitHub
-  state.setActiveWorktree(worktreeId)
+  state.setActiveWorktree(worktreeId, opts?.executionHostId)
   const postActivationState = useAppStore.getState()
   const ownerRuntimeEnvironmentId = getRuntimeEnvironmentIdForWorktree(postActivationState, wt.id)
   if (opts?.notifyHostRuntime !== false && isWebRuntimeSessionActive(ownerRuntimeEnvironmentId)) {
diff --git a/src/renderer/src/lib/worktree-operation-route.ts b/src/renderer/src/lib/worktree-operation-route.ts
index 04468c5e995..c2281b28ac0 100644
--- a/src/renderer/src/lib/worktree-operation-route.ts
+++ b/src/renderer/src/lib/worktree-operation-route.ts
@@ -134,6 +134,19 @@ export function resolveWorktreeOperationRouteResult(
   state: WorktreeOperationRouteState,
   worktreeId: string
 ): WorktreeOperationRouteResolution {
+  const activeHost =
+    state.activeWorktreeId === worktreeId
+      ? parseExecutionHostId(state.activeWorkspaceExecutionHostId)
+      : null
+  if (activeHost) {
+    return {
+      kind: 'resolved',
+      route: {
+        executionHostId: activeHost.id,
+        runtimeEnvironmentId: activeHost.kind === 'runtime' ? activeHost.environmentId : null
+      }
+    }
+  }
   // Why: folder workspaces are not Git worktrees — they never appear in the worktree/repo
   // catalogs scanned below, so without this branch a plain local folder workspace reads as an
   // unresolved cross-host identity and every owner-routed operation fails closed (#10251).
diff --git a/src/renderer/src/lib/worktree-runtime-owner-index.ts b/src/renderer/src/lib/worktree-runtime-owner-index.ts
index 6e9a4a6f1ab..c9d2afbc41e 100644
--- a/src/renderer/src/lib/worktree-runtime-owner-index.ts
+++ b/src/renderer/src/lib/worktree-runtime-owner-index.ts
@@ -1,8 +1,18 @@
 import type { FolderWorkspace, ProjectGroup, Repo, Worktree } from '../../../shared/types'
+import {
+  getRepoExecutionHostId,
+  parseExecutionHostId,
+  toRuntimeExecutionHostId,
+  toSshExecutionHostId,
+  type ExecutionHostId
+} from '../../../shared/execution-host'
 
 type WorktreeOwnerRecord = Pick<Worktree, 'id' | 'repoId' | 'hostId' | 'runtimeOwnerEnvironmentId'>
 type RepoOwnerRecord = Pick<Repo, 'id' | 'connectionId' | 'executionHostId'>
-type FolderWorkspaceOwnerRecord = Pick<FolderWorkspace, 'id' | 'projectGroupId' | 'connectionId'>
+type FolderWorkspaceOwnerRecord = Pick<
+  FolderWorkspace,
+  'id' | 'projectGroupId' | 'connectionId' | 'executionHostId'
+>
 type ProjectGroupOwnerRecord = Pick<ProjectGroup, 'id' | 'connectionId' | 'executionHostId'>
 
 // Why: owner resolution runs inside retained selectors and interaction paths;
@@ -17,35 +27,56 @@ const repoOwnerIndexCache = new WeakMap<
 >()
 const folderWorkspaceOwnerIndexCache = new WeakMap<
   readonly FolderWorkspaceOwnerRecord[],
-  ReadonlyMap<string, FolderWorkspaceOwnerRecord>
+  ReadonlyMap<string, IndexedFolderWorkspaceOwnerResolution>
 >()
 const projectGroupOwnerIndexCache = new WeakMap<
   readonly ProjectGroupOwnerRecord[],
-  ReadonlyMap<string, ProjectGroupOwnerRecord>
+  ReadonlyMap<string, IndexedProjectGroupOwnerResolution>
 >()
 
-function findIndexedOwnerRecord<T extends { id: string }>(
-  records: readonly T[] | undefined,
-  id: string,
-  cache: WeakMap<readonly T[], ReadonlyMap<string, T>>
-): T | null {
-  if (!records) {
-    return null
+type IndexedFolderWorkspaceOwnerResolution =
+  | { kind: 'resolved'; owner: FolderWorkspaceOwnerRecord }
+  | { kind: 'missing' }
+  | { kind: 'ambiguous' }
+
+type IndexedProjectGroupOwnerResolution =
+  | { kind: 'resolved'; owner: ProjectGroupOwnerRecord }
+  | { kind: 'missing' }
+  | { kind: 'ambiguous' }
+
+function catalogOwnerHostId(owner: {
+  connectionId?: string | null
+  executionHostId?: string | null
+}): ExecutionHostId {
+  const explicitHost = parseExecutionHostId(owner.executionHostId)
+  if (explicitHost) {
+    return explicitHost.id
   }
-  let index = cache.get(records)
-  if (!index) {
-    const next = new Map<string, T>()
-    for (const record of records) {
-      const recordId = record.id
-      if (!next.has(recordId)) {
-        // Preserve the prior Array.find behavior for invalid duplicate IDs.
-        next.set(recordId, record)
-      }
+  const connectionId = owner.connectionId?.trim()
+  return connectionId ? toSshExecutionHostId(connectionId) : 'local'
+}
+
+function buildCatalogOwnerIndex<
+  T extends { id: string; connectionId?: string | null; executionHostId?: string | null }
+>(
+  records: readonly T[]
+): ReadonlyMap<string, { kind: 'resolved'; owner: T } | { kind: 'ambiguous' }> {
+  const next = new Map<string, { kind: 'resolved'; owner: T } | { kind: 'ambiguous' }>()
+  for (const record of records) {
+    const id = record.id
+    const hostId = catalogOwnerHostId(record)
+    const current = next.get(id)
+    if (!current) {
+      next.set(id, { kind: 'resolved', owner: record })
+    } else if (current.kind === 'resolved' && catalogOwnerHostId(current.owner) !== hostId) {
+      next.set(id, { kind: 'ambiguous' })
     }
-    index = next
-    cache.set(records, index)
+    next.set(`${id}\0${hostId}`, {
+      kind: 'resolved',
+      owner: record
+    })
   }
-  return index.get(id) ?? null
+  return next
 }
 
 export function findIndexedWorktreeOwner(
@@ -56,6 +87,21 @@ export function findIndexedWorktreeOwner(
   return resolution.kind === 'resolved' ? resolution.owner : null
 }
 
+export function findIndexedWorktreeOwnerForHost(
+  worktreesByRepo: Record<string, readonly WorktreeOwnerRecord[]> | undefined,
+  worktreeId: string,
+  executionHostId: ExecutionHostId
+): WorktreeOwnerRecord | null {
+  if (!worktreesByRepo) {
+    return null
+  }
+  resolveIndexedWorktreeOwner(worktreesByRepo, worktreeId)
+  const resolution = worktreeOwnerIndexCache
+    .get(worktreesByRepo)
+    ?.get(`${worktreeId}\0${executionHostId}`)
+  return resolution?.kind === 'resolved' ? resolution.owner : null
+}
+
 export type IndexedRepoOwnerResolution =
   | { kind: 'resolved'; owner: RepoOwnerRecord }
   | { kind: 'missing' }
@@ -86,6 +132,10 @@ export function resolveIndexedRepoOwner(
       ) {
         next.set(repoId, { kind: 'ambiguous' })
       }
+      next.set(`${repoId}\0${getRepoExecutionHostId(repo)}`, {
+        kind: 'resolved',
+        owner: repo
+      })
     }
     index = next
     repoOwnerIndexCache.set(repos, index)
@@ -106,6 +156,15 @@ function worktreeOwnerIdentity(owner: WorktreeOwnerRecord): string {
   ])
 }
 
+function worktreeOwnerHostId(owner: WorktreeOwnerRecord): ExecutionHostId {
+  return (
+    parseExecutionHostId(owner.hostId)?.id ??
+    (owner.runtimeOwnerEnvironmentId
+      ? toRuntimeExecutionHostId(owner.runtimeOwnerEnvironmentId)
+      : 'local')
+  )
+}
+
 export function resolveIndexedWorktreeOwner(
   worktreesByRepo: Record<string, readonly WorktreeOwnerRecord[]> | undefined,
   worktreeId: string
@@ -128,6 +187,10 @@ export function resolveIndexedWorktreeOwner(
         ) {
           next.set(id, { kind: 'ambiguous' })
         }
+        next.set(`${id}\0${worktreeOwnerHostId(worktree)}`, {
+          kind: 'resolved',
+          owner: worktree
+        })
       }
     }
     index = next
@@ -144,16 +207,53 @@ export function findIndexedRepoOwner(
   return resolution.kind === 'resolved' ? resolution.owner : null
 }
 
+export function findIndexedRepoOwnerForHost(
+  repos: readonly RepoOwnerRecord[] | undefined,
+  repoId: string,
+  executionHostId: ExecutionHostId
+): RepoOwnerRecord | null {
+  if (!repos) {
+    return null
+  }
+  resolveIndexedRepoOwner(repos, repoId)
+  const resolution = repoOwnerIndexCache.get(repos)?.get(`${repoId}\0${executionHostId}`)
+  return resolution?.kind === 'resolved' ? resolution.owner : null
+}
+
 export function findIndexedFolderWorkspaceOwner(
   folderWorkspaces: readonly FolderWorkspaceOwnerRecord[] | undefined,
-  folderWorkspaceId: string
+  folderWorkspaceId: string,
+  executionHostId?: ExecutionHostId
 ): FolderWorkspaceOwnerRecord | null {
-  return findIndexedOwnerRecord(folderWorkspaces, folderWorkspaceId, folderWorkspaceOwnerIndexCache)
+  if (!folderWorkspaces) {
+    return null
+  }
+  let index = folderWorkspaceOwnerIndexCache.get(folderWorkspaces)
+  if (!index) {
+    index = buildCatalogOwnerIndex(folderWorkspaces)
+    folderWorkspaceOwnerIndexCache.set(folderWorkspaces, index)
+  }
+  const resolution = index.get(
+    executionHostId ? `${folderWorkspaceId}\0${executionHostId}` : folderWorkspaceId
+  )
+  return resolution?.kind === 'resolved' ? resolution.owner : null
 }
 
 export function findIndexedProjectGroupOwner(
   projectGroups: readonly ProjectGroupOwnerRecord[] | undefined,
-  projectGroupId: string
+  projectGroupId: string,
+  executionHostId?: ExecutionHostId
 ): ProjectGroupOwnerRecord | null {
-  return findIndexedOwnerRecord(projectGroups, projectGroupId, projectGroupOwnerIndexCache)
+  if (!projectGroups) {
+    return null
+  }
+  let index = projectGroupOwnerIndexCache.get(projectGroups)
+  if (!index) {
+    index = buildCatalogOwnerIndex(projectGroups)
+    projectGroupOwnerIndexCache.set(projectGroups, index)
+  }
+  const resolution = index.get(
+    executionHostId ? `${projectGroupId}\0${executionHostId}` : projectGroupId
+  )
+  return resolution?.kind === 'resolved' ? resolution.owner : null
 }
diff --git a/src/renderer/src/lib/worktree-runtime-owner-state.ts b/src/renderer/src/lib/worktree-runtime-owner-state.ts
index 7c9976d1983..6e65f7a1bcf 100644
--- a/src/renderer/src/lib/worktree-runtime-owner-state.ts
+++ b/src/renderer/src/lib/worktree-runtime-owner-state.ts
@@ -20,9 +20,14 @@ export type WorktreeRuntimeOwnerState = {
       worktrees: readonly Pick<Worktree, 'id' | 'repoId' | 'hostId' | 'runtimeOwnerEnvironmentId'>[]
     }
   >
-  folderWorkspaces?: readonly Pick<FolderWorkspace, 'id' | 'projectGroupId' | 'connectionId'>[]
+  folderWorkspaces?: readonly Pick<
+    FolderWorkspace,
+    'id' | 'projectGroupId' | 'connectionId' | 'executionHostId'
+  >[]
   projectGroups?: readonly Pick<ProjectGroup, 'id' | 'connectionId' | 'executionHostId'>[]
   restoredRuntimeHostIdByWorkspaceSessionKey?: Record<string, ExecutionHostId>
+  activeWorktreeId?: string | null
+  activeWorkspaceExecutionHostId?: ExecutionHostId | null
   runtimeEnvironments?: readonly { id: string }[]
   runtimeEnvironmentCatalogHydrated?: boolean
   removedRuntimeEnvironmentIds?: ReadonlySet<string>
diff --git a/src/renderer/src/lib/worktree-runtime-owner.test.ts b/src/renderer/src/lib/worktree-runtime-owner.test.ts
index bb5aab3e19a..410c3b3bebf 100644
--- a/src/renderer/src/lib/worktree-runtime-owner.test.ts
+++ b/src/renderer/src/lib/worktree-runtime-owner.test.ts
@@ -62,6 +62,27 @@ describe('getSettingsForWorktreeRuntimeOwner', () => {
     expect(getExecutionHostIdForWorktree(state, 'folder:runtime-folder')).toBe('runtime:folder-env')
   })
 
+  it('uses the folder host stamp when same-ID project groups exist on different hosts', () => {
+    const collisionState: WorktreeRuntimeOwnerState = {
+      settings: { activeRuntimeEnvironmentId: null },
+      folderWorkspaces: [
+        {
+          id: 'same-folder',
+          projectGroupId: 'same-group',
+          executionHostId: 'runtime:folder-env'
+        }
+      ],
+      projectGroups: [
+        { id: 'same-group', connectionId: null, executionHostId: 'local' },
+        { id: 'same-group', connectionId: null, executionHostId: 'runtime:folder-env' }
+      ]
+    }
+
+    expect(getExecutionHostIdForWorktree(collisionState, 'folder:same-folder')).toBe(
+      'runtime:folder-env'
+    )
+  })
+
   it('routes restored runtime folder workspaces before their catalog loads', () => {
     const restoredFolderState: WorktreeRuntimeOwnerState = {
       settings: { activeRuntimeEnvironmentId: 'focused-env' },
diff --git a/src/renderer/src/lib/worktree-runtime-owner.ts b/src/renderer/src/lib/worktree-runtime-owner.ts
index 4bd54c0c50b..0ad6b696c07 100644
--- a/src/renderer/src/lib/worktree-runtime-owner.ts
+++ b/src/renderer/src/lib/worktree-runtime-owner.ts
@@ -43,6 +43,15 @@ function getExecutionHostIdFromWorktreeHost(
   return parseExecutionHostId(hostId)?.id ?? null
 }
 
+function getActiveWorkspaceExecutionHostId(
+  state: WorktreeRuntimeOwnerState,
+  worktreeId: string
+): ExecutionHostId | null {
+  return state.activeWorktreeId === worktreeId
+    ? (state.activeWorkspaceExecutionHostId ?? null)
+    : null
+}
+
 export function getRuntimeEnvironmentIdForWorktree(
   state: WorktreeRuntimeOwnerState,
   worktreeId: string | null | undefined
@@ -53,6 +62,10 @@ export function getRuntimeEnvironmentIdForWorktree(
   if (worktreeId === FLOATING_TERMINAL_WORKTREE_ID) {
     return null
   }
+  const activeHost = parseExecutionHostId(getActiveWorkspaceExecutionHostId(state, worktreeId))
+  if (activeHost) {
+    return activeHost.kind === 'runtime' ? activeHost.environmentId : null
+  }
   const workspaceScope = parseWorkspaceKey(worktreeId)
   if (workspaceScope?.type === 'folder') {
     return getRuntimeEnvironmentIdForFolderWorkspace(state, workspaceScope.folderWorkspaceId)
@@ -100,6 +113,10 @@ export function getExplicitRuntimeEnvironmentIdForWorktree(
   if (!worktreeId) {
     return null
   }
+  const activeHost = parseExecutionHostId(getActiveWorkspaceExecutionHostId(state, worktreeId))
+  if (activeHost) {
+    return activeHost.kind === 'runtime' ? activeHost.environmentId : null
+  }
   const workspaceScope = parseWorkspaceKey(worktreeId)
   if (workspaceScope?.type === 'folder') {
     return getExplicitRuntimeEnvironmentIdForFolderWorkspace(
@@ -151,6 +168,10 @@ export function getExecutionHostIdForWorktree(
   if (worktreeId === FLOATING_TERMINAL_WORKTREE_ID) {
     return 'local'
   }
+  const activeHostId = getActiveWorkspaceExecutionHostId(state, worktreeId)
+  if (activeHostId) {
+    return activeHostId
+  }
   const workspaceScope = parseWorkspaceKey(worktreeId)
   if (workspaceScope?.type === 'folder') {
     return getExecutionHostIdForFolderWorkspace(state, workspaceScope.folderWorkspaceId)
diff --git a/src/renderer/src/runtime/web-runtime-session.test.ts b/src/renderer/src/runtime/web-runtime-session.test.ts
index bd42dda2be6..7eee47842ba 100644
--- a/src/renderer/src/runtime/web-runtime-session.test.ts
+++ b/src/renderer/src/runtime/web-runtime-session.test.ts
@@ -33,6 +33,7 @@ import {
   recordWebAgentSessionHandoff,
   resetWebAgentSessionHandoffsForTests
 } from './web-agent-session-handoff'
+import { toRuntimeExecutionHostId } from '../../../shared/execution-host'
 
 const mocks = vi.hoisted(() => ({
   getState: vi.fn(),
@@ -79,6 +80,7 @@ vi.mock('@/lib/agent-launch-prompt-delivery', () => ({
 }))
 
 const ENVIRONMENT_ID = 'web-env-1'
+const RUNTIME_EXECUTION_HOST_ID = toRuntimeExecutionHostId(ENVIRONMENT_ID)
 const WORKTREE_ID = 'repo::/worktree'
 const FOCUS_LEAF_ID = '11111111-1111-4111-8111-111111111111'
 
@@ -392,7 +394,7 @@ describe('createWebRuntimeSessionBrowserTab', () => {
 
     await vi.waitFor(() => expect(mocks.applyFreshWebSessionTabsSnapshot).toHaveBeenCalledTimes(1))
 
-    expect(mocks.setActiveWorktree).toHaveBeenCalledWith(WORKTREE_ID)
+    expect(mocks.setActiveWorktree).toHaveBeenCalledWith(WORKTREE_ID, RUNTIME_EXECUTION_HOST_ID)
     expect(mocks.applyFreshWebSessionTabsSnapshot).toHaveBeenCalledWith(
       { state: 'before-stage', activeWorktreeId: 'other-worktree' },
       snapshot,
@@ -489,7 +491,7 @@ describe('createWebRuntimeSessionBrowserTab', () => {
     ).resolves.toBe(true)
 
     expect(mocks.focusBrowserTabInWorktree).not.toHaveBeenCalled()
-    expect(mocks.setActiveWorktree).toHaveBeenCalledWith(WORKTREE_ID)
+    expect(mocks.setActiveWorktree).toHaveBeenCalledWith(WORKTREE_ID, RUNTIME_EXECUTION_HOST_ID)
     await vi.waitFor(() => expect(mocks.setState).toHaveBeenCalledTimes(1))
   })
 
@@ -563,6 +565,33 @@ describe('createWebRuntimeSessionTerminal', () => {
     vi.clearAllMocks()
   })
 
+  it('keeps same-ID local and runtime worktrees on the selected runtime owner', async () => {
+    const selectedHosts: (string | undefined)[] = []
+    mocks.setActiveWorktree.mockImplementation((_worktreeId: string, executionHostId?: string) => {
+      selectedHosts.push(executionHostId)
+    })
+    const runtimeCall = vi
+      .fn()
+      .mockResolvedValueOnce({
+        id: 'create',
+        ok: true,
+        result: { tab: { id: 'host-tab-1', leafId: 'host-leaf-1' } }
+      })
+      .mockResolvedValueOnce({ id: 'list', ok: true, result: makeSnapshot() })
+    vi.stubGlobal('window', {
+      api: { runtimeEnvironments: { call: runtimeCall } }
+    })
+
+    await expect(
+      createWebRuntimeSessionTerminal({
+        worktreeId: WORKTREE_ID,
+        environmentId: ENVIRONMENT_ID
+      })
+    ).resolves.toEqual({ status: 'created' })
+
+    expect(selectedHosts).toEqual([RUNTIME_EXECUTION_HOST_ID])
+  })
+
   it.each([
     { sessionKind: 'fresh' as const, activate: true },
     { sessionKind: 'fresh' as const, activate: false },
diff --git a/src/renderer/src/runtime/web-runtime-session.ts b/src/renderer/src/runtime/web-runtime-session.ts
index ee85894fc99..05ee84260fc 100644
--- a/src/renderer/src/runtime/web-runtime-session.ts
+++ b/src/renderer/src/runtime/web-runtime-session.ts
@@ -60,6 +60,7 @@ import { runRemoteAgentSessionLaunch } from './remote-agent-session-launch'
 import { translate } from '../i18n/i18n'
 import { getRuntimeEnvironmentRevision } from './runtime-environment-revision'
 import { parsePaneKey } from '../../../shared/stable-pane-id'
+import { toRuntimeExecutionHostId } from '../../../shared/execution-host'
 
 export {
   HOST_TERMINAL_SURFACE_SEPARATOR,
@@ -229,7 +230,7 @@ async function createWebRuntimeSessionTerminalResult(
   const callEnvironment = captureRuntimeEnvironmentCall(environmentId, intentOwner.pairingRevision)
 
   if (args.selectWorktree !== false) {
-    selectWebRuntimeSessionWorktree(args.worktreeId)
+    selectWebRuntimeSessionWorktree(args.worktreeId, environmentId)
   }
   let hostCreated = false
   let createdTabId: string | undefined
@@ -437,7 +438,7 @@ export async function createWebRuntimeSessionBrowserTab(args: {
   const shouldSelectWorktree = args.selectWorktree !== false
   const stagedFromWorktreeId = useAppStore.getState().activeWorktreeId
   if (shouldSelectWorktree) {
-    selectWebRuntimeSessionWorktree(args.worktreeId)
+    selectWebRuntimeSessionWorktree(args.worktreeId, environmentId)
   }
   try {
     const response = await callEnvironment({
@@ -503,7 +504,7 @@ function stageWebRuntimeBrowserTab(args: {
     remotePageId
   )
   if (args.restoreFocus !== false) {
-    selectWebRuntimeSessionWorktree(args.worktreeId)
+    selectWebRuntimeSessionWorktree(args.worktreeId, args.environmentId)
   }
 
   if (existing) {
@@ -533,8 +534,8 @@ function stageWebRuntimeBrowserTab(args: {
   })
 }
 
-function selectWebRuntimeSessionWorktree(worktreeId: string): void {
-  useAppStore.getState().setActiveWorktree(worktreeId)
+function selectWebRuntimeSessionWorktree(worktreeId: string, environmentId: string): void {
+  useAppStore.getState().setActiveWorktree(worktreeId, toRuntimeExecutionHostId(environmentId))
 }
 
 function findLocalBrowserPageForRemotePage(
diff --git a/src/renderer/src/store/selectors.test.ts b/src/renderer/src/store/selectors.test.ts
index 8059cf68dde..ca9248a3ab5 100644
--- a/src/renderer/src/store/selectors.test.ts
+++ b/src/renderer/src/store/selectors.test.ts
@@ -8,6 +8,7 @@ import {
   getProjectHostSetupProjectionFromState,
   getWorktreeMapFromState,
   resetFloatingVisibleTabCountSelectorCacheForTest,
+  selectRepoByIdForActiveWorkspace,
   selectFloatingVisibleTabCount,
   selectFloatingWorkspaceHasUnread
 } from './selectors'
@@ -261,6 +262,32 @@ describe('store selectors', () => {
     expect(getProjectHostSetupProjectionFromState({ repos: [...repos] })).not.toBe(projection)
   })
 
+  it('does not fall back to a same-ID local repo when the active runtime row is absent', () => {
+    const local = makeRepo({
+      id: 'same-repo',
+      path: '/local/repo',
+      displayName: 'local',
+      executionHostId: 'local'
+    })
+    const runtime = makeRepo({
+      id: 'same-repo',
+      path: '/runtime/repo',
+      displayName: 'runtime',
+      executionHostId: toRuntimeExecutionHostId('env-1')
+    })
+    const activeState = {
+      activeRepoId: 'same-repo',
+      activeWorkspaceExecutionHostId: toRuntimeExecutionHostId('env-1')
+    }
+
+    expect(
+      selectRepoByIdForActiveWorkspace({ ...activeState, repos: [local, runtime] }, 'same-repo')
+    ).toBe(runtime)
+    expect(
+      selectRepoByIdForActiveWorkspace({ ...activeState, repos: [local] }, 'same-repo')
+    ).toBeNull()
+  })
+
   it('prefers hydrated project host setup state when present', () => {
     const repos = [
       makeRepo({
diff --git a/src/renderer/src/store/selectors.ts b/src/renderer/src/store/selectors.ts
index 76dcb5336af..1904074f487 100644
--- a/src/renderer/src/store/selectors.ts
+++ b/src/renderer/src/store/selectors.ts
@@ -3,6 +3,7 @@ import { useShallow } from 'zustand/react/shallow'
 import type { Repo, Worktree, TerminalTab } from '../../../shared/types'
 import type { AppState } from './types'
 import { FLOATING_TERMINAL_WORKTREE_ID } from '../../../shared/constants'
+import { getRepoExecutionHostId } from '../../../shared/execution-host'
 import { getProjectHostSetupProjectionFromState } from './project-host-setup-selector'
 import {
   getIndexedAllWorktrees as getCachedAllWorktrees,
@@ -170,10 +171,30 @@ export function getRepoMapFromState(state: Pick<AppState, 'repos'>): Map<string,
 // ─── Repos ──────────────────────────────────────────────────────────
 export const useRepos = () => useAppStore((s) => s.repos)
 export const useActiveRepo = () =>
-  useAppStore(useShallow((s) => s.repos.find((r) => r.id === s.activeRepoId) ?? null))
+  useAppStore(useShallow((s) => selectRepoByIdForActiveWorkspace(s, s.activeRepoId)))
 export const useRepoMap = () => useAppStore((s) => getCachedRepoMap(s.repos))
+
+export function selectRepoByIdForActiveWorkspace(
+  state: Pick<AppState, 'repos' | 'activeRepoId' | 'activeWorkspaceExecutionHostId'>,
+  repoId: string | null
+): Repo | null {
+  if (!repoId) {
+    return null
+  }
+  if (repoId === state.activeRepoId && state.activeWorkspaceExecutionHostId) {
+    return (
+      state.repos.find(
+        (repo) =>
+          repo.id === repoId &&
+          getRepoExecutionHostId(repo) === state.activeWorkspaceExecutionHostId
+      ) ?? null
+    )
+  }
+  return getCachedRepoMap(state.repos).get(repoId) ?? null
+}
+
 export const useRepoById = (repoId: string | null) =>
-  useAppStore((s) => (repoId ? (getCachedRepoMap(s.repos).get(repoId) ?? null) : null))
+  useAppStore((s) => selectRepoByIdForActiveWorkspace(s, repoId))
 export const useProjectHostSetupProjection = () =>
   useAppStore((s) => getProjectHostSetupProjectionFromState(s))
 
@@ -185,11 +206,21 @@ export const useAllWorktrees = () => useAppStore((s) => getCachedAllWorktrees(s.
 export const useWorktreeMap = () => useAppStore((s) => getCachedWorktreeMap(s.worktreesByRepo))
 export const useWorktreeById = (worktreeId: string | null) =>
   useAppStore((s) =>
-    worktreeId ? (getCachedWorktreeMap(s.worktreesByRepo).get(worktreeId) ?? null) : null
+    worktreeId
+      ? (s.getKnownWorktreeById(
+          worktreeId,
+          worktreeId === s.activeWorktreeId
+            ? (s.activeWorkspaceExecutionHostId ?? undefined)
+            : undefined
+        ) ?? null)
+      : null
   )
 export const useActiveWorktree = () => {
   const activeWorktreeId = useActiveWorktreeId()
   return useAppStore((s) =>
-    activeWorktreeId ? (s.getKnownWorktreeById(activeWorktreeId) ?? null) : null
+    activeWorktreeId
+      ? (s.getKnownWorktreeById(activeWorktreeId, s.activeWorkspaceExecutionHostId ?? undefined) ??
+        null)
+      : null
   )
 }
diff --git a/src/renderer/src/store/slices/direct-ssh-terminal-workspace-scope.ts b/src/renderer/src/store/slices/direct-ssh-terminal-workspace-scope.ts
index c970e4fe451..e24ca1cdcd1 100644
--- a/src/renderer/src/store/slices/direct-ssh-terminal-workspace-scope.ts
+++ b/src/renderer/src/store/slices/direct-ssh-terminal-workspace-scope.ts
@@ -59,6 +59,9 @@ function folderHasContradictoryOwner(
   const expectedHostId = toSshExecutionHostId(input.targetId)
   const folders = (input.folderWorkspaces ?? []).filter((folder) => folder.id === folderWorkspaceId)
   for (const folder of folders) {
+    if (isExplicitContradictoryHost(folder.executionHostId, expectedHostId)) {
+      return true
+    }
     if (folder.connectionId?.trim() && folder.connectionId.trim() !== input.targetId) {
       return true
     }
diff --git a/src/renderer/src/store/slices/folder-workspace-owner-routed-mutations.test.ts b/src/renderer/src/store/slices/folder-workspace-owner-routed-mutations.test.ts
index 736201137f6..83ea704c690 100644
--- a/src/renderer/src/store/slices/folder-workspace-owner-routed-mutations.test.ts
+++ b/src/renderer/src/store/slices/folder-workspace-owner-routed-mutations.test.ts
@@ -237,6 +237,55 @@ describe('folder workspace owner-routed mutations', () => {
     expect(store.getState().folderWorkspaces[0]?.updatedAt).toBe(2)
   })
 
+  it('does not fence a runtime update when the local same-ID catalog refreshes', async () => {
+    const localWorkspace = makeFolderWorkspace({ updatedAt: 3 })
+    const runtimeWorkspace = {
+      ...makeFolderWorkspace(),
+      executionHostId: 'runtime:env-owner' as const
+    }
+    let resolveRuntimeUpdate!: (response: {
+      id: string
+      ok: true
+      result: { folderWorkspace: FolderWorkspace }
+      _meta: { runtimeId: string }
+    }) => void
+    runtimeEnvironmentCall.mockImplementation(
+      () =>
+        new Promise((resolve) => {
+          resolveRuntimeUpdate = resolve
+        })
+    )
+    folderWorkspacesList.mockResolvedValue([localWorkspace])
+    const store = createTestStore()
+    store.setState({
+      projectGroups: [{ ...projectGroup, executionHostId: 'local' }],
+      folderWorkspaces: [localWorkspace, runtimeWorkspace]
+    })
+
+    const pendingUpdate = store
+      .getState()
+      .updateFolderWorkspace(
+        runtimeWorkspace.id,
+        { isUnread: true },
+        { executionHostId: 'runtime:env-owner' }
+      )
+    await store.getState().fetchFolderWorkspaces({ runtimeEnvironmentId: null })
+    resolveRuntimeUpdate({
+      id: 'rpc-update-folder',
+      ok: true,
+      result: {
+        folderWorkspace: { ...runtimeWorkspace, isUnread: true, updatedAt: 2 }
+      },
+      _meta: { runtimeId: 'runtime-owner' }
+    })
+    await pendingUpdate
+
+    expect(store.getState().folderWorkspaces).toEqual([
+      { ...localWorkspace, executionHostId: 'local' },
+      { ...runtimeWorkspace, isUnread: true, updatedAt: 2 }
+    ])
+  })
+
   it('does not rewind newer optimistic activity when an older response arrives', async () => {
     const folderWorkspace = makeFolderWorkspace()
     let resolveUpdate!: (workspace: FolderWorkspace) => void
diff --git a/src/renderer/src/store/slices/repos-all-hosts-folder-workspaces.test.ts b/src/renderer/src/store/slices/repos-all-hosts-folder-workspaces.test.ts
index dea0120febf..bbbd90d6440 100644
--- a/src/renderer/src/store/slices/repos-all-hosts-folder-workspaces.test.ts
+++ b/src/renderer/src/store/slices/repos-all-hosts-folder-workspaces.test.ts
@@ -276,7 +276,9 @@ describe('all-host folder workspace startup catalogs', () => {
     expect(store.getState().projectGroups).toEqual([
       { ...localProjectGroup, executionHostId: 'local' }
     ])
-    expect(store.getState().folderWorkspaces).toEqual([localFolderWorkspace])
+    expect(store.getState().folderWorkspaces).toEqual([
+      { ...localFolderWorkspace, executionHostId: 'local' }
+    ])
   })
 
   it('does not repeat offline runtime compatibility probes across startup catalog loads', async () => {
@@ -305,7 +307,9 @@ describe('all-host folder workspace startup catalogs', () => {
       expect(store.getState().projectGroups).toEqual([
         { ...localProjectGroup, executionHostId: 'local' }
       ])
-      expect(store.getState().folderWorkspaces).toEqual([localFolderWorkspace])
+      expect(store.getState().folderWorkspaces).toEqual([
+        { ...localFolderWorkspace, executionHostId: 'local' }
+      ])
       expect(runtimeEnvironmentTransportCall.mock.calls.map((call) => call[0].method)).toEqual([
         'status.get'
       ])
diff --git a/src/renderer/src/store/slices/repos-all-hosts.test.ts b/src/renderer/src/store/slices/repos-all-hosts.test.ts
index 638941df094..9d38bc0bf8c 100644
--- a/src/renderer/src/store/slices/repos-all-hosts.test.ts
+++ b/src/renderer/src/store/slices/repos-all-hosts.test.ts
@@ -780,7 +780,9 @@ describe('fetchReposForAllHosts', () => {
     expect(store.getState().projectGroups).toEqual([
       { ...localProjectGroup, executionHostId: 'local' }
     ])
-    expect(store.getState().folderWorkspaces).toEqual([localFolderWorkspace])
+    expect(store.getState().folderWorkspaces).toEqual([
+      { ...localFolderWorkspace, executionHostId: 'local' }
+    ])
   })
 
   it('preserves remote repo filters during first-paint local catalog refresh', async () => {
diff --git a/src/renderer/src/store/slices/repos-project-groups.test.ts b/src/renderer/src/store/slices/repos-project-groups.test.ts
index 7b32c5b6b3a..9fbf455587b 100644
--- a/src/renderer/src/store/slices/repos-project-groups.test.ts
+++ b/src/renderer/src/store/slices/repos-project-groups.test.ts
@@ -270,7 +270,7 @@ describe('project group store routing', () => {
           { projectGroupId: projectGroup.id, name: 'Runtime folder' },
           { runtimeEnvironmentId: 'env-1' }
         )
-    ).resolves.toEqual(folderWorkspace)
+    ).resolves.toEqual({ ...folderWorkspace, executionHostId: 'runtime:env-1' })
 
     expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
       selector: 'env-1',
@@ -350,7 +350,7 @@ describe('project group store routing', () => {
         name: 'Refund fix',
         linkedTask
       })
-    ).resolves.toEqual(folderWorkspace)
+    ).resolves.toEqual({ ...folderWorkspace, executionHostId: 'local' })
     await expect(
       store.getState().updateFolderWorkspace(folderWorkspace.id, { comment: 'Ready' })
     ).resolves.toBe(true)
@@ -805,9 +805,13 @@ describe('project group store routing', () => {
       _meta: { runtimeId: 'runtime-remote' }
     })
     const store = createTestStore()
-    store.setState({ settings: { activeRuntimeEnvironmentId: 'env-1' } as never })
+    store.setState({ settings: { activeRuntimeEnvironmentId: 'env-ambient' } as never })
 
-    await expect(store.getState().scanNestedRepos('/platform')).resolves.toEqual({
+    await expect(
+      store.getState().scanNestedRepos('/platform', undefined, {
+        runtimeEnvironmentId: 'env-selected'
+      })
+    ).resolves.toEqual({
       selectedPath: '/platform',
       selectedPathKind: 'non_git_folder',
       repos: [{ path: '/platform/api', displayName: 'api', depth: 1 }],
@@ -821,7 +825,7 @@ describe('project group store routing', () => {
     })
 
     expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
-      selector: 'env-1',
+      selector: 'env-selected',
       method: 'projectGroup.scanNested',
       params: { path: '/platform' },
       timeoutMs: 20_000
diff --git a/src/renderer/src/store/slices/repos-selected-owner-routing.test.ts b/src/renderer/src/store/slices/repos-selected-owner-routing.test.ts
new file mode 100644
index 00000000000..691a9fbdaaf
--- /dev/null
+++ b/src/renderer/src/store/slices/repos-selected-owner-routing.test.ts
@@ -0,0 +1,536 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { FolderWorkspace, ProjectGroup, Repo } from '../../../../shared/types'
+import {
+  createCompatibleRuntimeStatusResponseIfNeeded,
+  type RuntimeEnvironmentCallRequest
+} from '../../runtime/runtime-compatibility-test-fixture'
+import { clearRuntimeCompatibilityCacheForTests } from '../../runtime/runtime-rpc-client'
+import { createTestStore } from './store-test-helpers'
+
+const projectGroup: ProjectGroup = {
+  id: 'group-runtime',
+  name: 'Platform',
+  parentPath: '/runtime/platform',
+  parentGroupId: null,
+  createdFrom: 'manual',
+  tabOrder: 0,
+  isCollapsed: false,
+  color: null,
+  createdAt: 1,
+  updatedAt: 1
+}
+
+const baseRepo: Repo = {
+  id: 'repo',
+  path: '/repo',
+  displayName: 'Repo',
+  badgeColor: '#111',
+  addedAt: 1
+}
+
+const reposList = vi.fn()
+const projectGroupsList = vi.fn()
+const projectGroupsImportNested = vi.fn()
+const projectGroupsScanNested = vi.fn()
+const projectGroupsCancelNestedScan = vi.fn()
+const folderWorkspacesList = vi.fn()
+const runtimeEnvironmentCall = vi.fn()
+const runtimeEnvironmentTransportCall = vi.fn()
+
+beforeEach(() => {
+  clearRuntimeCompatibilityCacheForTests()
+  vi.clearAllMocks()
+  runtimeEnvironmentTransportCall.mockImplementation((args: RuntimeEnvironmentCallRequest) => {
+    return createCompatibleRuntimeStatusResponseIfNeeded(args) ?? runtimeEnvironmentCall(args)
+  })
+  vi.stubGlobal('window', {
+    api: {
+      repos: { list: reposList },
+      projectGroups: {
+        list: projectGroupsList,
+        importNested: projectGroupsImportNested,
+        scanNested: projectGroupsScanNested,
+        cancelNestedScan: projectGroupsCancelNestedScan,
+        onNestedScanProgress: vi.fn(() => vi.fn())
+      },
+      folderWorkspaces: { list: folderWorkspacesList },
+      runtimeEnvironments: { call: runtimeEnvironmentTransportCall }
+    }
+  })
+})
+
+describe('selected Add Project owner routing', () => {
+  it('keeps same-ID project groups and folder workspaces partitioned by host', async () => {
+    const localGroup = {
+      ...projectGroup,
+      id: 'shared-group',
+      name: 'Local group',
+      parentPath: '/local/platform',
+      executionHostId: 'local' as const
+    }
+    const runtimeGroup = {
+      ...projectGroup,
+      id: localGroup.id,
+      name: 'Runtime group',
+      parentPath: '/runtime/platform'
+    }
+    const localFolder: FolderWorkspace = {
+      id: 'shared-folder',
+      projectGroupId: localGroup.id,
+      name: 'Local folder',
+      folderPath: '/local/platform',
+      linkedTask: null,
+      comment: '',
+      isArchived: false,
+      isUnread: false,
+      isPinned: false,
+      sortOrder: 0,
+      lastActivityAt: 0,
+      createdAt: 1,
+      updatedAt: 1
+    }
+    const runtimeFolder = {
+      ...localFolder,
+      name: 'Runtime folder',
+      folderPath: '/runtime/platform'
+    }
+    runtimeEnvironmentCall.mockImplementation(async ({ method }) => ({
+      id: `rpc-${method}`,
+      ok: true,
+      result:
+        method === 'projectGroup.list'
+          ? { groups: [runtimeGroup] }
+          : { folderWorkspaces: [runtimeFolder] },
+      _meta: { runtimeId: 'runtime-remote' }
+    }))
+    const store = createTestStore()
+    store.setState({
+      projectGroups: [localGroup],
+      folderWorkspaces: [localFolder]
+    })
+
+    await store.getState().fetchProjectGroups({ runtimeEnvironmentId: 'env-1' })
+    await store.getState().fetchFolderWorkspaces({ runtimeEnvironmentId: 'env-1' })
+
+    expect(store.getState().projectGroups).toEqual([
+      localGroup,
+      { ...runtimeGroup, executionHostId: 'runtime:env-1' }
+    ])
+    expect(store.getState().folderWorkspaces).toEqual([
+      localFolder,
+      { ...runtimeFolder, executionHostId: 'runtime:env-1' }
+    ])
+  })
+
+  it('merges explicit runtime groups and folders without erasing local siblings', async () => {
+    const localGroup = { ...projectGroup, id: 'group-local', executionHostId: 'local' as const }
+    const runtimeGroup = { ...projectGroup, name: 'Runtime' }
+    const localFolder: FolderWorkspace = {
+      id: 'folder-local',
+      projectGroupId: localGroup.id,
+      name: 'Local folder',
+      folderPath: '/local/folder',
+      linkedTask: null,
+      comment: '',
+      isArchived: false,
+      isUnread: false,
+      isPinned: false,
+      sortOrder: 0,
+      lastActivityAt: 0,
+      createdAt: 1,
+      updatedAt: 1
+    }
+    const runtimeFolder = {
+      ...localFolder,
+      id: 'folder-runtime',
+      projectGroupId: runtimeGroup.id,
+      name: 'Runtime folder',
+      folderPath: '/runtime/folder'
+    }
+    runtimeEnvironmentCall.mockImplementation(async ({ method }) =>
+      method === 'projectGroup.list'
+        ? {
+            id: 'rpc-groups',
+            ok: true,
+            result: { groups: [runtimeGroup] },
+            _meta: { runtimeId: 'runtime-remote' }
+          }
+        : {
+            id: 'rpc-folders',
+            ok: true,
+            result: { folderWorkspaces: [runtimeFolder] },
+            _meta: { runtimeId: 'runtime-remote' }
+          }
+    )
+    const store = createTestStore()
+    store.setState({
+      settings: { activeRuntimeEnvironmentId: 'env-ambient' } as never,
+      projectGroups: [localGroup],
+      folderWorkspaces: [localFolder]
+    })
+
+    await store.getState().fetchProjectGroups({ runtimeEnvironmentId: 'env-1' })
+    await store.getState().fetchFolderWorkspaces({ runtimeEnvironmentId: 'env-1' })
+
+    expect(store.getState().projectGroups).toEqual([
+      localGroup,
+      { ...runtimeGroup, executionHostId: 'runtime:env-1' }
+    ])
+    expect(store.getState().folderWorkspaces).toEqual([
+      localFolder,
+      { ...runtimeFolder, executionHostId: 'runtime:env-1' }
+    ])
+
+    projectGroupsList.mockResolvedValue([localGroup])
+    folderWorkspacesList.mockResolvedValue([localFolder])
+    store.setState({ settings: { activeRuntimeEnvironmentId: null } as never })
+    await store.getState().fetchProjectGroups()
+    await store.getState().fetchFolderWorkspaces()
+
+    expect(store.getState().projectGroups).toEqual([
+      localGroup,
+      { ...runtimeGroup, executionHostId: 'runtime:env-1' }
+    ])
+    expect(store.getState().folderWorkspaces).toEqual([
+      { ...localFolder, executionHostId: 'local' },
+      { ...runtimeFolder, executionHostId: 'runtime:env-1' }
+    ])
+  })
+
+  it('keeps a selected-runtime import refresh across an overlapping local refresh', async () => {
+    const localRepo = { ...baseRepo, id: 'local-repo', path: '/local/repo' }
+    const runtimeRepo = {
+      ...baseRepo,
+      id: 'runtime-repo',
+      path: '/runtime/platform/api',
+      projectGroupId: projectGroup.id
+    }
+    const result = {
+      group: projectGroup,
+      repos: [{ path: runtimeRepo.path, projectId: runtimeRepo.id, status: 'imported' as const }],
+      importedCount: 1,
+      alreadyKnownCount: 0,
+      failedCount: 0
+    }
+    let resolveRuntimeRepos!: (value: unknown) => void
+    const runtimeRepos = new Promise((resolve) => {
+      resolveRuntimeRepos = resolve
+    })
+    runtimeEnvironmentCall.mockImplementation(({ method }) => {
+      const responses: Record<string, unknown> = {
+        'projectGroup.importNested': result,
+        'projectGroup.list': { groups: [projectGroup] },
+        'folderWorkspace.list': { folderWorkspaces: [] },
+        'project.list': { projects: [] },
+        'projectHostSetup.list': { setups: [] }
+      }
+      if (method === 'repo.list') {
+        return runtimeRepos
+      }
+      return Promise.resolve({
+        id: `rpc-${method}`,
+        ok: true,
+        result: responses[method],
+        _meta: { runtimeId: 'runtime-remote' }
+      })
+    })
+    reposList.mockResolvedValue([localRepo])
+    const store = createTestStore()
+
+    const importing = store.getState().importNestedRepos({
+      parentPath: '/runtime/platform',
+      groupName: 'Platform',
+      projectPaths: [runtimeRepo.path],
+      runtimeEnvironmentId: 'env-1',
+      mode: 'group'
+    })
+    await vi.waitFor(() =>
+      expect(runtimeEnvironmentCall).toHaveBeenCalledWith(
+        expect.objectContaining({ method: 'repo.list', selector: 'env-1' })
+      )
+    )
+    await store.getState().fetchRepos({ runtimeEnvironmentId: null })
+    resolveRuntimeRepos({
+      id: 'rpc-repos',
+      ok: true,
+      result: { repos: [runtimeRepo] },
+      _meta: { runtimeId: 'runtime-remote' }
+    })
+
+    await expect(importing).resolves.toEqual(result)
+    expect(store.getState().repos).toEqual(
+      expect.arrayContaining([
+        { ...localRepo, executionHostId: 'local' },
+        { ...runtimeRepo, executionHostId: 'runtime:env-1' }
+      ])
+    )
+  })
+
+  it('drops older same-host group and folder responses that finish last', async () => {
+    let resolveOldGroup!: (value: unknown) => void
+    let resolveNewGroup!: (value: unknown) => void
+    let resolveOldFolder!: (value: unknown) => void
+    let resolveNewFolder!: (value: unknown) => void
+    const groupResponses = [
+      new Promise((resolve) => {
+        resolveOldGroup = resolve
+      }),
+      new Promise((resolve) => {
+        resolveNewGroup = resolve
+      })
+    ]
+    const folderResponses = [
+      new Promise((resolve) => {
+        resolveOldFolder = resolve
+      }),
+      new Promise((resolve) => {
+        resolveNewFolder = resolve
+      })
+    ]
+    runtimeEnvironmentCall.mockImplementation(({ method }) => {
+      if (method === 'projectGroup.list') {
+        return groupResponses.shift()
+      }
+      if (method === 'folderWorkspace.list') {
+        return folderResponses.shift()
+      }
+      throw new Error(`Unexpected method: ${method}`)
+    })
+    const store = createTestStore()
+    const oldGroup = { ...projectGroup, id: 'group-old', parentPath: '/runtime/old' }
+    const newGroup = { ...projectGroup, id: 'group-new', parentPath: '/runtime/new' }
+    const oldFolder: FolderWorkspace = {
+      id: 'old-folder',
+      projectGroupId: oldGroup.id,
+      name: 'Old folder',
+      folderPath: '/runtime/old',
+      linkedTask: null,
+      comment: '',
+      isArchived: false,
+      isUnread: false,
+      isPinned: false,
+      sortOrder: 0,
+      lastActivityAt: 0,
+      createdAt: 1,
+      updatedAt: 1
+    }
+    const newFolder = {
+      ...oldFolder,
+      id: 'new-folder',
+      projectGroupId: newGroup.id,
+      name: 'New folder',
+      folderPath: '/runtime/new'
+    }
+
+    const oldGroupsRequest = store.getState().fetchProjectGroups({ runtimeEnvironmentId: 'env-1' })
+    const newGroupsRequest = store.getState().fetchProjectGroups({ runtimeEnvironmentId: 'env-1' })
+    resolveNewGroup({
+      id: 'rpc-new-group',
+      ok: true,
+      result: { groups: [newGroup] },
+      _meta: { runtimeId: 'runtime-remote' }
+    })
+    await newGroupsRequest
+    resolveOldGroup({
+      id: 'rpc-old-group',
+      ok: true,
+      result: { groups: [oldGroup] },
+      _meta: { runtimeId: 'runtime-remote' }
+    })
+    await oldGroupsRequest
+
+    store.setState({
+      projectGroups: [{ ...newGroup, executionHostId: 'runtime:env-1' }]
+    })
+    const oldFoldersRequest = store
+      .getState()
+      .fetchFolderWorkspaces({ runtimeEnvironmentId: 'env-1' })
+    const newFoldersRequest = store
+      .getState()
+      .fetchFolderWorkspaces({ runtimeEnvironmentId: 'env-1' })
+    resolveNewFolder({
+      id: 'rpc-new-folder',
+      ok: true,
+      result: { folderWorkspaces: [newFolder] },
+      _meta: { runtimeId: 'runtime-remote' }
+    })
+    await newFoldersRequest
+    resolveOldFolder({
+      id: 'rpc-old-folder',
+      ok: true,
+      result: { folderWorkspaces: [oldFolder] },
+      _meta: { runtimeId: 'runtime-remote' }
+    })
+    await oldFoldersRequest
+
+    expect(store.getState().projectGroups).toEqual([
+      { ...newGroup, executionHostId: 'runtime:env-1' }
+    ])
+    expect(store.getState().folderWorkspaces).toEqual([
+      { ...newFolder, executionHostId: 'runtime:env-1' }
+    ])
+  })
+
+  it('drops pre-reconnect group and folder responses without pruning the new catalog', async () => {
+    let resolveOldGroup!: (value: unknown) => void
+    let resolveOldFolder!: (value: unknown) => void
+    runtimeEnvironmentCall.mockImplementation(({ method }) => {
+      if (method === 'projectGroup.list') {
+        return new Promise((resolve) => {
+          resolveOldGroup = resolve
+        })
+      }
+      if (method === 'folderWorkspace.list') {
+        return new Promise((resolve) => {
+          resolveOldFolder = resolve
+        })
+      }
+      throw new Error(`Unexpected method: ${method}`)
+    })
+    const store = createTestStore()
+    store
+      .getState()
+      .setRuntimeEnvironments([{ id: 'env-1', createdAt: 1, pairingRevision: 1 } as never])
+    const pending = store.getState().fetchProjectGroups({ runtimeEnvironmentId: 'env-1' })
+    const pendingFolders = store.getState().fetchFolderWorkspaces({ runtimeEnvironmentId: 'env-1' })
+    await vi.waitFor(() => expect(resolveOldGroup).toBeTypeOf('function'))
+    await vi.waitFor(() => expect(resolveOldFolder).toBeTypeOf('function'))
+    store
+      .getState()
+      .setRuntimeEnvironments([{ id: 'env-1', createdAt: 1, pairingRevision: 2 } as never])
+    const newGroup = {
+      ...projectGroup,
+      id: 'group-after-reconnect',
+      executionHostId: 'runtime:env-1'
+    }
+    const newFolder: FolderWorkspace = {
+      id: 'folder-after-reconnect',
+      projectGroupId: newGroup.id,
+      name: 'New folder',
+      folderPath: '/runtime/new',
+      executionHostId: 'runtime:env-1',
+      linkedTask: null,
+      comment: '',
+      isArchived: false,
+      isUnread: false,
+      isPinned: false,
+      sortOrder: 0,
+      lastActivityAt: 0,
+      createdAt: 1,
+      updatedAt: 1
+    }
+    store.setState({ projectGroups: [newGroup], folderWorkspaces: [newFolder] })
+    resolveOldGroup({
+      id: 'rpc-before-reconnect',
+      ok: true,
+      result: { groups: [{ ...projectGroup, id: 'stale-group' }] },
+      _meta: { runtimeId: 'runtime-old' }
+    })
+    resolveOldFolder({
+      id: 'rpc-folder-before-reconnect',
+      ok: true,
+      result: {
+        folderWorkspaces: [
+          {
+            ...newFolder,
+            id: 'stale-folder',
+            executionHostId: undefined
+          }
+        ]
+      },
+      _meta: { runtimeId: 'runtime-old' }
+    })
+    await pending
+    await pendingFolders
+
+    expect(store.getState().projectGroups).toEqual([newGroup])
+    expect(store.getState().folderWorkspaces).toEqual([newFolder])
+  })
+
+  it('prunes deleted desktop and direct-SSH catalog rows without erasing runtime siblings', async () => {
+    const sshGroup = {
+      ...projectGroup,
+      id: 'ssh-group',
+      connectionId: 'ssh-1',
+      executionHostId: 'ssh:ssh-1'
+    }
+    const runtimeGroup = {
+      ...projectGroup,
+      id: sshGroup.id,
+      executionHostId: 'runtime:env-1'
+    }
+    const sshFolder: FolderWorkspace = {
+      id: 'ssh-folder',
+      projectGroupId: sshGroup.id,
+      name: 'SSH folder',
+      folderPath: '/srv/folder',
+      connectionId: 'ssh-1',
+      linkedTask: null,
+      comment: '',
+      isArchived: false,
+      isUnread: false,
+      isPinned: false,
+      sortOrder: 0,
+      lastActivityAt: 0,
+      createdAt: 1,
+      updatedAt: 1
+    }
+    const runtimeFolder = {
+      ...sshFolder,
+      id: sshFolder.id,
+      projectGroupId: runtimeGroup.id,
+      connectionId: null,
+      executionHostId: 'runtime:env-1' as const
+    }
+    projectGroupsList.mockResolvedValue([])
+    folderWorkspacesList.mockResolvedValue([])
+    const store = createTestStore()
+    store.setState({
+      projectGroups: [sshGroup, runtimeGroup],
+      folderWorkspaces: [sshFolder, runtimeFolder]
+    })
+
+    await store.getState().fetchProjectGroups({ runtimeEnvironmentId: null })
+    await store.getState().fetchFolderWorkspaces({ runtimeEnvironmentId: null })
+
+    expect(store.getState().projectGroups).toEqual([runtimeGroup])
+    expect(store.getState().folderWorkspaces).toEqual([runtimeFolder])
+  })
+
+  it('pins selected SSH scans and cancellation to local IPC over an ambient runtime', async () => {
+    const scan = {
+      selectedPath: '/srv/platform',
+      selectedPathKind: 'git_repo' as const,
+      repos: [],
+      truncated: false,
+      timedOut: false,
+      stopped: false,
+      durationMs: 1,
+      maxDepth: 3,
+      maxRepos: 100,
+      timeoutMs: null
+    }
+    projectGroupsScanNested.mockResolvedValue(scan)
+    projectGroupsCancelNestedScan.mockResolvedValue(true)
+    const store = createTestStore()
+    store.setState({ settings: { activeRuntimeEnvironmentId: 'env-ambient' } as never })
+
+    await expect(
+      store.getState().scanNestedRepos('/srv/platform', 'ssh-1', {
+        scanId: 'scan-ssh',
+        runtimeEnvironmentId: null
+      })
+    ).resolves.toEqual(scan)
+    await expect(
+      store.getState().cancelNestedRepoScan('scan-ssh', { runtimeEnvironmentId: null })
+    ).resolves.toBe(true)
+
+    expect(projectGroupsScanNested).toHaveBeenCalledWith({
+      path: '/srv/platform',
+      connectionId: 'ssh-1',
+      scanId: 'scan-ssh'
+    })
+    expect(projectGroupsCancelNestedScan).toHaveBeenCalledWith({ scanId: 'scan-ssh' })
+    expect(runtimeEnvironmentCall).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/renderer/src/store/slices/repos.ts b/src/renderer/src/store/slices/repos.ts
index dac56c84102..2c80b970dc6 100644
--- a/src/renderer/src/store/slices/repos.ts
+++ b/src/renderer/src/store/slices/repos.ts
@@ -65,7 +65,8 @@ import {
 import {
   assertRuntimeEnvironmentCapability,
   callRuntimeRpc,
-  getActiveRuntimeTarget
+  getActiveRuntimeTarget,
+  settingsForRuntimeOwner
 } from '../../runtime/runtime-rpc-client'
 import { syncRuntimeGitForkDefaultBranch } from '../../runtime/runtime-git-client'
 import { toRuntimeWorktreeSelector } from '../../runtime/runtime-worktree-selector'
@@ -102,6 +103,14 @@ const ERROR_TOAST_DURATION = 60_000
 const SAFE_AUTO_FORK_SYNC_COOLDOWN_MS = 10 * 60 * 1000
 const safeAutoForkSyncAttempts = new Map<string, { attemptedAt: number; promise?: Promise<void> }>()
 const runtimeRepoFetchGenerationByEnvironment = new Map<string, number>()
+type HostCatalogKind = 'project-groups' | 'folder-workspaces'
+type HostCatalogFence = {
+  key: string
+  generation: number
+  target: ReturnType<typeof getActiveRuntimeTarget>
+  sshStateGeneration: number | null
+  runtimeConnectionGeneration: number | null
+}
 
 export type RepoUpdate = Partial<
   Pick<
@@ -177,6 +186,11 @@ function getFolderWorkspaceUpdateCoordinator(
 type NestedRepoScanControls = {
   scanId?: string
   onProgress?: (scan: NestedRepoScanResult) => void
+  runtimeEnvironmentId?: string | null
+}
+
+type NestedRepoScanCancelOptions = {
+  runtimeEnvironmentId?: string | null
 }
 
 export type FolderWorkspacePathStatusCacheEntry = {
@@ -843,13 +857,18 @@ function mergeFetchedProjectCompatibilityForHost({
   }
 }
 
-function mergeById<T extends { id: string }>(base: readonly T[], overlay: readonly T[]): T[] {
+function mergeByIdentity<T>(
+  base: readonly T[],
+  overlay: readonly T[],
+  getIdentity: (entry: T) => string
+): T[] {
   const merged = [...base]
-  const indexById = new Map(merged.map((entry, index) => [entry.id, index]))
+  const indexById = new Map(merged.map((entry, index) => [getIdentity(entry), index]))
   for (const entry of overlay) {
-    const index = indexById.get(entry.id)
+    const identity = getIdentity(entry)
+    const index = indexById.get(identity)
     if (index === undefined) {
-      indexById.set(entry.id, merged.length)
+      indexById.set(identity, merged.length)
       merged.push(entry)
     } else {
       merged[index] = entry
@@ -940,17 +959,66 @@ function getProjectGroupHostId(group: Pick<ProjectGroup, 'connectionId' | 'execu
   return group.connectionId ? toSshExecutionHostId(group.connectionId) : LOCAL_EXECUTION_HOST_ID
 }
 
+function getProjectGroupHostIdentity(group: ProjectGroup): string {
+  return JSON.stringify([getProjectGroupHostId(group), group.id])
+}
+
+function catalogOwnsHost(catalogHostId: string, rowHostId: string): boolean {
+  if (catalogHostId !== LOCAL_EXECUTION_HOST_ID) {
+    return catalogHostId === rowHostId
+  }
+  return parseExecutionHostId(rowHostId)?.kind !== 'runtime'
+}
+
 function mergeFetchedProjectGroupsForHost(
   previous: readonly ProjectGroup[],
   fetched: ProjectGroup[],
   hostId: string
 ): ProjectGroup[] {
-  const fetchedIds = new Set(fetched.map((group) => group.id))
+  const fetchedIdentities = new Set(fetched.map(getProjectGroupHostIdentity))
   const preserved = previous.filter((group) => {
     const existingHostId = getProjectGroupHostId(group)
-    return existingHostId !== hostId || fetchedIds.has(group.id)
+    return (
+      !catalogOwnsHost(hostId, existingHostId) ||
+      fetchedIdentities.has(getProjectGroupHostIdentity(group))
+    )
   })
-  return mergeById(preserved, fetched)
+  return mergeByIdentity(preserved, fetched, getProjectGroupHostIdentity)
+}
+
+function getFolderWorkspaceHostId(
+  workspace: FolderWorkspace,
+  projectGroups: readonly ProjectGroup[]
+): ExecutionHostId {
+  const explicitHostId = parseExecutionHostId(workspace.executionHostId)?.id
+  if (explicitHostId) {
+    return explicitHostId
+  }
+  if (workspace.connectionId) {
+    return toSshExecutionHostId(workspace.connectionId)
+  }
+  const matchingHosts = new Set(
+    projectGroups
+      .filter((group) => group.id === workspace.projectGroupId)
+      .map(getProjectGroupHostId)
+  )
+  return matchingHosts.size === 1
+    ? ([...matchingHosts][0] as ExecutionHostId)
+    : LOCAL_EXECUTION_HOST_ID
+}
+
+function getFolderWorkspaceHostIdentity(
+  workspace: FolderWorkspace,
+  projectGroups: readonly ProjectGroup[]
+): string {
+  return JSON.stringify([getFolderWorkspaceHostId(workspace, projectGroups), workspace.id])
+}
+
+function getFolderWorkspaceUpdateIdentity(
+  hostId: ExecutionHostId,
+  folderWorkspaceId: string
+): string {
+  return `${hostId}\0${folderWorkspaceId}`
 }
 
 function mergeFetchedFolderWorkspacesForHost({
@@ -964,15 +1032,19 @@ function mergeFetchedFolderWorkspacesForHost({
   projectGroups: readonly ProjectGroup[]
   hostId: string
 }): FolderWorkspace[] {
-  const fetchedIds = new Set(fetched.map((workspace) => workspace.id))
-  const projectGroupHostIds = new Map(
-    projectGroups.map((group) => [group.id, getProjectGroupHostId(group)])
+  const fetchedIdentities = new Set(
+    fetched.map((workspace) => getFolderWorkspaceHostIdentity(workspace, projectGroups))
   )
   const preserved = previous.filter((workspace) => {
-    const existingHostId = projectGroupHostIds.get(workspace.projectGroupId)
-    return existingHostId === undefined || existingHostId !== hostId || fetchedIds.has(workspace.id)
+    const existingHostId = getFolderWorkspaceHostId(workspace, projectGroups)
+    return (
+      !catalogOwnsHost(hostId, existingHostId) ||
+      fetchedIdentities.has(getFolderWorkspaceHostIdentity(workspace, projectGroups))
+    )
   })
-  return mergeById(preserved, fetched)
+  return mergeByIdentity(preserved, fetched, (workspace) =>
+    getFolderWorkspaceHostIdentity(workspace, projectGroups)
+  )
 }
 
 type FetchedRepoCatalog = {
@@ -991,21 +1063,26 @@ type FetchedFolderWorkspaceCatalog = {
   hostId: ReturnType<typeof getRuntimeTargetHostId>
 }
 
-function getFolderWorkspaceCatalogReplacementIds(
+function getFolderWorkspaceCatalogReplacementIdentities(
   catalog: FetchedFolderWorkspaceCatalog,
   currentFolderWorkspaces: readonly FolderWorkspace[],
   projectGroups: readonly ProjectGroup[]
 ): Set<string> {
-  const replacedIds = new Set(catalog.folderWorkspaces.map((workspace) => workspace.id))
-  const projectGroupHostIds = new Map(
-    projectGroups.map((group) => [group.id, getProjectGroupHostId(group)])
+  const replacedIdentities = new Set(
+    catalog.folderWorkspaces.map((workspace) =>
+      getFolderWorkspaceUpdateIdentity(
+        getFolderWorkspaceHostId(workspace, projectGroups),
+        workspace.id
+      )
+    )
   )
   for (const workspace of currentFolderWorkspaces) {
-    if (projectGroupHostIds.get(workspace.projectGroupId) === catalog.hostId) {
-      replacedIds.add(workspace.id)
+    const hostId = getFolderWorkspaceHostId(workspace, projectGroups)
+    if (catalogOwnsHost(catalog.hostId, hostId)) {
+      replacedIdentities.add(getFolderWorkspaceUpdateIdentity(hostId, workspace.id))
     }
   }
-  return replacedIds
+  return replacedIdentities
 }
 
 async function fetchRepoCatalogForTarget(
@@ -1172,18 +1249,9 @@ function mergeFetchedProjectGroupCatalog(
   }
 }
 
-async function fetchProjectGroupsForTarget(
-  target: ReturnType<typeof getActiveRuntimeTarget>,
-  currentProjectGroups: readonly ProjectGroup[]
-): Promise<{ projectGroups: ProjectGroup[]; hostId: ReturnType<typeof getRuntimeTargetHostId> }> {
-  return mergeFetchedProjectGroupCatalog(
-    await fetchProjectGroupCatalogForTarget(target),
-    currentProjectGroups
-  )
-}
-
 async function fetchFolderWorkspaceCatalogForTarget(
-  target: ReturnType<typeof getActiveRuntimeTarget>
+  target: ReturnType<typeof getActiveRuntimeTarget>,
+  projectGroups: readonly ProjectGroup[]
 ): Promise<FetchedFolderWorkspaceCatalog> {
   const fetchedFolderWorkspaces =
     target.kind === 'local'
@@ -1197,11 +1265,27 @@ async function fetchFolderWorkspaceCatalogForTarget(
           )
         ).folderWorkspaces
   return {
-    folderWorkspaces: fetchedFolderWorkspaces,
+    folderWorkspaces: fetchedFolderWorkspaces.map((workspace) =>
+      folderWorkspaceWithFetchedOwner(workspace, target, projectGroups)
+    ),
     hostId: getRuntimeTargetHostId(target)
   }
 }
 
+function folderWorkspaceWithFetchedOwner(
+  workspace: FolderWorkspace,
+  target: ReturnType<typeof getActiveRuntimeTarget>,
+  projectGroups: readonly ProjectGroup[]
+): FolderWorkspace {
+  return {
+    ...workspace,
+    executionHostId:
+      target.kind === 'environment'
+        ? getRuntimeTargetHostId(target)
+        : getFolderWorkspaceHostId(workspace, projectGroups)
+  }
+}
+
 function mergeFetchedFolderWorkspaceCatalog(
   catalog: FetchedFolderWorkspaceCatalog,
   currentFolderWorkspaces: readonly FolderWorkspace[],
@@ -1224,14 +1308,19 @@ function mergeFetchedFolderWorkspaceCatalog(
 async function reconcileFailedFolderWorkspaceUpdate(args: {
   target: ReturnType<typeof getActiveRuntimeTarget>
   folderWorkspaceId: string
+  updateIdentity: string
+  ownerHostId: ExecutionHostId
   ticket: FolderWorkspaceUpdateTicket<FolderWorkspaceUpdateField>
   coordinator: FolderWorkspaceUpdateCoordinatorInstance
   set: Parameters<StateCreator<AppState>>[0]
   get: Parameters<StateCreator<AppState>>[1]
 }): Promise<void> {
   try {
-    const catalog = await fetchFolderWorkspaceCatalogForTarget(args.target)
-    const latestFields = args.coordinator.latestFields(args.folderWorkspaceId, args.ticket)
+    const catalog = await fetchFolderWorkspaceCatalogForTarget(
+      args.target,
+      args.get().projectGroups
+    )
+    const latestFields = args.coordinator.latestFields(args.updateIdentity, args.ticket)
     if (latestFields.length === 0) {
       return
     }
@@ -1241,11 +1330,16 @@ async function reconcileFailedFolderWorkspaceUpdate(args: {
     args.set((state) => ({
       folderWorkspaces: refreshed
         ? state.folderWorkspaces.map((workspace) =>
-            workspace.id === args.folderWorkspaceId
+            workspace.id === args.folderWorkspaceId &&
+            getFolderWorkspaceHostId(workspace, state.projectGroups) === args.ownerHostId
               ? mergeFolderWorkspaceUpdateResponse(workspace, refreshed, latestFields)
               : workspace
           )
-        : state.folderWorkspaces.filter((workspace) => workspace.id !== args.folderWorkspaceId),
+        : state.folderWorkspaces.filter(
+            (workspace) =>
+              workspace.id !== args.folderWorkspaceId ||
+              getFolderWorkspaceHostId(workspace, state.projectGroups) !== args.ownerHostId
+          ),
       ...(folderWorkspaceUpdateInvalidatesPathStatus(latestFields) || !refreshed
         ? { folderWorkspacePathStatuses: {} }
         : {})
@@ -1313,6 +1407,7 @@ function getRuntimeTargetCachePrefix(
 
 type FolderWorkspacePathStatusRouteOptions = { runtimeEnvironmentId?: string | null }
 type AddRepoPathRouteOptions = { runtimeEnvironmentId?: string | null }
+type RuntimeCatalogFetchOptions = { runtimeEnvironmentId?: string | null }
 
 function getFolderWorkspacePathStatusRouteSettings(
   options: FolderWorkspacePathStatusRouteOptions | undefined,
@@ -1534,13 +1629,13 @@ export type RepoSlice = {
   reposFetchGeneration: number
   pendingSshRepoReadoptions: SshRepoReadoption[]
   recordSshRepoReadoptions: (readoptions: SshRepoReadoption[]) => void
-  fetchRepos: () => Promise<void>
+  fetchRepos: (options?: RuntimeCatalogFetchOptions) => Promise<void>
   fetchReposForAllHosts: (options?: AllHostCatalogFetchOptions) => Promise<void>
   awaitLocalRepoCatalogSettlement: () => Promise<void>
   fetchRuntimeEnvironmentRepos: (environmentId: string) => Promise<Repo[]>
-  fetchProjectGroups: () => Promise<void>
+  fetchProjectGroups: (options?: RuntimeCatalogFetchOptions) => Promise<void>
   fetchProjectGroupsForAllHosts: (options?: AllHostCatalogFetchOptions) => Promise<void>
-  fetchFolderWorkspaces: () => Promise<void>
+  fetchFolderWorkspaces: (options?: RuntimeCatalogFetchOptions) => Promise<void>
   fetchFolderWorkspacesForAllHosts: (options?: AllHostCatalogFetchOptions) => Promise<void>
   addRepo: () => Promise<Repo | null>
   addRepoPath: (
@@ -1567,13 +1662,14 @@ export type RepoSlice = {
     connectionId?: string,
     controls?: NestedRepoScanControls
   ) => Promise<NestedRepoScanResult | null>
-  cancelNestedRepoScan: (scanId: string) => Promise<boolean>
+  cancelNestedRepoScan: (scanId: string, options?: NestedRepoScanCancelOptions) => Promise<boolean>
   importNestedRepos: (args: {
     parentPath: string
     groupName: string
     projectPaths: string[]
     connectionId?: string
     scanId?: string
+    runtimeEnvironmentId?: string | null
     mode: 'group' | 'separate'
   }) => Promise<ProjectGroupImportResult | null>
   createProjectGroup: (name: string) => Promise<ProjectGroup | null>
@@ -1604,7 +1700,8 @@ export type RepoSlice = {
   ) => Promise<FolderWorkspacePathStatus | null>
   updateFolderWorkspace: (
     folderWorkspaceId: string,
-    updates: FolderWorkspaceUpdates
+    updates: FolderWorkspaceUpdates,
+    options?: { executionHostId?: ExecutionHostId }
   ) => Promise<boolean>
   deleteFolderWorkspace: (folderWorkspaceId: string) => Promise<boolean>
   updateProjectGroup: (
@@ -1644,6 +1741,51 @@ const latestLocalRepoCatalogFetchByStore = new WeakMap<
 >()
 const latestRepoCatalogGenerationByHostByStore = new WeakMap<() => AppState, Map<string, number>>()
 const latestAllHostRepoCatalogGenerationByStore = new WeakMap<() => AppState, number>()
+const latestHostCatalogGenerationByStore = new WeakMap<() => AppState, Map<string, number>>()
+
+function claimHostCatalogFence(
+  get: () => AppState,
+  kind: HostCatalogKind,
+  target: ReturnType<typeof getActiveRuntimeTarget>
+): HostCatalogFence {
+  const key = `${kind}:${getRuntimeTargetHostId(target)}`
+  let generations = latestHostCatalogGenerationByStore.get(get)
+  if (!generations) {
+    generations = new Map()
+    latestHostCatalogGenerationByStore.set(get, generations)
+  }
+  const generation = (generations.get(key) ?? 0) + 1
+  generations.set(key, generation)
+  return {
+    key,
+    generation,
+    target,
+    sshStateGeneration:
+      target.kind === 'environment' ? getEnvironmentSshStateGeneration(target.environmentId) : null,
+    runtimeConnectionGeneration:
+      target.kind === 'environment'
+        ? getRuntimeEnvironmentConnectionGeneration(target.environmentId)
+        : null
+  }
+}
+
+function isHostCatalogFenceCurrent(get: () => AppState, fence: HostCatalogFence): boolean {
+  if (latestHostCatalogGenerationByStore.get(get)?.get(fence.key) !== fence.generation) {
+    return false
+  }
+  if (fence.target.kind !== 'environment') {
+    return true
+  }
+  return (
+    !isRemovedRuntimeHostId(
+      getRuntimeTargetHostId(fence.target),
+      get().removedRuntimeEnvironmentIds
+    ) &&
+    getEnvironmentSshStateGeneration(fence.target.environmentId) === fence.sshStateGeneration &&
+    getRuntimeEnvironmentConnectionGeneration(fence.target.environmentId) ===
+      fence.runtimeConnectionGeneration
+  )
+}
 
 function startLocalRepoCatalogFetch(
   get: () => AppState
@@ -1727,8 +1869,10 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
       }
     }),
 
-  fetchRepos: async () => {
-    const target = getActiveRuntimeTarget(get().settings)
+  fetchRepos: async (options) => {
+    const target = getActiveRuntimeTarget(
+      settingsForRuntimeOwner(get().settings, options?.runtimeEnvironmentId)
+    )
     const settleLocalCatalog: (outcome: LocalRepoCatalogFetchOutcome) => void =
       target.kind === 'local' ? startLocalRepoCatalogFetch(get) : () => undefined
     let localCatalogOutcome: LocalRepoCatalogFetchOutcome = { status: 'fulfilled' }
@@ -2006,14 +2150,25 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
 
   awaitLocalRepoCatalogSettlement: () => awaitLatestLocalRepoCatalogFetch(get),
 
-  fetchProjectGroups: async () => {
+  fetchProjectGroups: async (options) => {
     try {
-      const target = getActiveRuntimeTarget(get().settings)
-      const { projectGroups } = await fetchProjectGroupsForTarget(target, [])
-      set({
-        projectGroups,
-        folderWorkspacePathStatuses: {}
-      })
+      const target = getActiveRuntimeTarget(
+        settingsForRuntimeOwner(get().settings, options?.runtimeEnvironmentId)
+      )
+      const fence = claimHostCatalogFence(get, 'project-groups', target)
+      const catalog = await fetchProjectGroupCatalogForTarget(target)
+      if (!isHostCatalogFenceCurrent(get, fence)) {
+        return
+      }
+      set((current) =>
+        isHostCatalogFenceCurrent(get, fence)
+          ? {
+              projectGroups: mergeFetchedProjectGroupCatalog(catalog, current.projectGroups)
+                .projectGroups,
+              folderWorkspacePathStatuses: {}
+            }
+          : current
+      )
     } catch (err) {
       console.error('Failed to fetch project groups:', err)
     }
@@ -2021,15 +2176,25 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
 
   fetchProjectGroupsForAllHosts: async (options) => {
     // Why: startup renders an all-host sidebar; replacing groups with only the active host leaves other hosts' repos visible but ungrouped.
-    const applyCatalog = (catalog: FetchedProjectGroupCatalog): void => {
-      set((s) => ({
-        projectGroups: mergeFetchedProjectGroupCatalog(catalog, s.projectGroups).projectGroups,
-        folderWorkspacePathStatuses: {}
-      }))
+    const applyCatalog = (catalog: FetchedProjectGroupCatalog, fence: HostCatalogFence): void => {
+      if (!isHostCatalogFenceCurrent(get, fence)) {
+        return
+      }
+      set((s) =>
+        isHostCatalogFenceCurrent(get, fence)
+          ? {
+              projectGroups: mergeFetchedProjectGroupCatalog(catalog, s.projectGroups)
+                .projectGroups,
+              folderWorkspacePathStatuses: {}
+            }
+          : s
+      )
     }
 
     try {
-      applyCatalog(await fetchProjectGroupCatalogForTarget({ kind: 'local' }))
+      const target = { kind: 'local' as const }
+      const fence = claimHostCatalogFence(get, 'project-groups', target)
+      applyCatalog(await fetchProjectGroupCatalogForTarget(target), fence)
     } catch (err) {
       console.error('Failed to fetch local project groups for all-host load:', err)
     }
@@ -2040,13 +2205,13 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
     const environments = await listRuntimeEnvironmentsForAllHostLoad()
     await Promise.all(
       environments.map(async (environment) => {
+        const target = {
+          kind: 'environment' as const,
+          environmentId: environment.id
+        }
+        const fence = claimHostCatalogFence(get, 'project-groups', target)
         try {
-          applyCatalog(
-            await fetchProjectGroupCatalogForTarget({
-              kind: 'environment',
-              environmentId: environment.id
-            })
-          )
+          applyCatalog(await fetchProjectGroupCatalogForTarget(target), fence)
         } catch (err) {
           console.warn(`Skipped project groups for runtime environment ${environment.id}:`, err)
         }
@@ -2054,25 +2219,35 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
     )
   },
 
-  fetchFolderWorkspaces: async () => {
+  fetchFolderWorkspaces: async (options) => {
     try {
       const folderWorkspaceUpdates = getFolderWorkspaceUpdateCoordinator(get)
-      const target = getActiveRuntimeTarget(get().settings)
-      const catalog = await fetchFolderWorkspaceCatalogForTarget(target)
-      const current = get()
-      folderWorkspaceUpdates.recordCatalogReplacement(
-        getFolderWorkspaceCatalogReplacementIds(
+      const target = getActiveRuntimeTarget(
+        settingsForRuntimeOwner(get().settings, options?.runtimeEnvironmentId)
+      )
+      const fence = claimHostCatalogFence(get, 'folder-workspaces', target)
+      const catalog = await fetchFolderWorkspaceCatalogForTarget(target, get().projectGroups)
+      if (!isHostCatalogFenceCurrent(get, fence)) {
+        return
+      }
+      set((current) => {
+        if (!isHostCatalogFenceCurrent(get, fence)) {
+          return current
+        }
+        folderWorkspaceUpdates.recordCatalogReplacement(
+          getFolderWorkspaceCatalogReplacementIdentities(
+            catalog,
+            current.folderWorkspaces,
+            current.projectGroups
+          )
+        )
+        const { folderWorkspaces } = mergeFetchedFolderWorkspaceCatalog(
           catalog,
           current.folderWorkspaces,
           current.projectGroups
         )
-      )
-      const { folderWorkspaces } = mergeFetchedFolderWorkspaceCatalog(
-        catalog,
-        [],
-        current.projectGroups
-      )
-      set({ folderWorkspaces, folderWorkspacePathStatuses: {} })
+        return { folderWorkspaces, folderWorkspacePathStatuses: {} }
+      })
     } catch (err) {
       console.error('Failed to fetch folder workspaces:', err)
     }
@@ -2081,10 +2256,19 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
   fetchFolderWorkspacesForAllHosts: async (options) => {
     const folderWorkspaceUpdates = getFolderWorkspaceUpdateCoordinator(get)
     // Why: folder workspaces are owned through their project groups; fetch groups first, then merge each host's folder slice.
-    const applyCatalog = (catalog: FetchedFolderWorkspaceCatalog): void => {
+    const applyCatalog = (
+      catalog: FetchedFolderWorkspaceCatalog,
+      fence: HostCatalogFence
+    ): void => {
+      if (!isHostCatalogFenceCurrent(get, fence)) {
+        return
+      }
       set((current) => {
+        if (!isHostCatalogFenceCurrent(get, fence)) {
+          return current
+        }
         folderWorkspaceUpdates.recordCatalogReplacement(
-          getFolderWorkspaceCatalogReplacementIds(
+          getFolderWorkspaceCatalogReplacementIdentities(
             catalog,
             current.folderWorkspaces,
             current.projectGroups
@@ -2103,7 +2287,9 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
 
     let failed = false
     try {
-      applyCatalog(await fetchFolderWorkspaceCatalogForTarget({ kind: 'local' }))
+      const target = { kind: 'local' as const }
+      const fence = claimHostCatalogFence(get, 'folder-workspaces', target)
+      applyCatalog(await fetchFolderWorkspaceCatalogForTarget(target, get().projectGroups), fence)
     } catch (err) {
       failed = true
       console.error('Failed to fetch local folder workspaces for all-host load:', err)
@@ -2115,12 +2301,15 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
     const environments = await listRuntimeEnvironmentsForAllHostLoad()
     await Promise.all(
       environments.map(async (environment) => {
+        const target = {
+          kind: 'environment' as const,
+          environmentId: environment.id
+        }
+        const fence = claimHostCatalogFence(get, 'folder-workspaces', target)
         try {
           applyCatalog(
-            await fetchFolderWorkspaceCatalogForTarget({
-              kind: 'environment',
-              environmentId: environment.id
-            })
+            await fetchFolderWorkspaceCatalogForTarget(target, get().projectGroups),
+            fence
           )
         } catch (err) {
           failed = true
@@ -2196,7 +2385,9 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
 
   scanNestedRepos: async (path, connectionId, controls) => {
     try {
-      const target = getActiveRuntimeTarget(get().settings)
+      const target = getActiveRuntimeTarget(
+        settingsForRuntimeOwner(get().settings, controls?.runtimeEnvironmentId)
+      )
       if (target.kind === 'local') {
         const unsubscribe =
           controls?.scanId && controls.onProgress
@@ -2233,9 +2424,11 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
     }
   },
 
-  cancelNestedRepoScan: async (scanId) => {
+  cancelNestedRepoScan: async (scanId, options) => {
     try {
-      const target = getActiveRuntimeTarget(get().settings)
+      const target = getActiveRuntimeTarget(
+        settingsForRuntimeOwner(get().settings, options?.runtimeEnvironmentId)
+      )
       if (target.kind !== 'local') {
         return false
       }
@@ -2248,7 +2441,9 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
 
   importNestedRepos: async (args) => {
     try {
-      const target = getActiveRuntimeTarget(get().settings)
+      const target = getActiveRuntimeTarget(
+        settingsForRuntimeOwner(get().settings, args.runtimeEnvironmentId)
+      )
       const result =
         target.kind === 'local'
           ? await window.api.projectGroups.importNested(args)
@@ -2264,9 +2459,15 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
               },
               { timeoutMs: 60_000 }
             )
-      await get().fetchProjectGroups()
-      await get().fetchFolderWorkspaces()
-      await get().fetchRepos()
+      const catalogOptions =
+        'runtimeEnvironmentId' in args
+          ? { runtimeEnvironmentId: args.runtimeEnvironmentId }
+          : undefined
+      await get().fetchProjectGroups(catalogOptions)
+      await get().fetchFolderWorkspaces(catalogOptions)
+      await (args.runtimeEnvironmentId
+        ? get().fetchRuntimeEnvironmentRepos(args.runtimeEnvironmentId)
+        : get().fetchRepos(catalogOptions))
       set({ folderWorkspacePathStatuses: {} })
       return result
     } catch (err) {
@@ -2337,11 +2538,12 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
                 { timeoutMs: 15_000 }
               )
             ).folderWorkspace
+      const ownedWorkspace = folderWorkspaceWithFetchedOwner(workspace, target, get().projectGroups)
       set((s) => ({
-        folderWorkspaces: [workspace, ...s.folderWorkspaces],
+        folderWorkspaces: [ownedWorkspace, ...s.folderWorkspaces],
         folderWorkspacePathStatuses: {}
       }))
-      return workspace
+      return ownedWorkspace
     } catch (err) {
       console.error('Failed to create folder workspace:', err)
       const { title, description } = formatFolderWorkspaceCreateError(err)
@@ -2349,15 +2551,26 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
     }
   },
 
-  updateFolderWorkspace: async (folderWorkspaceId, updates) => {
+  updateFolderWorkspace: async (folderWorkspaceId, updates, options) => {
     const folderWorkspaceUpdates = getFolderWorkspaceUpdateCoordinator(get)
     const state = get()
-    if (!findFolderWorkspaceOwner(state, folderWorkspaceId)) {
+    const executionHostId =
+      options?.executionHostId ??
+      (state.activeWorktreeId === folderWorkspaceKey(folderWorkspaceId)
+        ? (state.activeWorkspaceExecutionHostId ?? undefined)
+        : undefined)
+    if (!findFolderWorkspaceOwner(state, folderWorkspaceId, executionHostId)) {
       return false
     }
-    const runtimeEnvironmentId = getRuntimeEnvironmentIdForFolderWorkspace(state, folderWorkspaceId)
+    const runtimeEnvironmentId = getRuntimeEnvironmentIdForFolderWorkspace(
+      state,
+      folderWorkspaceId,
+      executionHostId
+    )
     // Why: owner-scoped mutations must not follow whichever runtime happens to be focused.
     const target = getActiveRuntimeTarget({ activeRuntimeEnvironmentId: runtimeEnvironmentId })
+    const ownerHostId = executionHostId ?? getRuntimeTargetHostId(target)
+    const updateIdentity = getFolderWorkspaceUpdateIdentity(ownerHostId, folderWorkspaceId)
     // Why: same gate as folderWorkspace.create — an older paired runtime would drop the Jira link silently.
     if (
       target.kind === 'environment' &&
@@ -2371,7 +2584,7 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
       )
     }
     const updateTicket = folderWorkspaceUpdates.begin(
-      folderWorkspaceId,
+      updateIdentity,
       Object.keys(updates) as FolderWorkspaceUpdateField[]
     )
     try {
@@ -2390,6 +2603,8 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
         await reconcileFailedFolderWorkspaceUpdate({
           target,
           folderWorkspaceId,
+          updateIdentity,
+          ownerHostId,
           ticket: updateTicket,
           coordinator: folderWorkspaceUpdates,
           set,
@@ -2397,12 +2612,13 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
         })
         return false
       }
-      const latestFields = folderWorkspaceUpdates.latestFields(folderWorkspaceId, updateTicket)
-      const catalogChanged = folderWorkspaceUpdates.catalogChanged(folderWorkspaceId, updateTicket)
+      const latestFields = folderWorkspaceUpdates.latestFields(updateIdentity, updateTicket)
+      const catalogChanged = folderWorkspaceUpdates.catalogChanged(updateIdentity, updateTicket)
       if (latestFields.length > 0) {
         set((s) => ({
           folderWorkspaces: s.folderWorkspaces.map((workspace) =>
-            workspace.id === folderWorkspaceId
+            workspace.id === folderWorkspaceId &&
+            getFolderWorkspaceHostId(workspace, s.projectGroups) === ownerHostId
               ? mergeFolderWorkspaceUpdateResponse(workspace, updated, latestFields, {
                   rejectOlderResponse: catalogChanged
                 })
@@ -2419,6 +2635,8 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
       await reconcileFailedFolderWorkspaceUpdate({
         target,
         folderWorkspaceId,
+        updateIdentity,
+        ownerHostId,
         ticket: updateTicket,
         coordinator: folderWorkspaceUpdates,
         set,
@@ -2426,7 +2644,7 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
       })
       return false
     } finally {
-      folderWorkspaceUpdates.finish(folderWorkspaceId, updateTicket)
+      folderWorkspaceUpdates.finish(updateIdentity, updateTicket)
     }
   },
 
@@ -3028,8 +3246,16 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
       }
       await markOnboardingProjectAdded('addedFolder')
       // Why: focus the new folder so the add is visible; lazy-import worktree-activation to avoid a circular module load (it imports the store root).
-      await get().fetchWorktrees(repo.id)
-      const folderWorktree = get().worktreesByRepo[repo.id]?.[0]
+      const executionHostId =
+        options?.runtimeEnvironmentId === undefined
+          ? undefined
+          : options.runtimeEnvironmentId
+            ? toRuntimeExecutionHostId(options.runtimeEnvironmentId)
+            : LOCAL_EXECUTION_HOST_ID
+      await get().fetchWorktrees(repo.id, executionHostId ? { executionHostId } : undefined)
+      const folderWorktree = get().worktreesByRepo[repo.id]?.find(
+        (worktree) => executionHostId === undefined || worktree.hostId === executionHostId
+      )
       if (folderWorktree) {
         const { activateAndRevealWorktree } = await import('../../lib/worktree-activation')
         const onboarding = await window.api.onboarding.get().catch(() => null)
@@ -3041,6 +3267,7 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
         )
         activateAndRevealWorktree(folderWorktree.id, {
           sidebarRevealBehavior: 'auto',
+          ...(executionHostId ? { executionHostId } : {}),
           ...(startup ? { startup } : {})
         })
       }
@@ -3219,6 +3446,7 @@ export const createRepoSlice: StateCreator<AppState, [], [], RepoSlice> = (set,
                 activeView: 'terminal' as const,
                 activeWorktreeId: null,
                 activeWorkspaceKey: null,
+                activeWorkspaceExecutionHostId: null,
                 activeRepoId: null
               }
             : {})
diff --git a/src/renderer/src/store/slices/selected-host-active-workspace-identity.test.ts b/src/renderer/src/store/slices/selected-host-active-workspace-identity.test.ts
new file mode 100644
index 00000000000..a18fbfe23ce
--- /dev/null
+++ b/src/renderer/src/store/slices/selected-host-active-workspace-identity.test.ts
@@ -0,0 +1,185 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import type { ExecutionHostId } from '../../../../shared/execution-host'
+import type { Worktree } from '../../../../shared/types'
+import { getExecutionHostIdForWorktree } from '@/lib/worktree-runtime-owner'
+import { useAppStore } from '@/store'
+
+const SAME_REPO_ID = 'same-repo'
+const SAME_WORKTREE_ID = 'same-worktree'
+const RUNTIME_HOST: ExecutionHostId = 'runtime:env-1'
+
+function worktree(path: string, hostId: ExecutionHostId): Worktree {
+  return {
+    id: SAME_WORKTREE_ID,
+    repoId: SAME_REPO_ID,
+    path,
+    displayName: path,
+    comment: '',
+    linkedIssue: null,
+    linkedPR: null,
+    linkedLinearIssue: null,
+    isArchived: false,
+    isUnread: false,
+    isPinned: false,
+    sortOrder: 0,
+    lastActivityAt: 0,
+    head: 'abc',
+    branch: 'refs/heads/main',
+    isBare: false,
+    isMainWorktree: true,
+    hostId
+  }
+}
+
+afterEach(() => {
+  useAppStore.setState({
+    repos: [],
+    worktreesByRepo: {},
+    detectedWorktreesByRepo: {},
+    projectGroups: [],
+    folderWorkspaces: [],
+    activeRepoId: null,
+    activeWorktreeId: null,
+    activeWorkspaceKey: null,
+    activeWorkspaceExecutionHostId: null
+  } as never)
+})
+
+describe('selected-host active workspace identity', () => {
+  it('selects the runtime worktree when exact IDs collide in local-first order', () => {
+    const local = worktree('/local/repo', 'local')
+    const runtime = worktree('/runtime/repo', RUNTIME_HOST)
+    useAppStore.setState({
+      repos: [
+        {
+          id: SAME_REPO_ID,
+          path: local.path,
+          displayName: 'local',
+          badgeColor: '#000',
+          addedAt: 1,
+          executionHostId: 'local'
+        },
+        {
+          id: SAME_REPO_ID,
+          path: runtime.path,
+          displayName: 'runtime',
+          badgeColor: '#000',
+          addedAt: 2,
+          executionHostId: RUNTIME_HOST
+        }
+      ],
+      worktreesByRepo: { [SAME_REPO_ID]: [local, runtime] },
+      refreshGitHubForWorktreeIfStale: () => undefined
+    })
+
+    const selected = useAppStore.getState().getKnownWorktreeById(SAME_WORKTREE_ID, RUNTIME_HOST)
+    expect(selected?.path).toBe(runtime.path)
+
+    useAppStore.getState().setActiveWorktree(SAME_WORKTREE_ID, RUNTIME_HOST)
+    const state = useAppStore.getState()
+    expect(state.activeWorkspaceExecutionHostId).toBe(RUNTIME_HOST)
+    expect(getExecutionHostIdForWorktree(state, SAME_WORKTREE_ID)).toBe(RUNTIME_HOST)
+  })
+
+  it('selects the runtime worktree when exact-ID catalog order is reversed', () => {
+    const local = worktree('/local/repo', 'local')
+    const runtime = worktree('/runtime/repo', RUNTIME_HOST)
+    useAppStore.setState({
+      repos: [
+        {
+          id: SAME_REPO_ID,
+          path: runtime.path,
+          displayName: 'runtime',
+          badgeColor: '#000',
+          addedAt: 1,
+          executionHostId: RUNTIME_HOST
+        },
+        {
+          id: SAME_REPO_ID,
+          path: local.path,
+          displayName: 'local',
+          badgeColor: '#000',
+          addedAt: 2,
+          executionHostId: 'local'
+        }
+      ],
+      worktreesByRepo: { [SAME_REPO_ID]: [runtime, local] }
+    })
+
+    expect(useAppStore.getState().getKnownWorktreeById(SAME_WORKTREE_ID, RUNTIME_HOST)?.path).toBe(
+      runtime.path
+    )
+  })
+
+  it('keeps exact-ID folder and group activation on the selected runtime', () => {
+    useAppStore.setState({
+      projectGroups: [
+        {
+          id: 'same-group',
+          name: 'local',
+          parentPath: '/local',
+          executionHostId: 'local',
+          parentGroupId: null,
+          createdFrom: 'manual',
+          tabOrder: 0,
+          isCollapsed: false,
+          color: null,
+          createdAt: 1,
+          updatedAt: 1
+        },
+        {
+          id: 'same-group',
+          name: 'runtime',
+          parentPath: '/runtime',
+          executionHostId: RUNTIME_HOST,
+          parentGroupId: null,
+          createdFrom: 'manual',
+          tabOrder: 0,
+          isCollapsed: false,
+          color: null,
+          createdAt: 1,
+          updatedAt: 1
+        }
+      ],
+      folderWorkspaces: [
+        {
+          id: 'same-folder',
+          projectGroupId: 'same-group',
+          name: 'local',
+          folderPath: '/local/folder',
+          executionHostId: 'local',
+          linkedTask: null,
+          comment: '',
+          isArchived: false,
+          isUnread: false,
+          isPinned: false,
+          sortOrder: 0,
+          lastActivityAt: 0,
+          createdAt: 1,
+          updatedAt: 1
+        },
+        {
+          id: 'same-folder',
+          projectGroupId: 'same-group',
+          name: 'runtime',
+          folderPath: '/runtime/folder',
+          executionHostId: RUNTIME_HOST,
+          linkedTask: null,
+          comment: '',
+          isArchived: false,
+          isUnread: false,
+          isPinned: false,
+          sortOrder: 0,
+          lastActivityAt: 0,
+          createdAt: 1,
+          updatedAt: 1
+        }
+      ]
+    })
+
+    useAppStore.getState().setActiveFolderWorkspace('same-folder', RUNTIME_HOST)
+    const state = useAppStore.getState()
+    expect(state.activeWorkspaceExecutionHostId).toBe(RUNTIME_HOST)
+    expect(getExecutionHostIdForWorktree(state, 'folder:same-folder')).toBe(RUNTIME_HOST)
+  })
+})
diff --git a/src/renderer/src/store/slices/tabs.ts b/src/renderer/src/store/slices/tabs.ts
index b38aa980017..9574cd3a6d1 100644
--- a/src/renderer/src/store/slices/tabs.ts
+++ b/src/renderer/src/store/slices/tabs.ts
@@ -974,6 +974,7 @@ export const createTabsSlice: StateCreator<AppState, [], [], TabsSlice> = (set,
           ? {
               activeWorktreeId: null,
               activeWorkspaceKey: null,
+              activeWorkspaceExecutionHostId: null,
               activeTabId: null,
               activeBrowserTabId: null,
               activeFileId: null,
diff --git a/src/renderer/src/store/slices/terminals.ts b/src/renderer/src/store/slices/terminals.ts
index 27fd094bad7..2ff1dbc3c83 100644
--- a/src/renderer/src/store/slices/terminals.ts
+++ b/src/renderer/src/store/slices/terminals.ts
@@ -837,6 +837,7 @@ type WorkspaceHydrationPatch = Pick<
   | 'activeRepoId'
   | 'activeWorktreeId'
   | 'activeWorkspaceKey'
+  | 'activeWorkspaceExecutionHostId'
   | 'activeTabId'
   | 'activeTabIdByWorktree'
   | 'restoredRuntimeHostIdByWorkspaceSessionKey'
@@ -930,6 +931,9 @@ function targetScopedWorkspaceHydrationPatch(
     activeRepoId: activeOutsideScope ? state.activeRepoId : hydrated.activeRepoId,
     activeWorktreeId: activeOutsideScope ? state.activeWorktreeId : hydrated.activeWorktreeId,
     activeWorkspaceKey: activeOutsideScope ? state.activeWorkspaceKey : hydrated.activeWorkspaceKey,
+    activeWorkspaceExecutionHostId: activeOutsideScope
+      ? state.activeWorkspaceExecutionHostId
+      : hydrated.activeWorkspaceExecutionHostId,
     activeTabId: activeOutsideScope ? state.activeTabId : hydrated.activeTabId,
     activeTabIdByWorktree: replaceHydratedRecordKeys(
       state.activeTabIdByWorktree,
@@ -3805,6 +3809,10 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
               ? (activeWorktreeId as WorkspaceKey)
               : worktreeWorkspaceKey(activeWorktreeId)
             : null
+      const activeWorkspaceExecutionHostId =
+        activeWorkspaceKey && session.activeWorkspaceExecutionHostId
+          ? session.activeWorkspaceExecutionHostId
+          : null
       const activeTabId =
         session.activeTabId && validTabIds.has(session.activeTabId) ? session.activeTabId : null
       const activeRepoId =
@@ -3941,6 +3949,7 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         activeRepoId,
         activeWorktreeId,
         activeWorkspaceKey,
+        activeWorkspaceExecutionHostId,
         activeTabId,
         activeTabIdByWorktree,
         restoredRuntimeHostIdByWorkspaceSessionKey:
diff --git a/src/renderer/src/store/slices/worktree-helpers.ts b/src/renderer/src/store/slices/worktree-helpers.ts
index bb3a908f882..c102439987c 100644
--- a/src/renderer/src/store/slices/worktree-helpers.ts
+++ b/src/renderer/src/store/slices/worktree-helpers.ts
@@ -77,6 +77,7 @@ export type WorktreeSlice = {
   workspaceLineageByChildKey: Record<WorkspaceKey, WorkspaceLineage>
   activeWorktreeId: string | null
   activeWorkspaceKey: WorkspaceKey | null
+  activeWorkspaceExecutionHostId: ExecutionHostId | null
   /**
    * In-flight / failed background worktree creations, keyed by a renderer
    * `creationId`. Kept separate from `worktreesByRepo` on purpose — a real
@@ -146,7 +147,10 @@ export type WorktreeSlice = {
     (repoId: string, options?: WorktreeFetchOptions): Promise<boolean>
   }
   fetchAllWorktrees: (options?: { hydrationPurge?: 'allow' | 'defer' }) => Promise<void>
-  fetchWorktreeLineage: (options?: { forceLocalOwner?: boolean }) => Promise<void>
+  fetchWorktreeLineage: (options?: {
+    forceLocalOwner?: boolean
+    executionHostId?: ExecutionHostId
+  }) => Promise<void>
   updateWorktreeLineage: (
     worktreeId: string,
     args: { parentWorktreeId?: string; noParent?: boolean }
@@ -273,7 +277,7 @@ export type WorktreeSlice = {
    * fresh visit.
    */
   seedActiveWorktreeLastVisitedIfMissing: () => void
-  setActiveWorktree: (worktreeId: string | null) => void
+  setActiveWorktree: (worktreeId: string | null, executionHostId?: ExecutionHostId) => void
   /**
    * Health-driven remount of one terminal tab: bumps the tab's generation so
    * TerminalPane unmounts, detaches (preserving a live PTY), and remounts with
@@ -282,10 +286,13 @@ export type WorktreeSlice = {
    * undeliverable while the PTY is alive. Returns false when the tab is gone.
    */
   remountTerminalTabForRecovery: (tabId: string) => boolean
-  setActiveFolderWorkspace: (folderWorkspaceId: string) => void
+  setActiveFolderWorkspace: (folderWorkspaceId: string, executionHostId?: ExecutionHostId) => void
   setRenamingWorktreeId: (request: string | WorktreeRenameRequest | null) => void
   allWorktrees: () => Worktree[]
-  getKnownWorktreeById: (worktreeId: string) => Worktree | DetectedWorktree | undefined
+  getKnownWorktreeById: (
+    worktreeId: string,
+    executionHostId?: ExecutionHostId
+  ) => Worktree | DetectedWorktree | undefined
   /**
    * Wipes every terminal- and worktree-scoped map entry for each given id.
    * Called by the `worktrees:changed` listener on server-side deletions and
diff --git a/src/renderer/src/store/slices/worktrees.test.ts b/src/renderer/src/store/slices/worktrees.test.ts
index 44f45376fcf..cda7f0de246 100644
--- a/src/renderer/src/store/slices/worktrees.test.ts
+++ b/src/renderer/src/store/slices/worktrees.test.ts
@@ -2066,6 +2066,154 @@ describe('fetchWorktrees', () => {
     expect(store.getState().worktreesByRepo['same-repo']).toEqual([localWorktree])
   })
 
+  it('honors an explicit runtime owner before the repo catalog is hydrated', async () => {
+    const store = createTestStore()
+    const remote = makeWorktree({
+      id: 'repo-missing::/runtime/wt',
+      repoId: 'repo-missing',
+      path: '/runtime/wt',
+      hostId: 'local'
+    })
+    store.setState({
+      settings: { activeRuntimeEnvironmentId: null } as never,
+      repos: []
+    } as Partial<AppState>)
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-missing-repo',
+      ok: true,
+      result: makeDetectedResult('repo-missing', [remote]),
+      _meta: { runtimeId: 'runtime-remote' }
+    })
+
+    await store.getState().fetchWorktrees('repo-missing', {
+      executionHostId: 'runtime:env-1',
+      requireAuthoritative: true
+    })
+
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
+      selector: 'env-1',
+      method: 'worktree.detectedList',
+      params: { repo: 'repo-missing' },
+      timeoutMs: 15_000
+    })
+    expect(mockApi.worktrees.listDetected).not.toHaveBeenCalled()
+    expect(store.getState().worktreesByRepo['repo-missing']).toEqual([
+      { ...remote, hostId: 'runtime:env-1', runtimeOwnerEnvironmentId: 'env-1' }
+    ])
+  })
+
+  it('honors an explicit SSH owner before the repo catalog is hydrated', async () => {
+    const store = createTestStore()
+    const remote = makeWorktree({
+      id: 'repo-missing::/ssh/wt',
+      repoId: 'repo-missing',
+      path: '/ssh/wt',
+      hostId: 'local'
+    })
+    store.setState({
+      settings: { activeRuntimeEnvironmentId: 'env-ambient' } as never,
+      repos: []
+    } as Partial<AppState>)
+    mockApi.worktrees.listDetected.mockImplementationOnce(async (args: ListDetectedWorktreesArgs) =>
+      qualifyDetectedResult(args, makeDetectedResult('repo-missing', [remote]))
+    )
+
+    await store.getState().fetchWorktrees('repo-missing', {
+      executionHostId: 'ssh:ssh-1',
+      requireAuthoritative: true
+    })
+
+    expect(mockApi.worktrees.listDetected).toHaveBeenCalledWith(
+      expect.objectContaining({
+        repoId: 'repo-missing',
+        executionHostId: 'ssh:ssh-1',
+        expectedAuthority: TEST_SSH_AUTHORITY
+      })
+    )
+    expect(runtimeEnvironmentCall).not.toHaveBeenCalled()
+    expect(store.getState().worktreesByRepo['repo-missing']).toEqual([
+      { ...remote, hostId: 'ssh:ssh-1' }
+    ])
+  })
+
+  it('rejects a missing-owner SSH result after the repo catalog changes', async () => {
+    const store = createTestStore()
+    const remote = makeWorktree({
+      id: 'repo-missing::/ssh/wt',
+      repoId: 'repo-missing',
+      path: '/ssh/wt'
+    })
+    let release!: () => void
+    const started = new Promise<void>((resolve) => {
+      mockApi.worktrees.listDetected.mockImplementationOnce(
+        async (args: ListDetectedWorktreesArgs) => {
+          resolve()
+          await new Promise<void>((resume) => {
+            release = resume
+          })
+          return qualifyDetectedResult(args, makeDetectedResult('repo-missing', [remote]))
+        }
+      )
+    })
+
+    const refresh = store.getState().fetchWorktrees('repo-missing', {
+      executionHostId: 'ssh:ssh-1',
+      requireAuthoritative: true
+    })
+    await started
+    store.setState({ repos: [] })
+    release()
+
+    await expect(refresh).resolves.toBe(false)
+    expect(store.getState().worktreesByRepo['repo-missing']).toBeUndefined()
+  })
+
+  it('rejects a missing-owner SSH result after the provider reconnects', async () => {
+    const store = createTestStore()
+    const remote = makeWorktree({
+      id: 'repo-missing::/ssh/wt',
+      repoId: 'repo-missing',
+      path: '/ssh/wt'
+    })
+    let release!: () => void
+    const started = new Promise<void>((resolve) => {
+      mockApi.worktrees.listDetected.mockImplementationOnce(
+        async (args: ListDetectedWorktreesArgs) => {
+          resolve()
+          await new Promise<void>((resume) => {
+            release = resume
+          })
+          return qualifyDetectedResult(args, makeDetectedResult('repo-missing', [remote]))
+        }
+      )
+    })
+
+    const refresh = store.getState().fetchWorktrees('repo-missing', {
+      executionHostId: 'ssh:ssh-1',
+      requireAuthoritative: true
+    })
+    await started
+    store.setState({
+      sshConnectionStates: new Map([
+        [
+          TEST_SSH_AUTHORITY.targetId,
+          {
+            targetId: TEST_SSH_AUTHORITY.targetId,
+            status: 'connected',
+            error: null,
+            reconnectAttempt: 0,
+            providerEpoch: 'provider-ssh-2' as SshProviderEpoch,
+            connectionGeneration: TEST_SSH_AUTHORITY.connectionGeneration + 1
+          }
+        ]
+      ])
+    })
+    release()
+
+    await expect(refresh).resolves.toBe(false)
+    expect(store.getState().worktreesByRepo['repo-missing']).toBeUndefined()
+  })
+
   it('stamps remote runtime worktrees with the owning repo runtime host', async () => {
     const store = createTestStore()
     // Why: a remote runtime returns worktrees from its own perspective, so their hostId arrives as the default "local".
@@ -2667,6 +2815,31 @@ describe('worktree lineage state', () => {
     expect(store.getState().worktreeLineageById).toEqual({ [lineage.worktreeId]: lineage })
   })
 
+  it('pins lineage refresh to the event runtime when the default is local', async () => {
+    const store = createTestStore()
+    const lineage = makeLineage()
+    runtimeEnvironmentCall.mockResolvedValue({
+      id: 'rpc-lineage-list',
+      ok: true,
+      result: { lineage: { [lineage.worktreeId]: lineage } },
+      _meta: { runtimeId: 'runtime-remote' }
+    })
+    store.setState({
+      settings: { activeRuntimeEnvironmentId: null } as never,
+      worktreesByRepo: {}
+    } as Partial<AppState>)
+
+    await store.getState().fetchWorktreeLineage({ executionHostId: 'runtime:env-1' })
+
+    expect(runtimeEnvironmentCall).toHaveBeenCalledWith({
+      selector: 'env-1',
+      method: 'worktree.lineageList',
+      params: undefined,
+      timeoutMs: 15_000
+    })
+    expect(mockApi.worktrees.listLineage).not.toHaveBeenCalled()
+  })
+
   it('pins lineage refresh to the local host when forceLocalOwner is set', async () => {
     const store = createTestStore()
     const lineage = makeLineage()
diff --git a/src/renderer/src/store/slices/worktrees.ts b/src/renderer/src/store/slices/worktrees.ts
index f51e76fef6e..cf0474554a1 100644
--- a/src/renderer/src/store/slices/worktrees.ts
+++ b/src/renderer/src/store/slices/worktrees.ts
@@ -120,6 +120,7 @@ import type {
   SshExecutionHostId
 } from '../../../../shared/detected-worktree-provider-contract'
 import type { DirectSshAuthority } from '../../../../shared/ssh-types'
+import { findIndexedWorktreeOwnerForHost } from '@/lib/worktree-runtime-owner-index'
 export type { WorktreeSlice, WorktreeDeleteState } from './worktree-helpers'
 
 // Why: old runtime servers only have `worktree.list`; preserve the large-list UI hydration parity used before `worktree.detectedList` existed.
@@ -450,7 +451,10 @@ function repoHostId(
   hostId?: ExecutionHostId | null
 ): ExecutionHostId {
   const repo = findRepoForHost(state.repos, repoId, { hostId, settings: state.settings })
-  return repo ? getRepoExecutionHostId(repo) : LOCAL_EXECUTION_HOST_ID
+  if (repo) {
+    return getRepoExecutionHostId(repo)
+  }
+  return hostId && parseExecutionHostId(hostId) ? hostId : LOCAL_EXECUTION_HOST_ID
 }
 
 function repoHasExactlyOneExecutionHostOwner(
@@ -807,14 +811,29 @@ function applyDetectedWorktreeUpdates(
   return changed ? nextByRepo : detectedWorktreesByRepo
 }
 
+function folderWorkspaceMatchesHost(
+  workspace: Pick<FolderWorkspace, 'connectionId' | 'executionHostId'>,
+  executionHostId: ExecutionHostId
+): boolean {
+  return (
+    (parseExecutionHostId(workspace.executionHostId)?.id ??
+      (workspace.connectionId?.trim()
+        ? toSshExecutionHostId(workspace.connectionId)
+        : LOCAL_EXECUTION_HOST_ID)) === executionHostId
+  )
+}
+
 function findKnownWorktreeById(
   state: Pick<AppState, 'worktreesByRepo' | 'detectedWorktreesByRepo' | 'folderWorkspaces'>,
-  worktreeId: string
+  worktreeId: string,
+  executionHostId?: ExecutionHostId
 ): Worktree | DetectedWorktreeListResult['worktrees'][number] | undefined {
   const workspaceScope = parseWorkspaceKey(worktreeId)
   if (workspaceScope?.type === 'folder') {
     const folderWorkspace = state.folderWorkspaces.find(
-      (workspace) => workspace.id === workspaceScope.folderWorkspaceId
+      (workspace) =>
+        workspace.id === workspaceScope.folderWorkspaceId &&
+        (!executionHostId || folderWorkspaceMatchesHost(workspace, executionHostId))
     )
     if (!folderWorkspace) {
       return undefined
@@ -827,12 +846,25 @@ function findKnownWorktreeById(
     folderWorkspaceWorktreeCache.set(folderWorkspace, worktree)
     return worktree
   }
-  const visible = findWorktreeById(state.worktreesByRepo, worktreeId)
+  const visible = executionHostId
+    ? (findIndexedWorktreeOwnerForHost(
+        state.worktreesByRepo,
+        worktreeId,
+        executionHostId
+      ) as Worktree | null)
+    : findWorktreeById(state.worktreesByRepo, worktreeId)
   if (visible) {
     return visible
   }
   for (const result of Object.values(state.detectedWorktreesByRepo)) {
-    const detected = result.worktrees.find((worktree) => worktree.id === worktreeId)
+    const detected = result.worktrees.find(
+      (worktree) =>
+        worktree.id === worktreeId &&
+        (!executionHostId ||
+          worktreeMatchesHost(worktree, executionHostId, {
+            unhostedWorktreesMatchHost: executionHostId === LOCAL_EXECUTION_HOST_ID
+          }))
+    )
     if (detected) {
       return detected
     }
@@ -981,13 +1013,25 @@ function replaceWorktreeInRepoLists(
 function settingsForRepoOwner(
   state: Pick<AppState, 'repos' | 'settings'>,
   repoId: string,
-  hostId?: ExecutionHostId | null
+  hostId?: ExecutionHostId | null,
+  honorMissingHostId = false
 ) {
   const repo = findRepoForHost(state.repos, repoId, { hostId, settings: state.settings })
-  if (!repo) {
-    return state.settings
+  if (repo) {
+    return settingsForKnownRepoOwner(state.settings, repo)
   }
-  return settingsForKnownRepoOwner(state.settings, repo)
+  const parsedHost = honorMissingHostId && hostId ? parseExecutionHostId(hostId) : null
+  if (parsedHost?.kind === 'runtime') {
+    return state.settings
+      ? { ...state.settings, activeRuntimeEnvironmentId: parsedHost.environmentId }
+      : ({ activeRuntimeEnvironmentId: parsedHost.environmentId } as AppState['settings'])
+  }
+  if (parsedHost?.kind === 'local' || parsedHost?.kind === 'ssh') {
+    return state.settings
+      ? { ...state.settings, activeRuntimeEnvironmentId: null }
+      : ({ activeRuntimeEnvironmentId: null } as AppState['settings'])
+  }
+  return state.settings
 }
 
 function settingsForKnownRepoOwner(
@@ -2703,6 +2747,7 @@ function buildWorktreePurgeState(s: AppState, worktreeIds: string[]): Partial<Ap
       s.defaultTerminalTabsAppliedByWorktreeId
     ),
     activeWorktreeId: removedActive ? null : s.activeWorktreeId,
+    activeWorkspaceExecutionHostId: removedActive ? null : s.activeWorkspaceExecutionHostId,
     activeWorkspaceKey: (() => {
       if (s.activeWorkspaceKey && worktreeIdSet.has(s.activeWorkspaceKey)) {
         return null
@@ -2811,6 +2856,7 @@ type FencedWorktreeMergeArgs = {
   repoId: string
   hostId: ExecutionHostId
   ownerWasMissingAtStart: boolean
+  missingDirectSshOwnerReposSnapshot?: AppState['repos']
   requestStartedWorktrees: readonly Worktree[] | undefined
   setup?: ProjectHostSetup
   refresh: AdmittedDetectedWorktreeRefresh
@@ -2829,7 +2875,8 @@ function mergeFetchedWorktrees(
         s,
         args.repoId,
         args.hostId,
-        args.ownerWasMissingAtStart && !args.refresh.directSshAuthority
+        args.ownerWasMissingAtStart &&
+          (!args.refresh.directSshAuthority || s.repos === args.missingDirectSshOwnerReposSnapshot)
       )
     ) {
       return s
@@ -3017,6 +3064,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
   workspaceLineageByChildKey: {},
   activeWorktreeId: null,
   activeWorkspaceKey: null,
+  activeWorkspaceExecutionHostId: null,
   pendingWorktreeCreations: {},
   activePendingCreationId: null,
   renamingWorktreeId: null,
@@ -3127,7 +3175,12 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
         hostId,
         settings: ownerState.settings
       })
-      const ownerSettings = settingsForRepoOwner(ownerState, repoId, hostId)
+      const ownerSettings = settingsForRepoOwner(
+        ownerState,
+        repoId,
+        hostId,
+        ownerWasMissingAtStart && (useLocalOwner || options?.executionHostId !== undefined)
+      )
       const settings =
         useLocalOwner && ownerSettings?.activeRuntimeEnvironmentId
           ? { ...ownerSettings, activeRuntimeEnvironmentId: null }
@@ -3157,6 +3210,10 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
         repoId,
         hostId,
         ownerWasMissingAtStart,
+        missingDirectSshOwnerReposSnapshot:
+          ownerWasMissingAtStart && options?.executionHostId === hostId
+            ? ownerState.repos
+            : undefined,
         requestStartedWorktrees,
         setup,
         refresh
@@ -3340,12 +3397,18 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
     try {
       // Why: lineage is a focused-host refresh; host-merge so other hosts' fetched lineage is preserved.
       const ownerSettings = get().settings
-      // Why: local worktree-change events while a runtime is focused are paired
-      // with a forced-local list refresh; lineage must follow the same owner.
-      const settings =
-        options?.forceLocalOwner && ownerSettings?.activeRuntimeEnvironmentId
-          ? { ...ownerSettings, activeRuntimeEnvironmentId: null }
-          : ownerSettings
+      const parsedHost = options?.executionHostId
+        ? parseExecutionHostId(options.executionHostId)
+        : null
+      const activeRuntimeEnvironmentId =
+        parsedHost?.kind === 'runtime'
+          ? parsedHost.environmentId
+          : parsedHost || options?.forceLocalOwner
+            ? null
+            : ownerSettings?.activeRuntimeEnvironmentId
+      const settings = ownerSettings
+        ? { ...ownerSettings, activeRuntimeEnvironmentId }
+        : ({ activeRuntimeEnvironmentId } as AppState['settings'])
       await refreshWorktreeLineageForSettings(settings, set, {
         reuseRecentCompatibilityFailure: true
       })
@@ -4206,6 +4269,9 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
             return next
           })(),
           activeWorktreeId: removedActiveWorktree ? null : s.activeWorktreeId,
+          activeWorkspaceExecutionHostId: removedActiveWorktree
+            ? null
+            : s.activeWorkspaceExecutionHostId,
           activeTabId: s.activeTabId && tabIds.has(s.activeTabId) ? null : s.activeTabId,
           openFiles: newOpenFiles,
           browserTabsByWorktree: nextBrowserTabsByWorktree,
@@ -5041,8 +5107,11 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
           changed = true
         }
       }
-      const patch: { lastVisitedAtByWorktreeId?: Record<string, number>; activeWorktreeId?: null } =
-        {}
+      const patch: {
+        lastVisitedAtByWorktreeId?: Record<string, number>
+        activeWorktreeId?: null
+        activeWorkspaceExecutionHostId?: null
+      } = {}
       if (changed) {
         patch.lastVisitedAtByWorktreeId = next
       }
@@ -5059,6 +5128,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
         const activeRepoWorktreeIds = validIdsByRepo.get(getRepoIdFromWorktreeId(activeId))
         if (activeRepoWorktreeIds && !activeRepoWorktreeIds.has(activeId)) {
           patch.activeWorktreeId = null
+          patch.activeWorkspaceExecutionHostId = null
         }
       }
       return Object.keys(patch).length > 0 ? patch : {}
@@ -5121,7 +5191,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
     return remounted
   },
 
-  setActiveWorktree: (worktreeId) => {
+  setActiveWorktree: (worktreeId, executionHostId) => {
     const workspaceScope = worktreeId ? parseWorkspaceKey(worktreeId) : null
     if (worktreeId && shouldDeferActivationTerminalPrep()) {
       markInputQuietSchedulerInput()
@@ -5141,12 +5211,13 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
         return {
           activeWorktreeId: null,
           activeWorkspaceKey: null,
+          activeWorkspaceExecutionHostId: null,
           // Why: clearing/activating a worktree must dismiss the background-creation panel so the user isn't stranded on it.
           activePendingCreationId: null
         }
       }
 
-      const worktree = findKnownWorktreeById(s, worktreeId)
+      const worktree = findKnownWorktreeById(s, worktreeId, executionHostId)
       shouldClearUnread = Boolean(worktree?.isUnread)
 
       // Why: Search lives under Explorer, so the files/search sub-route must switch with the worktree, not leak the prior one.
@@ -5313,6 +5384,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
           : { ...s.activeTabTypeByWorktree, [worktreeId]: activeTabType }
       const hasStateChange =
         s.activeWorktreeId !== worktreeId ||
+        s.activeWorkspaceExecutionHostId !== (executionHostId ?? null) ||
         // Why: a pending-creation panel can show over the prior worktree; a non-null activePendingCreationId counts as a change.
         s.activePendingCreationId !== null ||
         s.activeFileId !== activeFileId ||
@@ -5337,6 +5409,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
         activeWorkspaceKey: isWorkspaceKey(worktreeId)
           ? worktreeId
           : worktreeWorkspaceKey(worktreeId),
+        activeWorkspaceExecutionHostId: executionHostId ?? null,
         activePendingCreationId: null,
         activeFileId,
         activeBrowserTabId,
@@ -5410,7 +5483,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
       get().refreshGitHubForWorktreeIfStale(worktreeId)
     }
 
-    if (!worktreeId || !get().getKnownWorktreeById(worktreeId)) {
+    if (!worktreeId || !get().getKnownWorktreeById(worktreeId, executionHostId)) {
       return
     }
 
@@ -5428,9 +5501,9 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
     }
   },
 
-  setActiveFolderWorkspace: (folderWorkspaceId) => {
+  setActiveFolderWorkspace: (folderWorkspaceId, executionHostId) => {
     const workspaceKey = folderWorkspaceKey(folderWorkspaceId)
-    const workspace = get().folderWorkspaces.find((entry) => entry.id === folderWorkspaceId)
+    const workspace = findKnownWorktreeById(get(), workspaceKey, executionHostId)
     if (!workspace) {
       return
     }
@@ -5516,6 +5589,7 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
         activeRepoId: null,
         activeWorktreeId: workspaceKey,
         activeWorkspaceKey: workspaceKey,
+        activeWorkspaceExecutionHostId: executionHostId ?? null,
         activePendingCreationId: null,
         activeFileId,
         activeBrowserTabId,
@@ -5528,19 +5602,27 @@ export const createWorktreeSlice: StateCreator<AppState, [], [], WorktreeSlice>
         everActivatedWorktreeIds: nextEverActivated,
         folderWorkspaces: workspace.isUnread
           ? s.folderWorkspaces.map((entry) =>
-              entry.id === folderWorkspaceId ? { ...entry, isUnread: false } : entry
+              entry.id === folderWorkspaceId &&
+              (!executionHostId || folderWorkspaceMatchesHost(entry, executionHostId))
+                ? { ...entry, isUnread: false }
+                : entry
             )
           : s.folderWorkspaces
       }
     })
     if (workspace.isUnread) {
-      void get().updateFolderWorkspace(folderWorkspaceId, { isUnread: false })
+      void get().updateFolderWorkspace(
+        folderWorkspaceId,
+        { isUnread: false },
+        executionHostId ? { executionHostId } : undefined
+      )
     }
   },
 
   allWorktrees: () => Object.values(get().worktreesByRepo).flat(),
 
-  getKnownWorktreeById: (worktreeId) => findKnownWorktreeById(get(), worktreeId),
+  getKnownWorktreeById: (worktreeId, executionHostId) =>
+    findKnownWorktreeById(get(), worktreeId, executionHostId),
 
   purgeWorktreeTerminalState: (worktreeIds: string[]) => {
     const purgeableWorktreeIds = worktreeIds.filter((id) => id !== FLOATING_TERMINAL_WORKTREE_ID)
diff --git a/src/shared/folder-workspace-worktree.ts b/src/shared/folder-workspace-worktree.ts
index 0eb22423723..0b427f42407 100644
--- a/src/shared/folder-workspace-worktree.ts
+++ b/src/shared/folder-workspace-worktree.ts
@@ -1,5 +1,6 @@
 import type { FolderWorkspace, Worktree } from './types'
 import { folderWorkspaceKey } from './workspace-scope'
+import { toSshExecutionHostId } from './execution-host'
 
 export function folderWorkspaceToWorktree(folderWorkspace: FolderWorkspace): Worktree {
   const linkedTask = folderWorkspace.linkedTask
@@ -37,6 +38,9 @@ export function folderWorkspaceToWorktree(folderWorkspace: FolderWorkspace): Wor
     branch: '',
     isBare: false,
     isSparse: false,
-    isMainWorktree: false
+    isMainWorktree: false,
+    hostId:
+      folderWorkspace.executionHostId ??
+      (folderWorkspace.connectionId ? toSshExecutionHostId(folderWorkspace.connectionId) : 'local')
   }
 }
diff --git a/src/shared/pr-check-status.ts b/src/shared/pr-check-status.ts
index bf7dd5f085c..2f8e68e1546 100644
--- a/src/shared/pr-check-status.ts
+++ b/src/shared/pr-check-status.ts
@@ -45,7 +45,11 @@ function normalizeRollupCheck(raw: RawCheckRollup, index: number): PRCheckDetail
     conclusion === 'error' || conclusion === 'startup_failure'
       ? 'failure'
       : conclusion ||
-        (state === 'failure' || state === 'error' ? 'failure' : state === 'success' ? 'success' : '')
+        (state === 'failure' || state === 'error'
+          ? 'failure'
+          : state === 'success'
+            ? 'success'
+            : '')
   const isPending =
     status === 'queued' ||
     status === 'in_progress' ||
diff --git a/src/shared/types.ts b/src/shared/types.ts
index fa6ca7b9f91..f713ada0645 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -328,6 +328,8 @@ export type FolderWorkspace = {
   folderPath: string
   /** SSH target ID for folder workspaces whose folder path lives remotely. */
   connectionId?: string | null
+  /** Renderer-owned host stamp for host-qualified folder catalogs. */
+  executionHostId?: ExecutionHostId | null
   linkedTask: WorkspaceLinkedItem | null
   linkedTaskSourceContext?: TaskSourceContext | null
   comment: string
@@ -1117,6 +1119,7 @@ export type WorkspaceSessionState = {
   activeRepoId: string | null
   /** Scope-aware active owner for folder workspaces. Legacy worktree UI still reads activeWorktreeId. */
   activeWorkspaceKey?: WorkspaceKey | null
+  activeWorkspaceExecutionHostId?: ExecutionHostId | null
   activeWorktreeId: string | null
   activeTabId: string | null
   /** Keys may be legacy raw worktree IDs or canonical WorkspaceKey values. */
diff --git a/src/shared/workspace-session-schema.ts b/src/shared/workspace-session-schema.ts
index 72ebd026e0a..da5fe4ef08e 100644
--- a/src/shared/workspace-session-schema.ts
+++ b/src/shared/workspace-session-schema.ts
@@ -18,6 +18,7 @@ import type {
   WorkspaceSessionState
 } from './types'
 import { isValidTerminalTabId } from './terminal-tab-id'
+import { parseExecutionHostId, type ExecutionHostId } from './execution-host'
 import { isTuiAgent } from './tui-agent-config'
 import { normalizeBrowserHistoryEntries } from './workspace-session-browser-history'
 import { isWorkspaceKey } from './workspace-scope'
@@ -250,6 +251,12 @@ const browserHistoryEntriesSchema = z
 export const workspaceSessionStateSchema: z.ZodType<WorkspaceSessionState> = z.object({
   activeRepoId: z.string().nullable(),
   activeWorkspaceKey: workspaceKeySchema.nullable().optional(),
+  activeWorkspaceExecutionHostId: z
+    .custom<ExecutionHostId>(
+      (value) => typeof value === 'string' && Boolean(parseExecutionHostId(value))
+    )
+    .nullable()
+    .optional(),
   activeWorktreeId: z.string().nullable(),
   activeTabId: z.string().nullable(),
   tabsByWorktree: z.record(z.string(), z.array(terminalTabSchema)),
diff --git a/src/shared/workspace-session-terminal-tab-close.ts b/src/shared/workspace-session-terminal-tab-close.ts
index 2b0b17a9d3a..e5f2d6cd28a 100644
--- a/src/shared/workspace-session-terminal-tab-close.ts
+++ b/src/shared/workspace-session-terminal-tab-close.ts
@@ -265,6 +265,7 @@ export function closeTerminalTabInWorkspaceSession(
     if (!hasSurface) {
       next.activeWorktreeId = null
       next.activeWorkspaceKey = null
+      next.activeWorkspaceExecutionHostId = null
     }
   }
   if ((next.tabsByWorktree[worktreeId]?.length ?? 0) === 0) {
diff --git a/tests/e2e/pr11346-selected-runtime-add.spec.ts b/tests/e2e/pr11346-selected-runtime-add.spec.ts
new file mode 100644
index 00000000000..f4e86d8b0f5
--- /dev/null
+++ b/tests/e2e/pr11346-selected-runtime-add.spec.ts
@@ -0,0 +1,757 @@
+import { rmSync } from 'node:fs'
+import path from 'node:path'
+import type { ElectronApplication, Locator, Page, TestInfo } from '@stablyai/playwright-test'
+import { RuntimeClient } from '../../src/cli/runtime/client'
+import type { FolderWorkspace, ProjectGroup, Repo } from '../../src/shared/types'
+import { expect, test } from './helpers/orca-app'
+import {
+  createRuntimeDesktopPairingOffer,
+  launchPairedElectronClient
+} from './helpers/paired-electron-client'
+import { waitForSessionReady } from './helpers/store'
+import {
+  configureIsolatedGitIdentity,
+  createProjectFixtures,
+  expectRuntimeActivation,
+  injectSameIdLocalActivationCollision,
+  installFinalActivationGate
+} from './pr11346-selected-runtime-identity-oracle'
+
+async function selectRuntimeHost(page: Page, runtimeName: string): Promise<Locator> {
+  await page
+    .getByRole('button', { name: /Add Project/i })
+    .first()
+    .click()
+  const dialog = page.getByRole('dialog', { name: /Add a project/i })
+  await expect(dialog).toBeVisible()
+  const hostPicker = dialog.getByRole('combobox')
+  if (!(await hostPicker.textContent())?.includes(runtimeName)) {
+    await hostPicker.click()
+    await page.locator('[cmdk-item]').filter({ hasText: runtimeName }).click()
+  }
+  await expect(hostPicker).toContainText(runtimeName)
+  return dialog
+}
+
+async function selectRuntimeHostAndOpenManualPath(
+  page: Page,
+  runtimeName: string
+): Promise<Locator> {
+  const dialog = await selectRuntimeHost(page, runtimeName)
+  await dialog.getByRole('button', { name: /Browse folder|Browse host/i }).click()
+  const browseDialog = page.getByRole('dialog', { name: /Browse host filesystem/i })
+  await expect(browseDialog).toBeVisible()
+  await browseDialog.getByRole('button', { name: /^Cancel$/i }).click()
+  const manualDialog = page.getByRole('dialog', { name: /Open host project/i })
+  await expect(manualDialog.locator('#server-project-path')).toBeVisible()
+  return manualDialog
+}
+
+async function listRuntimeInventory(client: RuntimeClient): Promise<{
+  folderWorkspaces: FolderWorkspace[]
+  projectGroups: ProjectGroup[]
+  repos: Repo[]
+}> {
+  const [repoResult, folderResult, projectGroupResult] = await Promise.all([
+    client.call<{ repos: Repo[] }>('repo.list'),
+    client.call<{ folderWorkspaces: FolderWorkspace[] }>('folderWorkspace.list'),
+    client.call<{ groups: ProjectGroup[] }>('projectGroup.list')
+  ])
+  return {
+    repos: repoResult.result.repos,
+    folderWorkspaces: folderResult.result.folderWorkspaces,
+    projectGroups: projectGroupResult.result.groups
+  }
+}
+
+async function setActiveRuntimePreference(page: Page, environmentId: string | null): Promise<void> {
+  const selected = await page.evaluate(async (nextEnvironmentId) => {
+    const next = await window.api.settings.setActiveRuntimeEnvironmentPreference({
+      environmentId: nextEnvironmentId
+    })
+    window.__store?.setState({ settings: next })
+    return next.activeRuntimeEnvironmentId
+  }, environmentId)
+  expect(selected).toBe(environmentId)
+}
+
+async function runSelectedRuntimeAddJourney(
+  electronApp: ElectronApplication,
+  orcaPage: Page,
+  testInfo: TestInfo,
+  visible: boolean
+): Promise<void> {
+  const runtimeName = `PR 11346 ${visible ? 'headed' : 'hidden-window'} runtime`
+  const fixture = await createProjectFixtures()
+  await waitForSessionReady(orcaPage)
+  const serverVisible = await electronApp.evaluate(({ BrowserWindow }) =>
+    BrowserWindow.getAllWindows().some((window) => window.isVisible())
+  )
+  expect(serverVisible).toBe(visible)
+  configureIsolatedGitIdentity(await electronApp.evaluate(({ app }) => app.getPath('home')))
+
+  const offer = await createRuntimeDesktopPairingOffer(orcaPage)
+  const client = await launchPairedElectronClient(offer, testInfo, runtimeName)
+  const serverUserDataDir = await electronApp.evaluate(({ app }) => app.getPath('userData'))
+  const clientUserDataDir = await client.app.evaluate(({ app }) => app.getPath('userData'))
+  const serverRuntime = new RuntimeClient(serverUserDataDir)
+  const clientLocalRuntime = new RuntimeClient(clientUserDataDir)
+
+  try {
+    const measurements: Record<string, number> = {}
+    if (visible) {
+      await client.app.evaluate(({ BrowserWindow }) => {
+        BrowserWindow.getAllWindows()[0]?.show()
+      })
+      expect(
+        await client.app.evaluate(
+          ({ BrowserWindow }) => BrowserWindow.getAllWindows()[0]?.isVisible() ?? false
+        )
+      ).toBe(true)
+    }
+    let startedAt = Date.now()
+    await setActiveRuntimePreference(client.page, null)
+    await setActiveRuntimePreference(client.page, client.environmentId)
+    await setActiveRuntimePreference(client.page, null)
+    measurements.runtimeSwitchMs = Date.now() - startedAt
+
+    const initialServerInventory = await listRuntimeInventory(serverRuntime)
+    const initialClientInventory = await listRuntimeInventory(clientLocalRuntime)
+    expect(initialServerInventory.repos.map((repo) => repo.path)).not.toContain(fixture.gitPath)
+    expect(initialClientInventory.repos.map((repo) => repo.path)).not.toContain(fixture.gitPath)
+
+    startedAt = Date.now()
+    await installFinalActivationGate(client.page, fixture.gitPath)
+    const gitDialog = await selectRuntimeHostAndOpenManualPath(client.page, runtimeName)
+    await gitDialog.locator('#server-project-path').fill(fixture.gitPath)
+    await gitDialog.getByRole('button', { name: /Add Git Project/i }).click()
+    const gitCollision = await injectSameIdLocalActivationCollision(
+      client.page,
+      fixture.gitPath,
+      fixture.localCloneCollisionPath
+    )
+    await expect(gitDialog).toBeHidden({ timeout: 30_000 })
+    measurements.gitAddMs = Date.now() - startedAt
+
+    startedAt = Date.now()
+    await installFinalActivationGate(client.page, fixture.folderPath)
+    const folderDialog = await selectRuntimeHostAndOpenManualPath(client.page, runtimeName)
+    await folderDialog.locator('#server-project-path').fill(fixture.folderPath)
+    await folderDialog.getByRole('button', { name: /Open as Folder/i }).click()
+    const folderCollision = await injectSameIdLocalActivationCollision(
+      client.page,
+      fixture.folderPath,
+      fixture.localCreateCollisionPath
+    )
+    await expect(folderDialog).toBeHidden({ timeout: 30_000 })
+    measurements.folderAddMs = Date.now() - startedAt
+
+    startedAt = Date.now()
+    await installFinalActivationGate(client.page, fixture.clonedRepoPath)
+    const cloneDialog = await selectRuntimeHost(client.page, runtimeName)
+    await cloneDialog.getByRole('button', { name: /Clone from URL/i }).click()
+    const cloneStep = client.page.getByRole('dialog', { name: /Clone from URL/i })
+    await cloneStep.getByRole('textbox').nth(0).fill(fixture.gitPath)
+    await cloneStep.getByRole('textbox').nth(1).fill(fixture.cloneParentPath)
+    await cloneStep.getByRole('button', { name: /^Clone$/i }).click()
+    const cloneCollision = await injectSameIdLocalActivationCollision(
+      client.page,
+      fixture.clonedRepoPath,
+      fixture.localCloneCollisionPath
+    )
+    await expect(cloneStep).toBeHidden({ timeout: 30_000 })
+    await expectRuntimeActivation(client.page, cloneCollision)
+    measurements.cloneMs = Date.now() - startedAt
+
+    startedAt = Date.now()
+    await installFinalActivationGate(client.page, fixture.createdRepoPath)
+    const createDialog = await selectRuntimeHost(client.page, runtimeName)
+    await createDialog.getByRole('button', { name: /Create (?:on host|new project)/i }).click()
+    const createStep = client.page.getByRole('dialog', { name: /Create a new project/i })
+    await createStep.locator('#create-project-name').fill('runtime-created-project')
+    await createStep.getByPlaceholder('/home/user/projects').fill(fixture.createParentPath)
+    await createStep.getByRole('button', { name: 'Create project', exact: true }).click()
+    const createCollision = await injectSameIdLocalActivationCollision(
+      client.page,
+      fixture.createdRepoPath,
+      fixture.localCreateCollisionPath
+    )
+    await expect(createStep).toBeHidden({ timeout: 30_000 })
+    await expectRuntimeActivation(client.page, createCollision)
+    measurements.createMs = Date.now() - startedAt
+
+    startedAt = Date.now()
+    const reconnectCatalog = await client.page.evaluate(
+      async ({ environmentId, reconnectCatalogPath }) => {
+        const store = window.__store
+        if (!store) {
+          throw new Error('Renderer store unavailable')
+        }
+        const oldRequests = [
+          store.getState().fetchProjectGroups({ runtimeEnvironmentId: environmentId }),
+          store.getState().fetchFolderWorkspaces({ runtimeEnvironmentId: environmentId })
+        ]
+        await window.api.runtimeEnvironments.disconnect({ selector: environmentId })
+        store.getState().setRuntimeEnvironmentStatus(environmentId, {
+          status: null,
+          checkedAt: Date.now()
+        })
+        const response = await window.api.runtimeEnvironments.connect({
+          selector: environmentId,
+          timeoutMs: 15_000
+        })
+        if (!response.ok) {
+          throw new Error(response.error.message)
+        }
+        store.getState().setRuntimeEnvironmentStatus(environmentId, {
+          status: response.result,
+          checkedAt: Date.now()
+        })
+        const groupResponse = await window.api.runtimeEnvironments.call({
+          selector: environmentId,
+          method: 'projectGroup.create',
+          params: {
+            name: 'Reconnect catalog',
+            parentPath: reconnectCatalogPath,
+            createdFrom: 'manual'
+          },
+          timeoutMs: 15_000
+        })
+        if (!groupResponse.ok) {
+          throw new Error(groupResponse.error.message)
+        }
+        const group = (groupResponse.result as { group: ProjectGroup }).group
+        const folderResponse = await window.api.runtimeEnvironments.call({
+          selector: environmentId,
+          method: 'folderWorkspace.create',
+          params: {
+            folderPath: reconnectCatalogPath,
+            name: 'Reconnect catalog workspace',
+            projectGroupId: group.id
+          },
+          timeoutMs: 15_000
+        })
+        if (!folderResponse.ok) {
+          throw new Error(folderResponse.error.message)
+        }
+        await store.getState().fetchProjectGroups({ runtimeEnvironmentId: environmentId })
+        await store.getState().fetchFolderWorkspaces({ runtimeEnvironmentId: environmentId })
+        await Promise.allSettled(oldRequests)
+        if (!(await store.getState().refreshRuntimeEnvironmentStatus(environmentId))) {
+          throw new Error('Paired runtime did not recover after reconnect')
+        }
+        return {
+          folder: store
+            .getState()
+            .folderWorkspaces.find((workspace) => workspace.folderPath === reconnectCatalogPath),
+          group: store
+            .getState()
+            .projectGroups.find((entry) => entry.parentPath === reconnectCatalogPath)
+        }
+      },
+      {
+        environmentId: client.environmentId,
+        reconnectCatalogPath: fixture.reconnectCatalogPath
+      }
+    )
+    expect(reconnectCatalog).toEqual({
+      folder: expect.objectContaining({
+        executionHostId: `runtime:${client.environmentId}`,
+        folderPath: fixture.reconnectCatalogPath
+      }),
+      group: expect.objectContaining({
+        executionHostId: `runtime:${client.environmentId}`,
+        parentPath: fixture.reconnectCatalogPath
+      })
+    })
+    await setActiveRuntimePreference(client.page, client.environmentId)
+    await setActiveRuntimePreference(client.page, null)
+    measurements.reconnectMs = Date.now() - startedAt
+
+    startedAt = Date.now()
+    const nestedDialog = await selectRuntimeHostAndOpenManualPath(client.page, runtimeName)
+    await nestedDialog.locator('#server-project-path').fill(fixture.nestedParentPath)
+    await nestedDialog.getByRole('button', { name: /Add Git Project/i }).click()
+    const importDialog = client.page.getByRole('dialog', {
+      name: /Import repositories from folder/i
+    })
+    await expect(importDialog.getByText('nested-api', { exact: true }).first()).toBeVisible({
+      timeout: 30_000
+    })
+    await expect(importDialog.getByText('nested-web', { exact: true }).first()).toBeVisible()
+    await importDialog.getByRole('button', { name: 'Yes, import as group', exact: true }).click()
+    await expect(importDialog).toBeHidden({ timeout: 30_000 })
+    measurements.nestedImportMs = Date.now() - startedAt
+
+    const remoteBrowse = await client.page.evaluate(
+      async ({ environmentId, rootPath }) => {
+        const response = await window.api.runtimeEnvironments.call({
+          selector: environmentId,
+          method: 'files.browseServerDir',
+          params: { path: rootPath },
+          timeoutMs: 15_000
+        })
+        if (!response.ok) {
+          throw new Error(response.error.message)
+        }
+        return response.result as { entries: { name: string; isDirectory: boolean }[] }
+      },
+      { environmentId: client.environmentId, rootPath: fixture.rootPath }
+    )
+    expect(remoteBrowse.entries).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ name: path.basename(fixture.gitPath), isDirectory: true }),
+        expect.objectContaining({ name: path.basename(fixture.folderPath), isDirectory: true }),
+        expect.objectContaining({
+          name: path.basename(fixture.nestedParentPath),
+          isDirectory: true
+        })
+      ])
+    )
+
+    await expect
+      .poll(async () => {
+        const inventory = await listRuntimeInventory(serverRuntime)
+        return {
+          groupParentPaths: inventory.projectGroups.map((group) => group.parentPath),
+          repoPaths: inventory.repos.map((repo) => repo.path)
+        }
+      })
+      .toEqual({
+        groupParentPaths: expect.arrayContaining([fixture.nestedParentPath]),
+        repoPaths: expect.arrayContaining([
+          fixture.gitPath,
+          fixture.folderPath,
+          fixture.clonedRepoPath,
+          fixture.createdRepoPath,
+          ...fixture.nestedRepoPaths
+        ])
+      })
+
+    const runtimeCatalog = await listRuntimeInventory(serverRuntime)
+    const runtimeGroup = runtimeCatalog.projectGroups.find(
+      (group) => group.parentPath === fixture.nestedParentPath
+    )
+    if (!runtimeGroup) {
+      throw new Error('Runtime project group unavailable for folder catalog boundary')
+    }
+    await serverRuntime.call('folderWorkspace.create', {
+      folderPath: fixture.catalogFolderPath,
+      name: 'Runtime catalog workspace',
+      projectGroupId: runtimeGroup.id
+    })
+    expect(
+      (await listRuntimeInventory(serverRuntime)).folderWorkspaces.map(
+        (workspace) => workspace.folderPath
+      )
+    ).toContain(fixture.catalogFolderPath)
+
+    const sameIdCatalog = await client.page.evaluate(
+      async ({
+        catalogFolderPath,
+        localGroupPath,
+        localWorkspacePath,
+        nestedParentPath,
+        runtimeEnvironmentId
+      }) => {
+        const store = window.__store
+        if (!store) {
+          throw new Error('Renderer store unavailable')
+        }
+        await store.getState().fetchProjectGroups({ runtimeEnvironmentId })
+        await store.getState().fetchFolderWorkspaces({ runtimeEnvironmentId })
+        const state = store.getState()
+        const runtimeGroup = state.projectGroups.find(
+          (group) =>
+            group.parentPath === nestedParentPath &&
+            group.executionHostId === `runtime:${runtimeEnvironmentId}`
+        )
+        const runtimeFolder = state.folderWorkspaces.find(
+          (workspace) =>
+            workspace.folderPath === catalogFolderPath &&
+            workspace.executionHostId === `runtime:${runtimeEnvironmentId}`
+        )
+        if (!runtimeGroup || !runtimeFolder) {
+          throw new Error('Runtime catalog unavailable for same-ID collision')
+        }
+        const localGroup = {
+          ...runtimeGroup,
+          name: 'Local same-ID group',
+          parentPath: localGroupPath,
+          executionHostId: 'local' as const
+        }
+        const localFolder = {
+          ...runtimeFolder,
+          name: 'Local same-ID folder',
+          folderPath: localWorkspacePath,
+          executionHostId: 'local' as const
+        }
+        store.setState({
+          projectGroups: [localGroup, ...state.projectGroups],
+          folderWorkspaces: [localFolder, ...state.folderWorkspaces]
+        })
+        await store.getState().fetchProjectGroups({ runtimeEnvironmentId })
+        await store.getState().fetchFolderWorkspaces({ runtimeEnvironmentId })
+        const collided = store.getState()
+        const result = {
+          folders: collided.folderWorkspaces
+            .filter((workspace) => workspace.id === runtimeFolder.id)
+            .map((workspace) => ({
+              executionHostId: workspace.executionHostId,
+              folderPath: workspace.folderPath
+            })),
+          groups: collided.projectGroups
+            .filter((group) => group.id === runtimeGroup.id)
+            .map((group) => ({
+              executionHostId: group.executionHostId,
+              parentPath: group.parentPath
+            }))
+        }
+        return result
+      },
+      {
+        catalogFolderPath: fixture.catalogFolderPath,
+        localGroupPath: fixture.localCloneCollisionPath,
+        localWorkspacePath: fixture.localCreateCollisionPath,
+        nestedParentPath: fixture.nestedParentPath,
+        runtimeEnvironmentId: client.environmentId
+      }
+    )
+    expect(sameIdCatalog).toEqual({
+      folders: expect.arrayContaining([
+        {
+          executionHostId: 'local',
+          folderPath: fixture.localCreateCollisionPath
+        },
+        {
+          executionHostId: `runtime:${client.environmentId}`,
+          folderPath: fixture.catalogFolderPath
+        }
+      ]),
+      groups: expect.arrayContaining([
+        {
+          executionHostId: 'local',
+          parentPath: fixture.localCloneCollisionPath
+        },
+        {
+          executionHostId: `runtime:${client.environmentId}`,
+          parentPath: fixture.nestedParentPath
+        }
+      ])
+    })
+
+    const reversedFolderActivation = await client.page.evaluate(
+      ({ catalogFolderPath, runtimeEnvironmentId }) => {
+        const store = window.__store
+        if (!store) {
+          throw new Error('Renderer store unavailable')
+        }
+        const hostId = `runtime:${runtimeEnvironmentId}` as const
+        const state = store.getState()
+        const runtimeFolder = state.folderWorkspaces.find(
+          (workspace) =>
+            workspace.folderPath === catalogFolderPath && workspace.executionHostId === hostId
+        )
+        if (!runtimeFolder) {
+          throw new Error('Runtime folder unavailable for reversed activation')
+        }
+        const sameFolders = state.folderWorkspaces
+          .filter((workspace) => workspace.id === runtimeFolder.id)
+          .toReversed()
+        const sameGroups = state.projectGroups
+          .filter((group) => group.id === runtimeFolder.projectGroupId)
+          .toReversed()
+        store.setState({
+          folderWorkspaces: [
+            ...state.folderWorkspaces.filter((workspace) => workspace.id !== runtimeFolder.id),
+            ...sameFolders
+          ],
+          projectGroups: [
+            ...state.projectGroups.filter((group) => group.id !== runtimeFolder.projectGroupId),
+            ...sameGroups
+          ]
+        })
+        store.getState().setActiveFolderWorkspace(runtimeFolder.id, hostId)
+        const activated = store.getState()
+        return {
+          activeHostId: activated.activeWorkspaceExecutionHostId,
+          activePath: activated.getKnownWorktreeById(`folder:${runtimeFolder.id}`, hostId)?.path,
+          sameIdHosts: activated.folderWorkspaces
+            .filter((workspace) => workspace.id === runtimeFolder.id)
+            .map((workspace) => workspace.executionHostId)
+            .sort()
+        }
+      },
+      {
+        catalogFolderPath: fixture.catalogFolderPath,
+        runtimeEnvironmentId: client.environmentId
+      }
+    )
+    expect(reversedFolderActivation).toEqual({
+      activeHostId: `runtime:${client.environmentId}`,
+      activePath: fixture.catalogFolderPath,
+      sameIdHosts: ['local', `runtime:${client.environmentId}`]
+    })
+
+    const collisionReconnect = await client.page.evaluate(
+      async ({ catalogFolderPath, environmentId }) => {
+        const store = window.__store
+        if (!store) {
+          throw new Error('Renderer store unavailable')
+        }
+        const runtimeFolder = store
+          .getState()
+          .folderWorkspaces.find((workspace) => workspace.folderPath === catalogFolderPath)
+        if (!runtimeFolder) {
+          throw new Error('Runtime folder unavailable before collision reconnect')
+        }
+        const staleRequests = [
+          store.getState().fetchProjectGroups({ runtimeEnvironmentId: environmentId }),
+          store.getState().fetchFolderWorkspaces({ runtimeEnvironmentId: environmentId })
+        ]
+        await window.api.runtimeEnvironments.disconnect({ selector: environmentId })
+        store.getState().setRuntimeEnvironmentStatus(environmentId, {
+          status: null,
+          checkedAt: Date.now()
+        })
+        const response = await window.api.runtimeEnvironments.connect({
+          selector: environmentId,
+          timeoutMs: 15_000
+        })
+        if (!response.ok) {
+          throw new Error(response.error.message)
+        }
+        store.getState().setRuntimeEnvironmentStatus(environmentId, {
+          status: response.result,
+          checkedAt: Date.now()
+        })
+        await store.getState().fetchProjectGroups({ runtimeEnvironmentId: environmentId })
+        await store.getState().fetchFolderWorkspaces({ runtimeEnvironmentId: environmentId })
+        await Promise.allSettled(staleRequests)
+        if (!(await store.getState().refreshRuntimeEnvironmentStatus(environmentId))) {
+          throw new Error('Paired runtime did not recover after collision reconnect')
+        }
+        store.getState().setActiveFolderWorkspace(runtimeFolder.id, `runtime:${environmentId}`)
+        const state = store.getState()
+        return {
+          activeHostId: state.activeWorkspaceExecutionHostId,
+          folderHosts: state.folderWorkspaces
+            .filter((workspace) => workspace.id === runtimeFolder.id)
+            .map((workspace) => workspace.executionHostId)
+            .sort(),
+          groupHosts: state.projectGroups
+            .filter((group) => group.id === runtimeFolder.projectGroupId)
+            .map((group) => group.executionHostId)
+            .sort()
+        }
+      },
+      {
+        catalogFolderPath: fixture.catalogFolderPath,
+        environmentId: client.environmentId
+      }
+    )
+    expect(collisionReconnect).toEqual({
+      activeHostId: `runtime:${client.environmentId}`,
+      folderHosts: ['local', `runtime:${client.environmentId}`],
+      groupHosts: ['local', `runtime:${client.environmentId}`]
+    })
+
+    const catalogAfterLocalRefresh = await client.page.evaluate(async () => {
+      const store = window.__store
+      if (!store) {
+        throw new Error('Renderer store unavailable')
+      }
+      await store.getState().fetchProjectGroups()
+      await store.getState().fetchFolderWorkspaces()
+      return {
+        folderWorkspaces: store.getState().folderWorkspaces,
+        projectGroups: store.getState().projectGroups
+      }
+    })
+    expect(catalogAfterLocalRefresh.projectGroups).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          executionHostId: `runtime:${client.environmentId}`,
+          parentPath: fixture.nestedParentPath
+        })
+      ])
+    )
+    expect(catalogAfterLocalRefresh.folderWorkspaces).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          executionHostId: `runtime:${client.environmentId}`,
+          folderPath: fixture.catalogFolderPath
+        })
+      ])
+    )
+
+    const clientRegistration = await client.page.evaluate(
+      ({
+        clonedRepoPath,
+        createdRepoPath,
+        environmentId,
+        folderCollisionId,
+        folderPath,
+        gitCollisionId,
+        gitPath,
+        nestedParentPath,
+        nestedRepoPaths
+      }) => {
+        const state = window.__store?.getState()
+        const nestedGroup = state?.projectGroups.find(
+          (group) => group.parentPath === nestedParentPath
+        )
+        const nestedRepos = state?.repos.filter((repo) => nestedRepoPaths.includes(repo.path)) ?? []
+        return {
+          clonedOwner:
+            state?.repos.find((repo) => repo.path === clonedRepoPath)?.executionHostId ?? null,
+          createdOwner:
+            state?.repos.find((repo) => repo.path === createdRepoPath)?.executionHostId ?? null,
+          folderKind: state?.repos.find((repo) => repo.path === folderPath)?.kind ?? null,
+          folderSameIdHosts:
+            Object.values(state?.worktreesByRepo ?? {})
+              .flat()
+              .filter((worktree) => worktree.id === folderCollisionId)
+              .map((worktree) => worktree.hostId ?? 'local')
+              .sort() ?? [],
+          folderOwner:
+            state?.repos.find((repo) => repo.path === folderPath)?.executionHostId ?? null,
+          gitSameIdHosts:
+            Object.values(state?.worktreesByRepo ?? {})
+              .flat()
+              .filter((worktree) => worktree.id === gitCollisionId)
+              .map((worktree) => worktree.hostId ?? 'local')
+              .sort() ?? [],
+          gitOwner: state?.repos.find((repo) => repo.path === gitPath)?.executionHostId ?? null,
+          nestedGroupOwner: nestedGroup?.executionHostId ?? null,
+          nestedRepoOwners: nestedRepos.map((repo) => repo.executionHostId ?? null).sort(),
+          nestedReposInGroup:
+            nestedGroup !== undefined &&
+            nestedRepos.length === nestedRepoPaths.length &&
+            nestedRepos.every((repo) => repo.projectGroupId === nestedGroup.id),
+          activeRuntimeEnvironmentId: state?.settings?.activeRuntimeEnvironmentId ?? null,
+          expectedOwner: `runtime:${environmentId}`
+        }
+      },
+      {
+        clonedRepoPath: fixture.clonedRepoPath,
+        createdRepoPath: fixture.createdRepoPath,
+        environmentId: client.environmentId,
+        folderCollisionId: folderCollision.runtimeWorktreeId,
+        folderPath: fixture.folderPath,
+        gitCollisionId: gitCollision.runtimeWorktreeId,
+        gitPath: fixture.gitPath,
+        nestedParentPath: fixture.nestedParentPath,
+        nestedRepoPaths: fixture.nestedRepoPaths
+      }
+    )
+    expect(clientRegistration).toEqual({
+      activeRuntimeEnvironmentId: null,
+      clonedOwner: `runtime:${client.environmentId}`,
+      createdOwner: `runtime:${client.environmentId}`,
+      expectedOwner: `runtime:${client.environmentId}`,
+      folderKind: 'folder',
+      folderOwner: `runtime:${client.environmentId}`,
+      folderSameIdHosts: ['local', `runtime:${client.environmentId}`],
+      gitOwner: `runtime:${client.environmentId}`,
+      gitSameIdHosts: ['local', `runtime:${client.environmentId}`],
+      nestedGroupOwner: `runtime:${client.environmentId}`,
+      nestedRepoOwners: [`runtime:${client.environmentId}`, `runtime:${client.environmentId}`],
+      nestedReposInGroup: true
+    })
+
+    const terminalActivation = await client.page.evaluate(
+      async ({ environmentId, worktreeId }) => {
+        const bridge = (
+          window as unknown as {
+            __webRuntimeSessionE2E?: {
+              createTerminal: (
+                args: Record<string, unknown>
+              ) => Promise<{ status: string; message?: string }>
+            }
+          }
+        ).__webRuntimeSessionE2E
+        const store = window.__store
+        if (!bridge || !store) {
+          throw new Error('Runtime terminal activation bridge unavailable')
+        }
+        const outcome = await bridge.createTerminal({ environmentId, worktreeId })
+        const state = store.getState()
+        return {
+          activeHostId: state.activeWorkspaceExecutionHostId,
+          activeWorktreeId: state.activeWorktreeId,
+          outcome,
+          sameIdHosts: Object.values(state.worktreesByRepo)
+            .flat()
+            .filter((worktree) => worktree.id === worktreeId)
+            .map((worktree) => worktree.hostId ?? 'local')
+            .sort()
+        }
+      },
+      {
+        environmentId: client.environmentId,
+        worktreeId: gitCollision.runtimeWorktreeId
+      }
+    )
+    expect(terminalActivation).toEqual({
+      activeHostId: `runtime:${client.environmentId}`,
+      activeWorktreeId: gitCollision.runtimeWorktreeId,
+      outcome: { status: 'created' },
+      sameIdHosts: ['local', `runtime:${client.environmentId}`]
+    })
+
+    const finalClientInventory = await listRuntimeInventory(clientLocalRuntime)
+    expect(finalClientInventory.repos.map((repo) => repo.path)).toEqual(
+      expect.not.arrayContaining([
+        fixture.gitPath,
+        fixture.folderPath,
+        fixture.clonedRepoPath,
+        fixture.createdRepoPath
+      ])
+    )
+    expect(finalClientInventory.repos.map((repo) => repo.path)).toEqual(
+      expect.not.arrayContaining(fixture.nestedRepoPaths)
+    )
+    expect(finalClientInventory.projectGroups.map((group) => group.parentPath)).not.toContain(
+      fixture.nestedParentPath
+    )
+    expect(
+      finalClientInventory.folderWorkspaces.map((workspace) => workspace.folderPath)
+    ).not.toContain(fixture.catalogFolderPath)
+    for (const projectName of [
+      path.basename(fixture.gitPath),
+      path.basename(fixture.folderPath),
+      path.basename(fixture.clonedRepoPath),
+      path.basename(fixture.createdRepoPath),
+      ...fixture.nestedRepoPaths.map((repoPath) => path.basename(repoPath))
+    ]) {
+      // Why: duplicate checkout names are disambiguated with a parent path.
+      await expect(client.page.getByText(projectName, { exact: false }).first()).toBeVisible()
+    }
+    expect(await client.getDirectSshAttemptTargetIds()).toEqual([])
+    console.info(`[pr11346-routing] ${JSON.stringify({ topology: runtimeName, ...measurements })}`)
+    await client.page.screenshot({
+      path: testInfo.outputPath(`${visible ? 'headed' : 'hidden-window'}-selected-runtime-add.png`),
+      fullPage: true
+    })
+  } finally {
+    await client.dispose()
+    rmSync(fixture.rootPath, { recursive: true, force: true })
+  }
+}
+
+test('routes every Add Project path to a selected non-default headed runtime @headful', async ({
+  electronApp,
+  orcaPage
+}, testInfo) => {
+  test.setTimeout(300_000)
+  await runSelectedRuntimeAddJourney(electronApp, orcaPage, testInfo, true)
+})
+
+test('keeps every selected-runtime Add Project path in hidden-window desktop parity', async ({
+  electronApp,
+  orcaPage
+}, testInfo) => {
+  test.setTimeout(300_000)
+  await runSelectedRuntimeAddJourney(electronApp, orcaPage, testInfo, false)
+})
diff --git a/tests/e2e/pr11346-selected-runtime-identity-oracle.ts b/tests/e2e/pr11346-selected-runtime-identity-oracle.ts
new file mode 100644
index 00000000000..2918a6928df
--- /dev/null
+++ b/tests/e2e/pr11346-selected-runtime-identity-oracle.ts
@@ -0,0 +1,247 @@
+import { execFileSync } from 'node:child_process'
+import { mkdirSync, realpathSync, writeFileSync } from 'node:fs'
+import { mkdtemp } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import type { Page } from '@stablyai/playwright-test'
+import type { AppState } from '../../src/renderer/src/store/types'
+import { expect } from './helpers/orca-app'
+
+export function configureIsolatedGitIdentity(homePath: string): void {
+  writeFileSync(
+    path.join(homePath, '.gitconfig'),
+    '[user]\n\tname = PR 11346 E2E\n\temail = pr11346@test.local\n'
+  )
+}
+
+function initializeGitRepo(repoPath: string, markerName: string): void {
+  mkdirSync(repoPath, { recursive: true })
+  execFileSync('git', ['init'], { cwd: repoPath, stdio: 'pipe' })
+  execFileSync('git', ['config', 'user.email', 'pr11346@test.local'], {
+    cwd: repoPath,
+    stdio: 'pipe'
+  })
+  execFileSync('git', ['config', 'user.name', 'PR 11346 E2E'], {
+    cwd: repoPath,
+    stdio: 'pipe'
+  })
+  writeFileSync(path.join(repoPath, markerName), `# ${path.basename(repoPath)} authority\n`)
+  execFileSync('git', ['add', markerName], { cwd: repoPath, stdio: 'pipe' })
+  execFileSync('git', ['commit', '-m', 'Initial remote fixture'], {
+    cwd: repoPath,
+    stdio: 'pipe'
+  })
+}
+
+export async function createProjectFixtures(): Promise<{
+  catalogFolderPath: string
+  cloneParentPath: string
+  clonedRepoPath: string
+  createdRepoPath: string
+  createParentPath: string
+  folderPath: string
+  gitPath: string
+  localCloneCollisionPath: string
+  localCreateCollisionPath: string
+  nestedParentPath: string
+  nestedRepoPaths: string[]
+  reconnectCatalogPath: string
+  rootPath: string
+}> {
+  const rootPath = realpathSync(await mkdtemp(path.join(os.tmpdir(), 'orca-pr11346-headed-')))
+  const gitPath = path.join(rootPath, 'remote-git-project')
+  const folderPath = path.join(rootPath, 'remote-plain-folder')
+  const cloneParentPath = path.join(rootPath, 'remote-clones')
+  const createParentPath = path.join(rootPath, 'remote-created-projects')
+  const nestedParentPath = path.join(rootPath, 'remote-nested-projects')
+  const catalogFolderPath = path.join(nestedParentPath, 'catalog-workspace')
+  const reconnectCatalogPath = path.join(rootPath, 'reconnect-catalog')
+  const localCloneCollisionPath = path.join(rootPath, 'local-clone-collision')
+  const localCreateCollisionPath = path.join(rootPath, 'local-create-collision')
+  const nestedRepoPaths = ['nested-api', 'nested-web'].map((name) =>
+    path.join(nestedParentPath, name)
+  )
+  mkdirSync(folderPath)
+  mkdirSync(cloneParentPath)
+  mkdirSync(createParentPath)
+  writeFileSync(path.join(folderPath, 'REMOTE_FOLDER_MARKER.txt'), 'remote-folder-authority\n')
+  initializeGitRepo(gitPath, 'REMOTE_GIT_MARKER.md')
+  initializeGitRepo(localCloneCollisionPath, 'LOCAL_CLONE_COLLISION.md')
+  initializeGitRepo(localCreateCollisionPath, 'LOCAL_CREATE_COLLISION.md')
+  nestedRepoPaths.forEach((repoPath) => initializeGitRepo(repoPath, 'NESTED_REMOTE_MARKER.md'))
+  mkdirSync(catalogFolderPath)
+  mkdirSync(reconnectCatalogPath)
+  return {
+    catalogFolderPath,
+    cloneParentPath,
+    clonedRepoPath: path.join(cloneParentPath, path.basename(gitPath)),
+    createParentPath,
+    createdRepoPath: path.join(createParentPath, 'runtime-created-project'),
+    folderPath,
+    gitPath,
+    localCloneCollisionPath,
+    localCreateCollisionPath,
+    nestedParentPath,
+    nestedRepoPaths,
+    reconnectCatalogPath,
+    rootPath
+  }
+}
+
+type ActivationCollision = {
+  localWorktreeId: string
+  runtimeWorktreeId: string
+}
+
+export async function installFinalActivationGate(page: Page, targetPath: string): Promise<void> {
+  await page.evaluate((pathToGate) => {
+    const store = window.__store
+    if (!store) {
+      throw new Error('Renderer store unavailable')
+    }
+    const originalFetchWorktrees = store.getState().fetchWorktrees
+    let release!: () => void
+    const released = new Promise<void>((resolve) => {
+      release = resolve
+    })
+    const gateWindow = window as typeof window & {
+      __pr11346ActivationGate?: {
+        originalFetchWorktrees: typeof originalFetchWorktrees
+        release: () => void
+        waiting: boolean
+      }
+    }
+    gateWindow.__pr11346ActivationGate = {
+      originalFetchWorktrees,
+      release,
+      waiting: false
+    }
+    store.setState({
+      fetchWorktrees: async (...args: Parameters<typeof originalFetchWorktrees>) => {
+        const result = await originalFetchWorktrees(...args)
+        const targetRepo = store
+          .getState()
+          .repos.find(
+            (repo) =>
+              repo.path === pathToGate && repo.executionHostId?.startsWith('runtime:') === true
+          )
+        if (targetRepo?.id === args[0]) {
+          gateWindow.__pr11346ActivationGate!.waiting = true
+          await released
+        }
+        return result
+      }
+    })
+  }, targetPath)
+}
+
+export async function injectSameIdLocalActivationCollision(
+  page: Page,
+  targetPath: string,
+  localPath: string
+): Promise<ActivationCollision> {
+  await expect
+    .poll(
+      () =>
+        page.evaluate(
+          () =>
+            (
+              window as typeof window & {
+                __pr11346ActivationGate?: { waiting: boolean }
+              }
+            ).__pr11346ActivationGate?.waiting ?? false
+        ),
+      { timeout: 60_000 }
+    )
+    .toBe(true)
+
+  return page.evaluate(
+    ({ localCollisionPath, runtimePath }) => {
+      const store = window.__store
+      const gateWindow = window as typeof window & {
+        __pr11346ActivationGate?: {
+          originalFetchWorktrees: AppState['fetchWorktrees']
+          release: () => void
+        }
+      }
+      const gate = gateWindow.__pr11346ActivationGate
+      if (!store || !gate) {
+        throw new Error('Activation gate unavailable')
+      }
+      const state = store.getState()
+      const runtimeRepo = state.repos.find(
+        (repo) => repo.path === runtimePath && repo.executionHostId?.startsWith('runtime:') === true
+      )
+      if (!runtimeRepo) {
+        throw new Error(`Runtime repo unavailable for ${runtimePath}`)
+      }
+      const runtimeWorktree = state.worktreesByRepo[runtimeRepo.id]?.find(
+        (worktree) =>
+          worktree.hostId === runtimeRepo.executionHostId &&
+          (worktree.isMainWorktree || worktree.path === runtimePath)
+      )
+      if (!runtimeWorktree) {
+        throw new Error(`Runtime default checkout unavailable for ${runtimePath}`)
+      }
+      const localWorktree = {
+        ...runtimeWorktree,
+        path: localCollisionPath,
+        hostId: 'local' as const,
+        runtimeOwnerEnvironmentId: null
+      }
+      store.setState({
+        repos: [
+          {
+            ...runtimeRepo,
+            path: localCollisionPath,
+            displayName: `Local collision for ${runtimeRepo.displayName}`,
+            executionHostId: 'local',
+            connectionId: null
+          },
+          ...state.repos
+        ],
+        worktreesByRepo: {
+          ...state.worktreesByRepo,
+          [runtimeRepo.id]: [localWorktree, ...(state.worktreesByRepo[runtimeRepo.id] ?? [])]
+        },
+        fetchWorktrees: gate.originalFetchWorktrees
+      })
+      gate.release()
+      delete gateWindow.__pr11346ActivationGate
+      return {
+        localWorktreeId: localWorktree.id,
+        runtimeWorktreeId: runtimeWorktree.id
+      }
+    },
+    { localCollisionPath: localPath, runtimePath: targetPath }
+  )
+}
+
+export async function expectRuntimeActivation(
+  page: Page,
+  collision: ActivationCollision
+): Promise<void> {
+  await expect
+    .poll(
+      () =>
+        page.evaluate(() => {
+          const state = window.__store?.getState()
+          return {
+            activeWorktreeId: state?.activeWorktreeId ?? null,
+            activeWorktreeHost: state?.activeWorkspaceExecutionHostId ?? null,
+            sameIdHosts: Object.values(state?.worktreesByRepo ?? {})
+              .flat()
+              .filter((worktree) => worktree.id === state?.activeWorktreeId)
+              .map((worktree) => worktree.hostId ?? 'local')
+              .sort()
+          }
+        }),
+      { timeout: 60_000 }
+    )
+    .toEqual({
+      activeWorktreeHost: expect.stringMatching(/^runtime:/),
+      activeWorktreeId: collision.runtimeWorktreeId,
+      sameIdHosts: ['local', expect.stringMatching(/^runtime:/)]
+    })
+  expect(collision.runtimeWorktreeId).toBe(collision.localWorktreeId)
+}

From bc6a6e9ff0e47683fc90a6840e86b08936f37335 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Fri, 31 Jul 2026 04:56:14 -0700
Subject: [PATCH 16/23] [P2] fix(daemon): keep audit-only evidence off the main
 thread and out of false negatives (#11695)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(daemon): keep audit-only evidence off the main thread and out of false negatives

Three audit-only daemon evidence defects:

- The Windows CIM probe emitted the "absent" marker whenever $p was empty, so a
  non-terminating Get-CimInstance failure (Winmgmt down, corrupt WMI repository,
  access denied) exited 0 with {"exists":false} and was recorded as proof the
  daemon process was gone. The script now sets $ErrorActionPreference and reports
  query failure explicitly; only a query that ran and found nothing yields
  'missing', everything else stays 'unavailable'.
- probeMacosProcess read the process start time through execFileSync('ps') on the
  Electron main thread. It now uses the async readMacosProcessStartedAtMs, matching
  the async command-line sibling in the same probe.
- daemon_audit_eligibility fired on every successful inventory, so routine
  listProcesses traffic could drain the shared 1,000-event per-session telemetry
  ceiling. Repeated identical observations now collapse to one heartbeat per
  5 minutes; a changed observation still emits immediately.

The evidence stays strictly audit-only — no lifecycle, routing or recovery path
consumes the observation.

Co-authored-by: Orca <help@stably.ai>

* fix(daemon): take the linux audit start-time read off the main thread

The linux branch of the audit-only evidence probe still bottomed out in
getProcessStartedAtMs, i.e. two readFileSync calls plus an
execFileSync('getconf', ['CLK_TCK']) spawn on the Electron main thread —
the same hazard the darwin half of this change removed. The `async`
wrapper hid it from the type signature and from the main-thread
regression test, which only covered darwin.

That path is reached whenever the pid record carries no start ticks or
boot id: legacy bare-integer pid files (the upgrade population this audit
exists to observe) and any host where /proc boot-id or start-tick reads
fail.

readLinuxProcessStartedAtMs now reads procfs asynchronously and caches
CLK_TCK for the process lifetime (it is fixed for the kernel's lifetime),
retrying only after a failed probe. The main-thread test now covers linux
with a ticks-less pid record.

Co-authored-by: Orca <help@stably.ai>

* fix(daemon): measure the audit heartbeat window on a monotonic clock

A backward wall-clock jump (NTP correction, VM resume) made elapsed time negative, which read as "still inside the window" and suppressed daemon_audit_eligibility heartbeats until wall time caught up. Rate-limit arithmetic now runs on performance.now() and treats any backward movement as eligible.

Co-authored-by: Orca <help@stably.ai>

* fix(daemon): guard the audit rate limiter and scope the CLK_TCK cache

The rate-limited tracker is the only production emitter, but its payload
serialization and clock read sat outside the guard that keeps audit
telemetry from affecting daemon availability — a throw there propagates
out of listProcesses' try and turns a successful inventory into a
reported inventory failure.

Also key the CLK_TCK cache by the runner that produced it: the value
belongs to the host executing getconf, not the module.

Co-authored-by: Orca <help@stably.ai>

* test(daemon): make audit CI synchronization deterministic

---------

Co-authored-by: Orca <help@stably.ai>
---
 .../daemon-audit-eligibility-event.test.ts    | 145 +++++++++++++++++-
 .../daemon/daemon-audit-eligibility-event.ts  |  74 +++++++--
 ...n-incarnation-evidence-main-thread.test.ts |  94 ++++++++++++
 .../daemon-incarnation-evidence-types.ts      |   2 +-
 .../daemon-incarnation-evidence.test.ts       |  19 ++-
 .../daemon/daemon-incarnation-evidence.ts     |  15 +-
 .../daemon/daemon-process-inspection.test.ts  |  93 ++++++++++-
 src/main/daemon/daemon-process-inspection.ts  |  92 ++++++++++-
 src/main/daemon/daemon-pty-adapter.ts         |   6 +-
 ...ty-portal-readiness-loop.react185.test.tsx |  29 ++--
 10 files changed, 513 insertions(+), 56 deletions(-)
 create mode 100644 src/main/daemon/daemon-incarnation-evidence-main-thread.test.ts

diff --git a/src/main/daemon/daemon-audit-eligibility-event.test.ts b/src/main/daemon/daemon-audit-eligibility-event.test.ts
index b17b5ba3892..52171e14853 100644
--- a/src/main/daemon/daemon-audit-eligibility-event.test.ts
+++ b/src/main/daemon/daemon-audit-eligibility-event.test.ts
@@ -1,11 +1,20 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { validate } from '../telemetry/validator'
 import { recordAuthenticatedInventory, type DaemonAuditContext } from './daemon-audit-classifier'
+import { DaemonPtyAdapter } from './daemon-pty-adapter'
+import { DaemonServer } from './daemon-server'
+import { getDaemonSocketPath } from './daemon-spawner'
 
 const { trackMock } = vi.hoisted(() => ({ trackMock: vi.fn() }))
 vi.mock('../telemetry/client', () => ({ track: trackMock }))
 
-import { trackDaemonAuditEligibility } from './daemon-audit-eligibility-event'
+import {
+  createDaemonAuditEligibilityTracker,
+  trackDaemonAuditEligibility
+} from './daemon-audit-eligibility-event'
 
 const context: DaemonAuditContext = {
   protocolGeneration: 23,
@@ -47,5 +56,137 @@ describe('daemon audit eligibility telemetry', () => {
     expect(() =>
       trackDaemonAuditEligibility(recordAuthenticatedInventory(context, null))
     ).not.toThrow()
+
+    // The rate-limited tracker is the production call site, so it carries the same guarantee.
+    const trackEligibility = createDaemonAuditEligibilityTracker()
+    expect(() => trackEligibility(recordAuthenticatedInventory(context, null))).not.toThrow()
+  })
+
+  it('cannot affect callers when the rate-limit bookkeeping throws', () => {
+    const trackEligibility = createDaemonAuditEligibilityTracker(() => {
+      throw new Error('no clock')
+    })
+
+    expect(() => trackEligibility(recordAuthenticatedInventory(context, null))).not.toThrow()
+
+    // A malformed observation must not escape the guard either.
+    const malformed = recordAuthenticatedInventory(context, null)
+    expect(() =>
+      trackEligibility({ ...malformed, evidenceSources: undefined as never })
+    ).not.toThrow()
+    expect(trackMock).not.toHaveBeenCalled()
+  })
+
+  it('collapses repeated identical observations into one heartbeat per window', () => {
+    let nowMs = 1_700_000_000_000
+    const trackEligibility = createDaemonAuditEligibilityTracker(() => nowMs)
+
+    for (let index = 0; index < 60; index += 1) {
+      nowMs += 1_000
+      trackEligibility(recordAuthenticatedInventory(context, null))
+    }
+
+    expect(trackMock).toHaveBeenCalledOnce()
+
+    nowMs += 5 * 60_000
+    trackEligibility(recordAuthenticatedInventory(context, null))
+    expect(trackMock).toHaveBeenCalledTimes(2)
+  })
+
+  it('keeps heartbeating after the clock jumps backward', () => {
+    let nowMs = 1_700_000_000_000
+    const trackEligibility = createDaemonAuditEligibilityTracker(() => nowMs)
+
+    trackEligibility(recordAuthenticatedInventory(context, null))
+    expect(trackMock).toHaveBeenCalledOnce()
+
+    // An NTP correction / VM resume rewinds the clock by an hour.
+    nowMs -= 60 * 60_000
+    trackEligibility(recordAuthenticatedInventory(context, null))
+    expect(trackMock).toHaveBeenCalledTimes(2)
+
+    // The window re-anchors on the rewound clock instead of emitting on every call.
+    for (let index = 0; index < 60; index += 1) {
+      nowMs += 1_000
+      trackEligibility(recordAuthenticatedInventory(context, null))
+    }
+    expect(trackMock).toHaveBeenCalledTimes(2)
+
+    nowMs += 5 * 60_000
+    trackEligibility(recordAuthenticatedInventory(context, null))
+    expect(trackMock).toHaveBeenCalledTimes(3)
+  })
+
+  it('measures the window on a monotonic clock rather than wall time', () => {
+    const wallClock = vi.spyOn(Date, 'now').mockReturnValue(1_700_000_000_000)
+    const trackEligibility = createDaemonAuditEligibilityTracker()
+
+    try {
+      trackEligibility(recordAuthenticatedInventory(context, null))
+      expect(trackMock).toHaveBeenCalledOnce()
+
+      // Wall time alone must not open the window: no real time has elapsed.
+      wallClock.mockReturnValue(1_700_000_000_000 + 6 * 60_000)
+      trackEligibility(recordAuthenticatedInventory(context, null))
+      expect(trackMock).toHaveBeenCalledOnce()
+    } finally {
+      wallClock.mockRestore()
+    }
+  })
+
+  it('emits immediately when the observation changes', () => {
+    let nowMs = 1_700_000_000_000
+    const trackEligibility = createDaemonAuditEligibilityTracker(() => nowMs)
+
+    trackEligibility(recordAuthenticatedInventory(context, null))
+    nowMs += 1_000
+    trackEligibility(
+      recordAuthenticatedInventory(context, {
+        identity: { pid: 42, startedAtMs: nowMs, launchNonce: 'launch-a' }
+      })
+    )
+
+    expect(trackMock).toHaveBeenCalledTimes(2)
+    expect(trackMock.mock.calls[1][1]).toMatchObject({ exact_incarnation: 'endpoint-identity' })
+  })
+})
+
+describe('daemon audit eligibility inventory volume', () => {
+  let dir: string
+  let socketPath: string
+  let tokenPath: string
+  let server: DaemonServer
+  let adapter: DaemonPtyAdapter
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'daemon-audit-eligibility-'))
+    socketPath = getDaemonSocketPath(dir)
+    tokenPath = join(dir, 'daemon.token')
+  })
+
+  afterEach(async () => {
+    adapter?.dispose()
+    await server?.shutdown()
+    rmSync(dir, { recursive: true, force: true })
+  })
+
+  it('does not emit one eligibility event per successful inventory', async () => {
+    server = new DaemonServer({
+      socketPath,
+      tokenPath,
+      spawnSubprocess: () => {
+        throw new Error('Test must not create a PTY')
+      }
+    })
+    await server.start()
+    adapter = new DaemonPtyAdapter({ socketPath, tokenPath })
+
+    for (let index = 0; index < 40; index += 1) {
+      await adapter.listProcesses()
+    }
+
+    expect(
+      trackMock.mock.calls.filter(([name]) => name === 'daemon_audit_eligibility')
+    ).toHaveLength(1)
   })
 })
diff --git a/src/main/daemon/daemon-audit-eligibility-event.ts b/src/main/daemon/daemon-audit-eligibility-event.ts
index 0511f7a384a..3afaaa8aad5 100644
--- a/src/main/daemon/daemon-audit-eligibility-event.ts
+++ b/src/main/daemon/daemon-audit-eligibility-event.ts
@@ -1,29 +1,71 @@
 import { track } from '../telemetry/client'
+import type { EventProps } from '../../shared/telemetry-events'
 import type { DaemonAuditObservation } from './daemon-audit-classifier'
 
+// Why: a steady daemon repeats a byte-identical observation on every listProcesses call, so
+// repeats are re-sent only as an occasional heartbeat — the shared per-session telemetry
+// ceiling is 1,000 events for the whole app and audit data must not crowd it out.
+const REPEATED_OBSERVATION_INTERVAL_MS = 5 * 60_000
+
 export function trackDaemonAuditEligibility(observation: DaemonAuditObservation): void {
   try {
-    track('daemon_audit_eligibility', {
-      state: observation.state,
-      reason: observation.reason,
-      trigger: observation.trigger,
-      evidence_sources: [...observation.evidenceSources],
-      protocol_generation: observation.context.protocolGeneration,
-      provider: observation.context.provider,
-      endpoint_kind: observation.context.endpointKind,
-      profile_scope: observation.context.profileScope ? 'configured' : 'unspecified',
-      exact_incarnation: exactIncarnationKind(observation),
-      reachability: observation.reachability,
-      inventory_authority: observation.inventoryAuthority,
-      process_liveness: observation.processLiveness,
-      process_reason: observation.processReason,
-      endpoint_state: observation.endpointState
-    })
+    track('daemon_audit_eligibility', auditEligibilityProperties(observation))
   } catch {
     // Audit telemetry cannot affect daemon availability.
   }
 }
 
+export function createDaemonAuditEligibilityTracker(
+  // Why: the window must be measured on a monotonic clock — a backward wall-clock jump (NTP
+  // correction, VM resume) would otherwise park the next heartbeat in the future.
+  monotonicNowMs: () => number = () => performance.now()
+): (observation: DaemonAuditObservation) => void {
+  let lastProperties: string | null = null
+  let lastTrackedAtMs = 0
+  return (observation) => {
+    // Why: the rate-limit bookkeeping runs inside the daemon's inventory path, so it is guarded
+    // together with the emit — audit telemetry cannot affect daemon availability.
+    try {
+      const properties = JSON.stringify(auditEligibilityProperties(observation))
+      const observedAtMs = monotonicNowMs()
+      const elapsedMs = observedAtMs - lastTrackedAtMs
+      if (
+        properties === lastProperties &&
+        elapsedMs >= 0 &&
+        elapsedMs < REPEATED_OBSERVATION_INTERVAL_MS
+      ) {
+        return
+      }
+      lastProperties = properties
+      lastTrackedAtMs = observedAtMs
+      trackDaemonAuditEligibility(observation)
+    } catch {
+      // Audit telemetry cannot affect daemon availability.
+    }
+  }
+}
+
+function auditEligibilityProperties(
+  observation: DaemonAuditObservation
+): EventProps<'daemon_audit_eligibility'> {
+  return {
+    state: observation.state,
+    reason: observation.reason,
+    trigger: observation.trigger,
+    evidence_sources: [...observation.evidenceSources],
+    protocol_generation: observation.context.protocolGeneration,
+    provider: observation.context.provider,
+    endpoint_kind: observation.context.endpointKind,
+    profile_scope: observation.context.profileScope ? 'configured' : 'unspecified',
+    exact_incarnation: exactIncarnationKind(observation),
+    reachability: observation.reachability,
+    inventory_authority: observation.inventoryAuthority,
+    process_liveness: observation.processLiveness,
+    process_reason: observation.processReason,
+    endpoint_state: observation.endpointState
+  }
+}
+
 function exactIncarnationKind(
   observation: DaemonAuditObservation
 ): 'endpoint-identity' | 'endpoint-identity-linux-ticks' | 'unavailable' {
diff --git a/src/main/daemon/daemon-incarnation-evidence-main-thread.test.ts b/src/main/daemon/daemon-incarnation-evidence-main-thread.test.ts
new file mode 100644
index 00000000000..7cc9d5833b3
--- /dev/null
+++ b/src/main/daemon/daemon-incarnation-evidence-main-thread.test.ts
@@ -0,0 +1,94 @@
+import type * as ChildProcessModule from 'node:child_process'
+import type * as FsPromisesModule from 'node:fs/promises'
+import { describe, expect, it, vi } from 'vitest'
+import type { ExactDaemonIncarnation } from './daemon-incarnation-evidence-types'
+
+const LINUX_BOOT_TIME_SECONDS = 1_699_000_000
+const LINUX_START_TICKS = 1_234
+const LINUX_CLOCK_TICKS_PER_SECOND = 100
+
+const { execFileMock, execFileSyncMock, readFileMock } = vi.hoisted(() => ({
+  execFileMock: vi.fn(
+    (
+      file: string,
+      _args: readonly string[],
+      _options: unknown,
+      callback: (error: Error | null, result: { stdout: string; stderr: string }) => void
+    ) => {
+      callback(null, {
+        stdout: file === 'getconf' ? '100\n' : `${new Date(1_700_000_000_000).toString()}\n`,
+        stderr: ''
+      })
+    }
+  ),
+  execFileSyncMock: vi.fn(() => ''),
+  readFileMock: vi.fn(async (path: string) =>
+    path === '/proc/stat' ? 'btime 1699000000\n' : `42 (orca-daemon) S${' 0'.repeat(18)} 1234 0 0\n`
+  )
+}))
+
+vi.mock('node:child_process', async (importOriginal) => ({
+  ...(await importOriginal<typeof ChildProcessModule>()),
+  execFile: execFileMock,
+  execFileSync: execFileSyncMock
+}))
+
+vi.mock('node:fs/promises', async (importOriginal) => ({
+  ...(await importOriginal<typeof FsPromisesModule>()),
+  readFile: readFileMock
+}))
+
+const { probeDaemonProcessIdentity } = await import('./daemon-incarnation-evidence')
+
+const endpoint = { socketPath: '/runtime/daemon.sock', tokenPath: '/runtime/daemon.token' }
+const exactIncarnation: ExactDaemonIncarnation = {
+  identity: { pid: 42, startedAtMs: 1_700_000_000_000, launchNonce: 'launch-a' }
+}
+const daemonCommandLine = `node daemon-entry --socket ${endpoint.socketPath} --token ${endpoint.tokenPath}`
+
+describe('daemon audit evidence main-thread cost', () => {
+  it('reads the macOS process start time without a synchronous main-thread spawn', async () => {
+    await expect(
+      probeDaemonProcessIdentity(exactIncarnation, endpoint, {
+        platform: 'darwin',
+        signalProcess: () => 'occupied',
+        readCommandLine: async () => daemonCommandLine
+      })
+    ).resolves.toMatchObject({ state: 'present', reason: 'macos_identity_match' })
+
+    expect(execFileSyncMock).not.toHaveBeenCalled()
+    expect(execFileMock).toHaveBeenCalledWith(
+      'ps',
+      ['-p', '42', '-o', 'lstart='],
+      expect.anything(),
+      expect.any(Function)
+    )
+  })
+
+  // Legacy bare-integer pid files carry no start ticks, so linux falls back to the start time.
+  it('reads the linux process start time without a synchronous main-thread spawn', async () => {
+    const startedAtMs =
+      LINUX_BOOT_TIME_SECONDS * 1000 + (LINUX_START_TICKS / LINUX_CLOCK_TICKS_PER_SECOND) * 1000
+
+    await expect(
+      probeDaemonProcessIdentity(
+        { identity: { pid: 42, startedAtMs, launchNonce: 'launch-a' } },
+        endpoint,
+        {
+          platform: 'linux',
+          signalProcess: () => 'occupied',
+          readLinuxStat: async () => ({ status: 'present', value: '42 (orca-daemon) S 1' }),
+          readCommandLine: async () => daemonCommandLine
+        }
+      )
+    ).resolves.toMatchObject({ state: 'present', reason: 'linux_identity_match' })
+
+    expect(execFileSyncMock).not.toHaveBeenCalled()
+    expect(execFileMock).toHaveBeenCalledWith(
+      'getconf',
+      ['CLK_TCK'],
+      expect.anything(),
+      expect.any(Function)
+    )
+  })
+})
diff --git a/src/main/daemon/daemon-incarnation-evidence-types.ts b/src/main/daemon/daemon-incarnation-evidence-types.ts
index 537a03fc191..48c61da177f 100644
--- a/src/main/daemon/daemon-incarnation-evidence-types.ts
+++ b/src/main/daemon/daemon-incarnation-evidence-types.ts
@@ -70,6 +70,6 @@ export type DaemonProcessProbeDependencies = {
   readLinuxStat?: (pid: number) => Promise<LinuxStatEvidence>
   readBootIdentity?: () => Promise<string | undefined>
   readCommandLine?: (pid: number, platform: NodeJS.Platform) => Promise<string | undefined>
-  readProcessStartedAtMs?: (pid: number) => number | null
+  readProcessStartedAtMs?: (pid: number) => Promise<number | null>
   queryWindowsProcess?: (pid: number) => Promise<WindowsProcessEvidence>
 }
diff --git a/src/main/daemon/daemon-incarnation-evidence.test.ts b/src/main/daemon/daemon-incarnation-evidence.test.ts
index 73e4a337e3c..1bd2f4dcfa4 100644
--- a/src/main/daemon/daemon-incarnation-evidence.test.ts
+++ b/src/main/daemon/daemon-incarnation-evidence.test.ts
@@ -61,7 +61,7 @@ describe('daemon process identity evidence', () => {
   })
 
   it('proves Linux pid reuse from native start ticks without derived milliseconds', async () => {
-    const readProcessStartedAtMs = vi.fn(() => exactIncarnation.identity.startedAtMs)
+    const readProcessStartedAtMs = vi.fn(async () => exactIncarnation.identity.startedAtMs)
 
     await expect(
       probeDaemonProcessIdentity(
@@ -247,7 +247,7 @@ describe('daemon process identity evidence', () => {
         signalProcess: () => 'occupied',
         readCommandLine: async () =>
           `node daemon-entry --socket ${endpoint.socketPath} --token ${endpoint.tokenPath}`,
-        readProcessStartedAtMs: () => exactIncarnation.identity.startedAtMs + 2_500
+        readProcessStartedAtMs: async () => exactIncarnation.identity.startedAtMs + 2_500
       })
     ).resolves.toMatchObject({ state: 'unknown', reason: 'macos_start_time_mismatch' })
   })
@@ -260,6 +260,21 @@ describe('daemon process identity evidence', () => {
       })
     ).resolves.toMatchObject({ state: 'gone', reason: 'pid_missing' })
   })
+
+  it('keeps unsupported platforms indeterminate without running a Darwin probe', async () => {
+    const signalProcess = vi.fn(() => 'occupied' as const)
+    const readCommandLine = vi.fn(async () => 'node daemon-entry')
+
+    await expect(
+      probeDaemonProcessIdentity(exactIncarnation, endpoint, {
+        platform: 'freebsd',
+        signalProcess,
+        readCommandLine
+      })
+    ).resolves.toMatchObject({ state: 'unknown', reason: 'inspection_failed' })
+    expect(signalProcess).not.toHaveBeenCalled()
+    expect(readCommandLine).not.toHaveBeenCalled()
+  })
 })
 
 describe('daemon audit availability evidence', () => {
diff --git a/src/main/daemon/daemon-incarnation-evidence.ts b/src/main/daemon/daemon-incarnation-evidence.ts
index b5c5429a9f2..01d9ffc97c5 100644
--- a/src/main/daemon/daemon-incarnation-evidence.ts
+++ b/src/main/daemon/daemon-incarnation-evidence.ts
@@ -1,9 +1,5 @@
 import { parseLinuxStartTicks, readBootIdentity } from '../agent-hooks/managed-hook-owner-identity'
-import {
-  commandLineMatchesDaemon,
-  getProcessStartedAtMs,
-  startTimesWithinTolerance
-} from './daemon-health'
+import { commandLineMatchesDaemon, startTimesWithinTolerance } from './daemon-health'
 import {
   WINDOWS_CREATION_TIME_TOLERANCE_MS,
   type DaemonEvidenceSources,
@@ -15,7 +11,9 @@ import {
 import {
   inspectProcessSignal,
   queryWindowsProcess,
+  readLinuxProcessStartedAtMs,
   readLinuxStat,
+  readMacosProcessStartedAtMs,
   readProcessCommandLine
 } from './daemon-process-inspection'
 
@@ -43,6 +41,9 @@ export async function probeDaemonProcessIdentity(
     return unknown('exact_identity_unavailable', ['pid_record'])
   }
   const platform = dependencies.platform ?? process.platform
+  if (platform !== 'linux' && platform !== 'darwin' && platform !== 'win32') {
+    return unknown('inspection_failed', ['process_signal'])
+  }
   const signalProcess = dependencies.signalProcess ?? inspectProcessSignal
   const signal = signalProcess(exactIncarnation.identity.pid)
   if (platform !== 'win32' && signal === 'missing') {
@@ -134,7 +135,7 @@ async function probeLinuxProcess(
     ])
   }
 
-  const startedAtMs = (dependencies.readProcessStartedAtMs ?? getProcessStartedAtMs)(
+  const startedAtMs = await (dependencies.readProcessStartedAtMs ?? readLinuxProcessStartedAtMs)(
     exactIncarnation.identity.pid
   )
   if (startedAtMs === null) {
@@ -172,7 +173,7 @@ async function probeMacosProcess(
   if (!commandLineMatchesDaemon(commandLine, endpoint.socketPath, endpoint.tokenPath)) {
     return unknown('command_line_mismatch', ['process_command_line'])
   }
-  const startedAtMs = (dependencies.readProcessStartedAtMs ?? getProcessStartedAtMs)(
+  const startedAtMs = await (dependencies.readProcessStartedAtMs ?? readMacosProcessStartedAtMs)(
     exactIncarnation.identity.pid
   )
   if (startedAtMs === null) {
diff --git a/src/main/daemon/daemon-process-inspection.test.ts b/src/main/daemon/daemon-process-inspection.test.ts
index 2b612fd068c..9da55aeb816 100644
--- a/src/main/daemon/daemon-process-inspection.test.ts
+++ b/src/main/daemon/daemon-process-inspection.test.ts
@@ -1,5 +1,14 @@
 import { describe, expect, it, vi } from 'vitest'
-import { queryWindowsProcess, readProcessCommandLine } from './daemon-process-inspection'
+import {
+  queryWindowsProcess,
+  readLinuxProcessStartedAtMs,
+  readMacosProcessStartedAtMs,
+  readProcessCommandLine
+} from './daemon-process-inspection'
+
+// btime 1699000000 with 1000 start ticks: 10s after boot at 100Hz, 1s at 1000Hz.
+const readProcStat = async (path: string): Promise<string> =>
+  path === '/proc/stat' ? 'btime 1699000000\n' : `42 (orca-daemon) S${' 0'.repeat(18)} 1000 0 0\n`
 
 describe('daemon process inspection', () => {
   it('falls back to ps when Linux procfs returns an empty command line', async () => {
@@ -23,6 +32,88 @@ describe('daemon process inspection', () => {
     expect(runCommand).not.toHaveBeenCalled()
   })
 
+  it('asks PowerShell to report a failed CIM query instead of an absent process', async () => {
+    const runCommand = vi.fn(
+      async (_file: string, _args: string[], _timeoutMs: number) =>
+        '{"status":"present","cmd":"daemon","start":1}'
+    )
+
+    await queryWindowsProcess(42, { runCommand })
+
+    const script = runCommand.mock.calls[0]?.[1].at(-1) ?? ''
+    expect(script).toContain("$ErrorActionPreference = 'Stop'")
+    expect(script).toMatch(/catch \{[^}]*query_failed/)
+  })
+
+  it('keeps a failed CIM query indeterminate instead of proving the process gone', async () => {
+    const runCommand = vi.fn(async () => '{"status":"query_failed"}')
+
+    await expect(queryWindowsProcess(42, { runCommand })).resolves.toEqual({
+      status: 'unavailable'
+    })
+  })
+
+  it('never reads a probe result without a success marker as proof of absence', async () => {
+    const runCommand = vi.fn(async () => '{"exists":false}')
+
+    await expect(queryWindowsProcess(42, { runCommand })).resolves.toEqual({
+      status: 'unavailable'
+    })
+  })
+
+  it('reports absence only from a CIM query that ran and found nothing', async () => {
+    const runCommand = vi.fn(async () => '{"status":"missing"}')
+
+    await expect(queryWindowsProcess(42, { runCommand })).resolves.toEqual({ status: 'missing' })
+  })
+
+  it('reads the macOS start time through an async spawn', async () => {
+    const runCommand = vi.fn(async () => 'Sat Jan  1 00:00:00 2028\n')
+
+    await expect(readMacosProcessStartedAtMs(42, { runCommand })).resolves.toBe(
+      Date.parse('Sat Jan  1 00:00:00 2028')
+    )
+    expect(runCommand).toHaveBeenCalledWith('ps', ['-p', '42', '-o', 'lstart='], 2_000)
+  })
+
+  // CLK_TCK belongs to the host that runs getconf, so a second runner must not inherit the first's.
+  it('scopes the CLK_TCK cache to the runner that produced it', async () => {
+    const hundredHz = vi.fn(async () => '100')
+    const thousandHz = vi.fn(async () => '1000')
+
+    await expect(
+      readLinuxProcessStartedAtMs(42, { readTextFile: readProcStat, runCommand: hundredHz })
+    ).resolves.toBe(1_699_000_010_000)
+    await expect(
+      readLinuxProcessStartedAtMs(42, { readTextFile: readProcStat, runCommand: thousandHz })
+    ).resolves.toBe(1_699_000_001_000)
+    expect(thousandHz).toHaveBeenCalledWith('getconf', ['CLK_TCK'], 1_000)
+
+    // The first runner stays cached: one spawn per runner, not per call.
+    await expect(
+      readLinuxProcessStartedAtMs(42, { readTextFile: readProcStat, runCommand: hundredHz })
+    ).resolves.toBe(1_699_000_010_000)
+    expect(hundredHz).toHaveBeenCalledOnce()
+  })
+
+  it('retries getconf for a runner whose first CLK_TCK read failed', async () => {
+    let attempt = 0
+    const runCommand = vi.fn(async () => {
+      attempt += 1
+      if (attempt === 1) {
+        throw new Error('getconf missing')
+      }
+      return '100'
+    })
+
+    await expect(
+      readLinuxProcessStartedAtMs(42, { readTextFile: readProcStat, runCommand })
+    ).resolves.toBeNull()
+    await expect(
+      readLinuxProcessStartedAtMs(42, { readTextFile: readProcStat, runCommand })
+    ).resolves.toBe(1_699_000_010_000)
+  })
+
   it.each([0, -1, 1.5, Number.MAX_SAFE_INTEGER + 1, Number.NaN])(
     'rejects unsafe Windows pid %s before command interpolation',
     async (pid) => {
diff --git a/src/main/daemon/daemon-process-inspection.ts b/src/main/daemon/daemon-process-inspection.ts
index 6dbc8ed55c4..1f066219b8b 100644
--- a/src/main/daemon/daemon-process-inspection.ts
+++ b/src/main/daemon/daemon-process-inspection.ts
@@ -1,6 +1,7 @@
 import { execFile } from 'node:child_process'
 import { readFile } from 'node:fs/promises'
 import { promisify } from 'node:util'
+import { parseLinuxBootTimeSeconds, parseLinuxProcStartTicks } from './daemon-health'
 import type {
   LinuxStatEvidence,
   ProcessSignalEvidence,
@@ -9,9 +10,11 @@ import type {
 
 const execFileAsync = promisify(execFile)
 
+type InspectionCommandRunner = (file: string, args: string[], timeoutMs: number) => Promise<string>
+
 export type DaemonProcessInspectionDependencies = {
   readTextFile?: (path: string) => Promise<string>
-  runCommand?: (file: string, args: string[], timeoutMs: number) => Promise<string>
+  runCommand?: InspectionCommandRunner
 }
 
 export function inspectProcessSignal(pid: number): ProcessSignalEvidence {
@@ -63,6 +66,9 @@ export async function readProcessCommandLine(
   }
 }
 
+// Why: Get-CimInstance errors (Winmgmt down, corrupt WMI repository, access denied) are
+// non-terminating and exit 0 with an empty $p, which is indistinguishable from "no such
+// process" — so the script reports query failure explicitly instead of asserting absence.
 export async function queryWindowsProcess(
   pid: number,
   dependencies: DaemonProcessInspectionDependencies = {}
@@ -78,23 +84,26 @@ export async function queryWindowsProcess(
         '-NoProfile',
         '-NonInteractive',
         '-Command',
-        `$p = Get-CimInstance Win32_Process -Filter "ProcessId = ${pid}"; ` +
-          `if (!$p) { @{ exists = $false } | ConvertTo-Json -Compress } else { ` +
+        `$ErrorActionPreference = 'Stop'; ` +
+          `try { $p = Get-CimInstance Win32_Process -Filter "ProcessId = ${pid}" } ` +
+          `catch { @{ status = 'query_failed' } | ConvertTo-Json -Compress; exit 0 }; ` +
+          `if (!$p) { @{ status = 'missing' } | ConvertTo-Json -Compress; exit 0 }; ` +
           `$start = $null; if ($p.CreationDate) { ` +
           `$start = [long]([DateTimeOffset]$p.CreationDate).ToUnixTimeMilliseconds() }; ` +
-          `@{ exists = $true; cmd = $p.CommandLine; start = $start } | ConvertTo-Json -Compress }`
+          `@{ status = 'present'; cmd = $p.CommandLine; start = $start } | ConvertTo-Json -Compress`
       ],
       3_000
     )
     const parsed = JSON.parse(stdout.trim()) as {
-      exists?: unknown
+      status?: unknown
       cmd?: unknown
       start?: unknown
     }
-    if (parsed.exists === false) {
+    // Only a query that ran and found nothing proves absence; anything else stays indeterminate.
+    if (parsed.status === 'missing') {
       return { status: 'missing' }
     }
-    if (parsed.exists !== true) {
+    if (parsed.status !== 'present') {
       return { status: 'unavailable' }
     }
     return {
@@ -108,6 +117,75 @@ export async function queryWindowsProcess(
   }
 }
 
+// Why: the sync procfs helper in daemon-health spawns getconf per call; CLK_TCK is fixed for
+// the kernel's lifetime, so cache one async spawn and only retry after a failure. The cache is
+// keyed by runner because CLK_TCK belongs to the host that executes the command, not the module.
+const clockTicksPerSecondByRunner = new WeakMap<InspectionCommandRunner, Promise<number | null>>()
+
+async function readClockTicksPerSecond(
+  runCommand: InspectionCommandRunner
+): Promise<number | null> {
+  let pending = clockTicksPerSecondByRunner.get(runCommand)
+  if (!pending) {
+    pending = runCommand('getconf', ['CLK_TCK'], 1_000).then(
+      (stdout) => {
+        const ticks = Number(stdout.trim())
+        return Number.isFinite(ticks) && ticks > 0 ? ticks : null
+      },
+      () => null
+    )
+    clockTicksPerSecondByRunner.set(runCommand, pending)
+  }
+  const ticksPerSecond = await pending
+  if (ticksPerSecond === null && clockTicksPerSecondByRunner.get(runCommand) === pending) {
+    clockTicksPerSecondByRunner.delete(runCommand)
+  }
+  return ticksPerSecond
+}
+
+// Why: same main-thread hazard as darwin — the sync linux helper does two readFileSync calls
+// plus a getconf spawn, and this audit-only probe runs in the Electron main process.
+export async function readLinuxProcessStartedAtMs(
+  pid: number,
+  dependencies: DaemonProcessInspectionDependencies = {}
+): Promise<number | null> {
+  const readTextFile =
+    dependencies.readTextFile ?? (async (path: string) => await readFile(path, 'utf8'))
+  try {
+    const startTicks = parseLinuxProcStartTicks(await readTextFile(`/proc/${pid}/stat`))
+    const bootTimeSeconds = parseLinuxBootTimeSeconds(await readTextFile('/proc/stat'))
+    const ticksPerSecond = await readClockTicksPerSecond(
+      dependencies.runCommand ?? runInspectionCommand
+    )
+    if (
+      ticksPerSecond === null ||
+      !Number.isFinite(startTicks) ||
+      !Number.isFinite(bootTimeSeconds)
+    ) {
+      return null
+    }
+    return bootTimeSeconds * 1000 + (startTicks / ticksPerSecond) * 1000
+  } catch {
+    return null
+  }
+}
+
+// Why: `ps` is darwin's only start-time source and this audit-only probe runs in the
+// Electron main process, where the sync spawn blocks every IPC/UI turn for its duration.
+export async function readMacosProcessStartedAtMs(
+  pid: number,
+  dependencies: DaemonProcessInspectionDependencies = {}
+): Promise<number | null> {
+  const runCommand = dependencies.runCommand ?? runInspectionCommand
+  try {
+    const stdout = await runCommand('ps', ['-p', String(pid), '-o', 'lstart='], 2_000)
+    const startedAtMs = Date.parse(stdout.trim())
+    return Number.isFinite(startedAtMs) ? startedAtMs : null
+  } catch {
+    return null
+  }
+}
+
 async function runInspectionCommand(
   file: string,
   args: string[],
diff --git a/src/main/daemon/daemon-pty-adapter.ts b/src/main/daemon/daemon-pty-adapter.ts
index 9fcf5a8633d..ef60ca5d9f1 100644
--- a/src/main/daemon/daemon-pty-adapter.ts
+++ b/src/main/daemon/daemon-pty-adapter.ts
@@ -77,7 +77,7 @@ import {
   type DaemonAuditTrigger
 } from './daemon-audit-classifier'
 import type { DaemonEvidenceSource, ExactDaemonIncarnation } from './daemon-incarnation-evidence'
-import { trackDaemonAuditEligibility } from './daemon-audit-eligibility-event'
+import { createDaemonAuditEligibilityTracker } from './daemon-audit-eligibility-event'
 
 type PendingDaemonSpawnOperation = {
   exitsBySessionId: Map<string, { incarnationId?: string }[]>
@@ -159,6 +159,8 @@ export class DaemonPtyAdapter implements IPtyProvider {
   private lastAuthenticatedIdentity: DaemonEndpointIdentity | null = null
   private exactDaemonIncarnation: ExactDaemonIncarnation | null = null
   private lastAuditObservation: DaemonAuditObservation | null = null
+  // Why: every listProcesses call republishes the same observation; unthrottled it drains the shared per-session telemetry ceiling.
+  private readonly trackAuditEligibility = createDaemonAuditEligibilityTracker()
   private auditObservationListeners: ((observation: DaemonAuditObservation) => void)[] = []
   private identityChangeListeners: ((event: DaemonIdentityChangeEvent) => void)[] = []
   private historyManager: HistoryManager | null
@@ -1723,7 +1725,7 @@ export class DaemonPtyAdapter implements IPtyProvider {
 
   private publishAuditObservation(observation: DaemonAuditObservation): void {
     this.lastAuditObservation = observation
-    trackDaemonAuditEligibility(observation)
+    this.trackAuditEligibility(observation)
     notifyAuditListeners(this.auditObservationListeners, observation)
   }
 
diff --git a/src/renderer/src/components/activity/activity-portal-readiness-loop.react185.test.tsx b/src/renderer/src/components/activity/activity-portal-readiness-loop.react185.test.tsx
index 916abbdcb69..14a1967a329 100644
--- a/src/renderer/src/components/activity/activity-portal-readiness-loop.react185.test.tsx
+++ b/src/renderer/src/components/activity/activity-portal-readiness-loop.react185.test.tsx
@@ -307,7 +307,6 @@ describe('Activity portal pane switching', () => {
   })
 
   it('releases a latched readiness once the terminal attaches', async () => {
-    // Drive rAF explicitly — wall-clock waits flake under CI load.
     const frames = installAnimationFrameController()
     const target = document.createElement('div')
     document.body.append(target)
@@ -334,20 +333,11 @@ describe('Activity portal pane switching', () => {
     }
     buildRoot('hidden')
 
-    let churning = true
-    let churns = 0
     const statuses: ActivityPortalReadinessStatus[] = []
 
     function ActivityTerminalSlot(): null {
       const status = useActivityTerminalPortalStatus(target, PANE_A.paneKey)
       statuses.push(status)
-      useLayoutEffect(() => {
-        if (!churning || churns > 30) {
-          return
-        }
-        churns += 1
-        buildRoot(status === 'unavailable' ? 'sibling' : 'hidden')
-      })
       return null
     }
 
@@ -355,21 +345,24 @@ describe('Activity portal pane switching', () => {
     await act(async () => {
       root.render(<ActivityTerminalSlot />)
     })
-    for (let frame = 0; frame < 40; frame += 1) {
-      if (frames.pending() === 0 && statuses.at(-1) === 'unavailable') {
-        break
-      }
+    await frames.flush()
+    expect(statuses.at(-1)).toBe('unavailable')
+
+    // Feed each observed DOM state separately so MutationObserver cannot coalesce the flips.
+    for (let flip = 0; flip < 9; flip += 1) {
+      await act(async () => {
+        buildRoot(flip % 2 === 0 ? 'sibling' : 'hidden')
+        await Promise.resolve()
+      })
       await frames.flush()
     }
     expect(statuses.at(-1)).toBe('unavailable')
 
-    churning = false
     await act(async () => {
       buildRoot('ready')
+      await Promise.resolve()
     })
-    for (let frame = 0; frame < 10 && statuses.at(-1) !== 'ready'; frame += 1) {
-      await frames.flush()
-    }
+    await frames.flush()
     expect(statuses.at(-1)).toBe('ready')
   })
 })

From fdb58695e9d08738c1cc16fd1c0b1f0e7937ca18 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Fri, 31 Jul 2026 04:58:15 -0700
Subject: [PATCH 17/23] [P1] fix(checks): stop skipped and manual checks
 reporting as failures (#11700)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(checks): stop skipped and manual checks reporting as failures

Route every check-classification surface through one shared helper so
desktop renderer, desktop main and mobile agree on the same verdict.

- GitLab `manual` jobs and pipelines are neutral again, not action_required/failure
- `skipped` counts as passed everywhere, including mobile
- a neutral check no longer demotes a summary that has passing checks

* fix(checks): move the check-classification parity test into the renderer project

The parity table lived in src/shared but imported a renderer module, and both
config/tsconfig.node.json and config/tsconfig.cli.json are composite projects
that include src/shared without that renderer path, so `pnpm typecheck` failed
with TS6307 on two of its three projects. Only the web project spans both trees.

Co-authored-by: Orca <help@stably.ai>

* fix(checks): stop the Tasks-grid pill contradicting its own verdict

The checks pill's label, tone and icon all read one ProviderCheckSummary, but
getChecksLabel short-circuited on the raw `neutral` counter while the tone and
icon key off `state`. After the classification fix a PR with 19 success + 1
neutral renders an emerald CheckCircle2 pill that reads "1 unresolved", and
mobile's own label (which keys off `state`) reads "19/20 passed" for the same
summary.

Move the label into src/shared/provider-check-summary.ts so desktop and mobile
cannot fork it again, and key it off `state`.

Also covers deriveWorkItemCheckSummary, the desktop-main producer of the summary
that reaches the Tasks grid and the relay-paired mobile client. It was rewritten
here with no test at all; the parity table stands in derivePRCheckStatusFromRollup,
which is a different normalizer. The new main-process test drives getWorkItem with
a real statusCheckRollup fixture, pinning the StatusContext `state` fallback that
would otherwise be deletable with the whole suite still green.

Co-authored-by: Orca <help@stably.ai>

* fix(gitlab): route the pipeline job-array rollup through the shared check classifier

The array path in derivePipelineStatus kept its own copy of the rollup rules, so
manual-only read green and one unrecognized job status demoted a passing pipeline
to neutral — both disagreeing with every other check surface.

Also retry the packaged-CLI smoke temp cleanup on Windows: the copied Orca.exe can
still be locked by AV/indexers after every assertion passed, failing the package job.

Co-authored-by: Orca <help@stably.ai>

* fix(gitlab): stop the skipped pipeline string diverging from the Checks tab

- classifyPipelineString now counts a skipped pipeline as passing, matching
  the per-check classifier; canceled stays neutral and is pinned as an
  explicit, sign-off-pending divergence.
- Pin the production string path (head_pipeline.status) in the parity table
  and note that the job-array branch has no production caller yet.
- Count skipped checks in the Checks panel's passing header so it agrees
  with the checks pill.
- Correct the packaged-CLI smoke retry comment: the EBUSY is the smoke's own
  just-exited Electron process, not AV/indexers.

Co-authored-by: Orca <help@stably.ai>

* fix(checks): finish cross-surface check parity and back out the skipped MR-card flip

Review follow-ups on the check-classification PR.

- PullRequestPage and GitHubItemDialog kept private copies of getCheckCounts /
  getChecksSummaryLabel that still counted only `success` as passing, so a
  2-success/3-skipped PR read "2 passing · 3 skipped" there and "5 passing" in
  the sidebar. Both copies move to pr-check-counts.ts, which routes the passing
  bucket through classifyCheckOutcome; action_required keeps its own amber
  bucket. The summary icon now keys off passing count, so an all-neutral PR
  stops painting a green tick above "0 of N checks passing".
- The sidebar checks header and triage strip still called
  `{status: completed, conclusion: null}` pending, contradicting the grey
  "Unresolved checks" pill. Both now read summarizeProviderChecks and render an
  unresolved chip/strip instead of an amber spinner that can never resolve.
- classifyPipelineString('skipped') is reverted to neutral. That flip painted
  MR cards green for pipelines that never ran, on the only GitLab path with
  production callers, and contradicted the same function's deferral of
  `canceled`. Both tone changes stay deferred, pinned by one test.
- classifyPipelineString('manual') resolves to pending rather than neutral: a
  blocked pipeline is outstanding, and neutral let the worktree card fall
  through to its emerald `open` default while GitLab still refuses the merge.
- TaskPage's checks pill helpers move to task-page-checks-pill.ts so the
  "1 unresolved on a green pill" fix is actually pinned by a test.
- smoke-packaged-cli no longer lets an EBUSY cleanup replace the real failure.

* fix(checks): stop completed unknown checks from spinning

---------

Co-authored-by: Orca <help@stably.ai>
---
 config/scripts/smoke-packaged-cli.mjs         |  30 ++-
 config/tsconfig.tc.web.json                   |   1 +
 mobile/src/tasks/github-check-summary.test.ts |  91 +++++++-
 mobile/src/tasks/github-check-summary.ts      |  59 +----
 mobile/src/tasks/gitlab-check-summary.ts      |  40 +---
 .../src/tasks/mobile-hosted-check-status.ts   |  18 +-
 .../client-work-item-check-summary.test.ts    | 155 ++++++++++++++
 src/main/github/client.ts                     |  52 ++---
 src/main/gitlab/mappers.test.ts               |  46 +++-
 src/main/gitlab/mappers.ts                    |  57 +++--
 .../src/components/GitHubItemDialog.tsx       |  70 +-----
 .../src/components/PullRequestPage.tsx        |  70 +-----
 src/renderer/src/components/TaskPage.tsx      |  35 +--
 ...b-enterprise-slug-routing-boundary.test.ts |   4 +-
 .../src/components/pr-check-counts.test.ts    |  84 ++++++++
 .../src/components/pr-check-counts.ts         |  66 ++++++
 ...ovider-check-classification-parity.test.ts | 201 ++++++++++++++++++
 .../checks-panel-content.test.tsx             |  89 ++++++++
 .../right-sidebar/checks-panel-content.tsx    |  70 +++++-
 .../sidebar/worktree-review-helpers.test.tsx  |  18 ++
 .../components/task-page-checks-pill.test.ts  |  54 +++++
 .../src/components/task-page-checks-pill.ts   |  26 +++
 .../task-page-pr-check-summary.test.ts        |   2 +-
 .../components/task-page-pr-check-summary.ts  |  53 +----
 src/renderer/src/i18n/locales/en.json         |   2 +
 src/shared/gitlab-pipeline-checks.test.ts     |   2 +-
 src/shared/gitlab-pipeline-checks.ts          |   7 +-
 src/shared/pr-check-severity-order.test.ts    |   3 +-
 src/shared/pr-check-status.ts                 |  35 +--
 src/shared/provider-check-summary.ts          | 101 +++++++++
 30 files changed, 1116 insertions(+), 425 deletions(-)
 create mode 100644 src/main/github/client-work-item-check-summary.test.ts
 create mode 100644 src/renderer/src/components/pr-check-counts.test.ts
 create mode 100644 src/renderer/src/components/pr-check-counts.ts
 create mode 100644 src/renderer/src/components/provider-check-classification-parity.test.ts
 create mode 100644 src/renderer/src/components/task-page-checks-pill.test.ts
 create mode 100644 src/renderer/src/components/task-page-checks-pill.ts
 create mode 100644 src/shared/provider-check-summary.ts

diff --git a/config/scripts/smoke-packaged-cli.mjs b/config/scripts/smoke-packaged-cli.mjs
index 4cecf49ad4b..877150f9e9b 100644
--- a/config/scripts/smoke-packaged-cli.mjs
+++ b/config/scripts/smoke-packaged-cli.mjs
@@ -35,6 +35,7 @@ const appDir = resolve(readAppDirArg(process.argv.slice(2)))
 const tempRoot = await mkdtemp(join(tmpdir(), 'orca-packaged-cli-smoke-'))
 const copiedAppDir = join(tempRoot, basename(appDir))
 
+let smokeFailure = null
 try {
   await cp(appDir, copiedAppDir, { recursive: true, verbatimSymlinks: true })
   const cliPath = getPackagedCliPath(copiedAppDir)
@@ -73,6 +74,31 @@ try {
   assert.equal(install.executed, false)
   assert.equal(update.executed, false)
   console.log(`[packaged-cli-smoke] help and skills commands passed via ${cliPath}`)
-} finally {
-  await rm(tempRoot, { recursive: true, force: true })
+} catch (error) {
+  smokeFailure = error
+}
+
+// Why: on Windows the launcher above spawns the copied Orca.exe (and its crashpad/utility children)
+// once per command; those handles can outlive execFile's exit by a few ms, so this cleanup hits
+// EBUSY on our own just-exited process after every assertion already passed. Same retry treatment
+// as removeHostTree(); a lock that never clears still throws — unless the smoke run itself failed,
+// in which case surfacing EBUSY instead of the real assertion would hide the actual regression.
+const cleanupFailure = await rm(tempRoot, {
+  recursive: true,
+  force: true,
+  maxRetries: 20,
+  retryDelay: 250
+}).then(
+  () => null,
+  (error) => error
+)
+
+if (smokeFailure) {
+  if (cleanupFailure) {
+    console.warn(`[packaged-cli-smoke] temp cleanup failed: ${cleanupFailure.message}`)
+  }
+  throw smokeFailure
+}
+if (cleanupFailure) {
+  throw cleanupFailure
 }
diff --git a/config/tsconfig.tc.web.json b/config/tsconfig.tc.web.json
index 39756947028..d42021315f0 100644
--- a/config/tsconfig.tc.web.json
+++ b/config/tsconfig.tc.web.json
@@ -6,6 +6,7 @@
     "../src/renderer/src/**/*.tsx",
     "../src/preload/api-types.ts",
     "../src/shared/**/*",
+    "../src/main/gitlab/mappers.ts",
     "../src/main/ipc/worktree-branch-name.ts",
     "../src/main/ipc/worktree-logic.ts",
     "../src/main/ipc/worktree-linked-work-item-metadata.ts",
diff --git a/mobile/src/tasks/github-check-summary.test.ts b/mobile/src/tasks/github-check-summary.test.ts
index a173663d9a5..3eafcc7661d 100644
--- a/mobile/src/tasks/github-check-summary.test.ts
+++ b/mobile/src/tasks/github-check-summary.test.ts
@@ -1,6 +1,8 @@
 import { describe, expect, it } from 'vitest'
-import { buildGitHubCheckSummary } from './github-check-summary'
+import { buildGitHubCheckSummary, type GitHubCheckLike } from './github-check-summary'
 import { buildGitLabCheckSummary } from './gitlab-check-summary'
+import { summarizeProviderChecks } from '../../../src/shared/provider-check-summary'
+import type { ProviderCheckSummary } from '../../../src/shared/types'
 
 describe('buildGitHubCheckSummary', () => {
   it('returns none for empty check lists', () => {
@@ -31,14 +33,14 @@ describe('buildGitHubCheckSummary', () => {
     })
   })
 
-  it('keeps neutral and unknown terminal conclusions out of passed', () => {
+  it('keeps neutral and unknown terminal conclusions out of passed without demoting the PR', () => {
     expect(
       buildGitHubCheckSummary([
         { status: 'completed', conclusion: 'success' },
         { status: 'completed', conclusion: 'neutral' }
       ])
     ).toEqual({
-      state: 'neutral',
+      state: 'success',
       total: 2,
       passed: 1,
       failed: 0,
@@ -49,7 +51,7 @@ describe('buildGitHubCheckSummary', () => {
 
   it('rolls up GitLab jobs with unknown terminal statuses as neutral', () => {
     expect(buildGitLabCheckSummary([{ status: 'success' }, { status: 'future_status' }])).toEqual({
-      state: 'neutral',
+      state: 'success',
       total: 2,
       passed: 1,
       failed: 0,
@@ -58,3 +60,84 @@ describe('buildGitHubCheckSummary', () => {
     })
   })
 })
+
+type ParityCase = {
+  name: string
+  checks: GitHubCheckLike[]
+  expected: Omit<ProviderCheckSummary, 'total'>
+}
+
+const completed = (conclusion: string): GitHubCheckLike => ({ status: 'completed', conclusion })
+
+const PARITY_CASES: ParityCase[] = [
+  {
+    name: 'all success',
+    checks: [completed('success'), completed('success')],
+    expected: { state: 'success', passed: 2, failed: 0, pending: 0, neutral: 0 }
+  },
+  {
+    name: 'success plus skipped',
+    checks: [completed('success'), completed('skipped')],
+    expected: { state: 'success', passed: 2, failed: 0, pending: 0, neutral: 0 }
+  },
+  {
+    name: 'all skipped',
+    checks: [completed('skipped'), completed('skipped')],
+    expected: { state: 'success', passed: 2, failed: 0, pending: 0, neutral: 0 }
+  },
+  {
+    name: 'success plus neutral',
+    checks: [completed('success'), completed('neutral')],
+    expected: { state: 'success', passed: 1, failed: 0, pending: 0, neutral: 1 }
+  },
+  {
+    name: 'all neutral',
+    checks: [completed('neutral')],
+    expected: { state: 'neutral', passed: 0, failed: 0, pending: 0, neutral: 1 }
+  },
+  {
+    name: 'success plus failure',
+    checks: [completed('success'), completed('failure')],
+    expected: { state: 'failure', passed: 1, failed: 1, pending: 0, neutral: 0 }
+  },
+  {
+    name: 'success plus running',
+    checks: [completed('success'), { status: 'in_progress', conclusion: null }],
+    expected: { state: 'pending', passed: 1, failed: 0, pending: 1, neutral: 0 }
+  },
+  {
+    name: 'genuine action_required',
+    checks: [completed('success'), completed('action_required')],
+    expected: { state: 'failure', passed: 1, failed: 1, pending: 0, neutral: 0 }
+  }
+]
+
+describe('mobile / desktop check classification parity', () => {
+  it.each(PARITY_CASES)('$name matches the shared desktop classifier', ({ checks, expected }) => {
+    const summary = { ...expected, total: checks.length }
+    expect(buildGitHubCheckSummary(checks)).toEqual(summary)
+    expect(summarizeProviderChecks(checks)).toEqual(summary)
+  })
+
+  it.each([
+    {
+      name: 'GitLab manual gate only',
+      statuses: ['manual'],
+      expected: { state: 'neutral', passed: 0, failed: 0, pending: 0, neutral: 1 }
+    },
+    {
+      name: 'GitLab manual gate alongside a green pipeline',
+      statuses: ['manual', 'success'],
+      expected: { state: 'success', passed: 1, failed: 0, pending: 0, neutral: 1 }
+    }
+  ] satisfies {
+    name: string
+    statuses: string[]
+    expected: Omit<ProviderCheckSummary, 'total'>
+  }[])('$name never reads as failing', ({ statuses, expected }) => {
+    expect(buildGitLabCheckSummary(statuses.map((status) => ({ status })))).toEqual({
+      ...expected,
+      total: statuses.length
+    })
+  })
+})
diff --git a/mobile/src/tasks/github-check-summary.ts b/mobile/src/tasks/github-check-summary.ts
index a0006efb95d..8a69db32291 100644
--- a/mobile/src/tasks/github-check-summary.ts
+++ b/mobile/src/tasks/github-check-summary.ts
@@ -1,60 +1,15 @@
+import { summarizeProviderChecks } from '../../../src/shared/provider-check-summary'
+import type { ProviderCheckSummary } from '../../../src/shared/types'
+
 export type GitHubCheckLike = {
   status: string
   conclusion?: string | null
 }
 
-export type GitHubCheckSummary = {
-  state: 'success' | 'failure' | 'pending' | 'neutral' | 'none'
-  total: number
-  passed: number
-  failed: number
-  pending: number
-  neutral: number
-}
-
-function isFailedCheck(check: GitHubCheckLike): boolean {
-  return (
-    check.conclusion === 'failure' ||
-    check.conclusion === 'timed_out' ||
-    check.conclusion === 'cancelled'
-  )
-}
-
-function isPendingCheck(check: GitHubCheckLike): boolean {
-  return (
-    check.status === 'queued' || check.status === 'in_progress' || check.conclusion === 'pending'
-  )
-}
+export type GitHubCheckSummary = ProviderCheckSummary
 
+// Why: reuse the desktop classifier verbatim — a second copy is what let mobile call `skipped`
+// unresolved while desktop called the same PR green.
 export function buildGitHubCheckSummary(checks: GitHubCheckLike[]): GitHubCheckSummary {
-  let failed = 0
-  let pending = 0
-  let neutral = 0
-
-  for (const check of checks) {
-    if (isFailedCheck(check) || check.conclusion === 'action_required') {
-      failed += 1
-    } else if (isPendingCheck(check)) {
-      pending += 1
-    } else if (check.conclusion === 'success') {
-      continue
-    } else {
-      neutral += 1
-    }
-  }
-
-  const total = checks.length
-  const passed = total - failed - pending - neutral
-  const state =
-    total === 0
-      ? 'none'
-      : failed > 0
-        ? 'failure'
-        : pending > 0
-          ? 'pending'
-          : neutral > 0
-            ? 'neutral'
-            : 'success'
-
-  return { state, total, passed, failed, pending, neutral }
+  return summarizeProviderChecks(checks)
 }
diff --git a/mobile/src/tasks/gitlab-check-summary.ts b/mobile/src/tasks/gitlab-check-summary.ts
index d984b6e4283..b5834a1d8b9 100644
--- a/mobile/src/tasks/gitlab-check-summary.ts
+++ b/mobile/src/tasks/gitlab-check-summary.ts
@@ -1,37 +1,17 @@
-import { buildGitHubCheckSummary, type GitHubCheckLike } from './github-check-summary'
+import {
+  mapGitLabPipelineJobStatusToCheckStatus,
+  mapGitLabPipelineJobStatusToConclusion
+} from '../../../src/shared/gitlab-pipeline-checks'
+import { summarizeProviderChecks } from '../../../src/shared/provider-check-summary'
 import type { ProviderCheckSummary } from '../../../src/shared/types'
 
 type GitLabPipelineJobLike = { status: string }
 
 export function buildGitLabCheckSummary(jobs: GitLabPipelineJobLike[]): ProviderCheckSummary {
-  return buildGitHubCheckSummary(
-    jobs.map((job): GitHubCheckLike => {
-      const status = job.status.toLowerCase()
-      const nonterminal = [
-        'created',
-        'pending',
-        'scheduled',
-        'waiting_for_callback',
-        'waiting_for_resource',
-        'preparing'
-      ].includes(status)
-      return {
-        status: status === 'running' ? 'in_progress' : nonterminal ? 'queued' : 'completed',
-        conclusion:
-          status === 'success'
-            ? 'success'
-            : status === 'failed'
-              ? 'failure'
-              : ['canceled', 'canceling'].includes(status)
-                ? 'cancelled'
-                : status === 'skipped'
-                  ? 'skipped'
-                  : ['manual', 'action_required'].includes(status)
-                    ? 'action_required'
-                    : status === 'running' || nonterminal
-                      ? 'pending'
-                      : null
-      }
-    })
+  return summarizeProviderChecks(
+    jobs.map((job) => ({
+      status: mapGitLabPipelineJobStatusToCheckStatus(job.status),
+      conclusion: mapGitLabPipelineJobStatusToConclusion(job.status)
+    }))
   )
 }
diff --git a/mobile/src/tasks/mobile-hosted-check-status.ts b/mobile/src/tasks/mobile-hosted-check-status.ts
index 341d71bc814..c1b6076c969 100644
--- a/mobile/src/tasks/mobile-hosted-check-status.ts
+++ b/mobile/src/tasks/mobile-hosted-check-status.ts
@@ -1,4 +1,5 @@
 import type { ProviderCheckSummary, PRMergeableState } from '../../../src/shared/types'
+import { getProviderChecksLabel } from '../../../src/shared/provider-check-summary'
 
 export type MobileHostedReviewStatus = {
   checksSummary?: ProviderCheckSummary
@@ -39,22 +40,7 @@ export function getHostedMergeLabel(item: MobileHostedReviewStatus): string {
 }
 
 export function getHostedChecksLabel(item: { checksSummary?: ProviderCheckSummary }): string {
-  const summary = item.checksSummary
-  if (!summary) {
-    return 'Checks'
-  }
-  if (summary.total === 0) {
-    return 'No checks'
-  }
-  if (summary.failed > 0) {
-    return `${summary.failed} failing`
-  }
-  if (summary.pending > 0) {
-    return `${summary.pending} pending`
-  }
-  return summary.state === 'neutral'
-    ? 'Unresolved checks'
-    : `${summary.passed}/${summary.total} passed`
+  return getProviderChecksLabel(item.checksSummary)
 }
 
 export function getHostedReviewSignalTone(
diff --git a/src/main/github/client-work-item-check-summary.test.ts b/src/main/github/client-work-item-check-summary.test.ts
new file mode 100644
index 00000000000..2543fa3a288
--- /dev/null
+++ b/src/main/github/client-work-item-check-summary.test.ts
@@ -0,0 +1,155 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { ghExecFileAsyncMock, getOwnerRepoMock, rateLimitGuardMock } = vi.hoisted(() => ({
+  ghExecFileAsyncMock: vi.fn(),
+  getOwnerRepoMock: vi.fn(),
+  rateLimitGuardMock: vi.fn(() => ({ blocked: false }))
+}))
+
+vi.mock('./gh-utils', () => ({
+  execFileAsync: vi.fn(),
+  ghExecFileAsync: ghExecFileAsyncMock,
+  githubRepoContext: (repoPath: string, connectionId?: string | null) => ({
+    repoPath,
+    connectionId: connectionId ?? null
+  }),
+  ghRepoExecOptions: (context: { repoPath: string }) => ({ cwd: context.repoPath }),
+  getOwnerRepo: getOwnerRepoMock,
+  getIssueOwnerRepo: vi.fn(),
+  getOwnerRepoForRemote: (
+    repoPath: string,
+    remoteName: string,
+    connectionId?: string | null,
+    localGitOptions?: unknown
+  ) =>
+    remoteName === 'origin'
+      ? getOwnerRepoMock(repoPath, connectionId, localGitOptions)
+      : Promise.resolve(null),
+  resolveIssueSource: vi.fn(),
+  extractExecError: vi.fn((err: unknown) => ({ stderr: String(err), stdout: '' })),
+  acquire: vi.fn(),
+  release: vi.fn(),
+  _resetOwnerRepoCache: vi.fn(),
+  classifyGhError: (stderr: string) => ({ type: 'unknown', message: stderr }),
+  classifyListIssuesError: (stderr: string) => ({ type: 'unknown', message: stderr })
+}))
+
+vi.mock('../git/runner', () => ({
+  gitExecFileAsync: vi.fn()
+}))
+
+vi.mock('./rate-limit', () => ({
+  rateLimitGuard: rateLimitGuardMock,
+  noteRateLimitSpend: vi.fn(),
+  getRateLimit: vi.fn(async () => ({ ok: false, error: 'not probed in tests' })),
+  repositoryRateLimitGuard: vi.fn(() => ({ blocked: false })),
+  noteRepositoryRateLimitSpend: vi.fn(),
+  spendsSharedGitHubComQuota: vi.fn(() => true)
+}))
+
+import { getWorkItem, _resetMergeQueueCacheForTests, _resetOwnerRepoCache } from './client'
+import { _resetOriginGitHubApiRepositoryCache } from './github-api-repository'
+
+// Why: only `pr view` is fixtured; the merge-metadata fan-out is best-effort and must not mask the summary.
+function mockPullRequestDetail(payload: Record<string, unknown>): void {
+  ghExecFileAsyncMock.mockImplementation(async (args: string[]) => {
+    if (args[0] !== 'pr' || args[1] !== 'view') {
+      throw new Error('unexpected gh call')
+    }
+    return { stdout: JSON.stringify(payload) }
+  })
+}
+
+describe('work item checksSummary', () => {
+  beforeEach(() => {
+    ghExecFileAsyncMock.mockReset()
+    getOwnerRepoMock.mockReset()
+    rateLimitGuardMock.mockReset()
+    rateLimitGuardMock.mockReturnValue({ blocked: false })
+    _resetOwnerRepoCache()
+    _resetOriginGitHubApiRepositoryCache()
+    _resetMergeQueueCacheForTests()
+    getOwnerRepoMock.mockResolvedValue({ owner: 'acme', repo: 'widgets' })
+  })
+
+  it('counts a skipped run as passing and reads a StatusContext state as its conclusion', async () => {
+    mockPullRequestDetail({
+      number: 42,
+      title: 'Add feature',
+      state: 'OPEN',
+      url: 'https://github.com/acme/widgets/pull/42',
+      updatedAt: '2026-04-01T00:00:00Z',
+      statusCheckRollup: [
+        { __typename: 'CheckRun', status: 'COMPLETED', conclusion: 'SKIPPED' },
+        // Why: StatusContext carries no status/conclusion — only `state`.
+        { __typename: 'StatusContext', state: 'SUCCESS' },
+        { __typename: 'CheckRun', status: 'COMPLETED', conclusion: 'NEUTRAL' }
+      ]
+    })
+
+    const item = await getWorkItem('/repo-root', 42, 'pr', null, {}, 'origin')
+
+    expect(item?.checksSummary).toEqual({
+      state: 'success',
+      total: 3,
+      passed: 2,
+      failed: 0,
+      pending: 0,
+      neutral: 1
+    })
+  })
+
+  it('reports a still-running check as pending', async () => {
+    mockPullRequestDetail({
+      number: 43,
+      title: 'Add feature',
+      state: 'OPEN',
+      url: 'https://github.com/acme/widgets/pull/43',
+      updatedAt: '2026-04-01T00:00:00Z',
+      statusCheckRollup: [
+        { __typename: 'CheckRun', status: 'COMPLETED', conclusion: 'SUCCESS' },
+        { __typename: 'CheckRun', status: 'IN_PROGRESS', conclusion: null }
+      ]
+    })
+
+    const item = await getWorkItem('/repo-root', 43, 'pr', null, {}, 'origin')
+
+    expect(item?.checksSummary).toEqual({
+      state: 'pending',
+      total: 2,
+      passed: 1,
+      failed: 0,
+      pending: 1,
+      neutral: 0
+    })
+  })
+
+  it('fails the summary on a failing run and leaves an empty rollup with no state', async () => {
+    mockPullRequestDetail({
+      number: 44,
+      title: 'Add feature',
+      state: 'OPEN',
+      url: 'https://github.com/acme/widgets/pull/44',
+      updatedAt: '2026-04-01T00:00:00Z',
+      statusCheckRollup: [
+        { __typename: 'CheckRun', status: 'COMPLETED', conclusion: 'SUCCESS' },
+        { __typename: 'CheckRun', status: 'COMPLETED', conclusion: 'FAILURE' }
+      ]
+    })
+    await expect(getWorkItem('/repo-root', 44, 'pr', null, {}, 'origin')).resolves.toMatchObject({
+      checksSummary: { state: 'failure', total: 2, passed: 1, failed: 1, pending: 0, neutral: 0 }
+    })
+
+    mockPullRequestDetail({
+      number: 45,
+      title: 'Add feature',
+      state: 'OPEN',
+      url: 'https://github.com/acme/widgets/pull/45',
+      updatedAt: '2026-04-01T00:00:00Z',
+      statusCheckRollup: []
+    })
+    await expect(getWorkItem('/repo-root', 45, 'pr', null, {}, 'origin')).resolves.toMatchObject({
+      checksSummary: { state: 'none', total: 0, passed: 0, failed: 0, pending: 0, neutral: 0 }
+    })
+  })
+})
diff --git a/src/main/github/client.ts b/src/main/github/client.ts
index d68c77ad263..ff602bc4dbe 100644
--- a/src/main/github/client.ts
+++ b/src/main/github/client.ts
@@ -27,6 +27,7 @@ import {
   normalizeHostedReviewHeadRef
 } from '../../shared/hosted-review-refs'
 import { normalizeGitHubPRMergeMethodSettings } from '../../shared/github-pr-merge-methods'
+import { summarizeProviderChecks } from '../../shared/provider-check-summary'
 import { isGitHubWorkItemsQueryTooLarge } from '../../shared/github-work-items-query-bounds'
 import { classifyGitHubUnavailable } from '../../shared/github-api-availability'
 import { parseTaskQuery, type ParsedTaskQuery } from '../../shared/task-query'
@@ -656,44 +657,19 @@ function checkRollupEntries(value: unknown): unknown[] {
 }
 
 function deriveWorkItemCheckSummary(value: unknown): GitHubWorkItem['checksSummary'] {
-  const entries = checkRollupEntries(value)
-  if (entries.length === 0) {
-    return { state: 'none', total: 0, passed: 0, failed: 0, pending: 0, neutral: 0 }
-  }
-  let passed = 0
-  let failed = 0
-  let pending = 0
-  let neutral = 0
-  for (const entry of entries) {
-    if (typeof entry !== 'object' || entry === null) {
-      pending += 1
-      continue
-    }
-    const raw = entry as Record<string, unknown>
-    const conclusion = String(raw.conclusion ?? raw.state ?? '').toUpperCase()
-    const status = String(raw.status ?? '').toUpperCase()
-    if (['SUCCESS', 'SKIPPED'].includes(conclusion)) {
-      passed += 1
-    } else if (
-      ['FAILURE', 'ERROR', 'TIMED_OUT', 'CANCELLED', 'ACTION_REQUIRED', 'STARTUP_FAILURE'].includes(
-        conclusion
-      )
-    ) {
-      failed += 1
-    } else if (status === 'COMPLETED') {
-      neutral += 1
-    } else {
-      pending += 1
-    }
-  }
-  return {
-    state: failed > 0 ? 'failure' : pending > 0 ? 'pending' : neutral > 0 ? 'neutral' : 'success',
-    total: entries.length,
-    passed,
-    failed,
-    pending,
-    neutral
-  }
+  return summarizeProviderChecks(
+    checkRollupEntries(value).map((entry) => {
+      if (typeof entry !== 'object' || entry === null) {
+        return { status: '', conclusion: '' }
+      }
+      const raw = entry as Record<string, unknown>
+      // Why: StatusContext reports `state` and carries no `status`; CheckRun reports both.
+      return {
+        status: String(raw.status ?? ''),
+        conclusion: String(raw.conclusion ?? raw.state ?? '')
+      }
+    })
+  )
 }
 
 function mapPullRequestWorkItem(
diff --git a/src/main/gitlab/mappers.test.ts b/src/main/gitlab/mappers.test.ts
index d96da3eb9be..8aef3b11511 100644
--- a/src/main/gitlab/mappers.test.ts
+++ b/src/main/gitlab/mappers.test.ts
@@ -38,8 +38,8 @@ describe('mapPipelineJobStatusToConclusion', () => {
     expect(mapPipelineJobStatusToConclusion('skipped')).toBe('skipped')
   })
 
-  it('maps manual and action-required jobs to an actionable conclusion', () => {
-    expect(mapPipelineJobStatusToConclusion('manual')).toBe('action_required')
+  it('keeps manual gates neutral while action-required stays actionable', () => {
+    expect(mapPipelineJobStatusToConclusion('manual')).toBe('neutral')
     expect(mapPipelineJobStatusToConclusion('action_required')).toBe('action_required')
   })
 
@@ -228,7 +228,23 @@ describe('derivePipelineStatus', () => {
     expect(derivePipelineStatus('success')).toBe('success')
     expect(derivePipelineStatus('failed')).toBe('failure')
     expect(derivePipelineStatus('running')).toBe('pending')
-    expect(derivePipelineStatus('manual')).toBe('failure')
+    // Why: pipeline-level `manual` means GitLab blocked the pipeline on a human trigger — it is
+    // outstanding, not broken (red) and not resolved (which would paint the MR card green while
+    // "Pipelines must succeed" still refuses the merge).
+    expect(derivePipelineStatus('manual')).toBe('pending')
+    expect(derivePipelineStatus({ status: 'manual' })).toBe('pending')
+  })
+
+  // Why: pins the two remaining string/array divergences. The job rollup calls skipped jobs
+  // passing and canceled jobs failing, but `head_pipeline.status` is the only production entry
+  // point and GitLab paints both pipeline states grey — flipping either card tone needs product
+  // sign-off, so these assertions exist so neither flip can land silently.
+  it('keeps skipped and canceled pipeline strings neutral (deferred tone changes)', () => {
+    expect(derivePipelineStatus('skipped')).toBe('neutral')
+    expect(derivePipelineStatus({ status: 'skipped' })).toBe('neutral')
+    expect(derivePipelineStatus('canceled')).toBe('neutral')
+    expect(derivePipelineStatus('canceling')).toBe('neutral')
+    expect(derivePipelineStatus([{ status: 'canceled' }])).toBe('failure')
   })
 
   it('rolls up an array of jobs', () => {
@@ -239,7 +255,22 @@ describe('derivePipelineStatus', () => {
 
   it('failure beats pending in the rollup', () => {
     expect(derivePipelineStatus([{ status: 'failed' }, { status: 'running' }])).toBe('failure')
-    expect(derivePipelineStatus([{ status: 'manual' }, { status: 'success' }])).toBe('failure')
+    expect(derivePipelineStatus([{ status: 'action_required' }, { status: 'success' }])).toBe(
+      'failure'
+    )
+  })
+
+  it('keeps a manual deploy gate from failing an otherwise green pipeline', () => {
+    expect(derivePipelineStatus([{ status: 'manual' }, { status: 'success' }])).toBe('success')
+  })
+
+  it('leaves a manual-only pipeline unresolved rather than green', () => {
+    expect(derivePipelineStatus([{ status: 'manual' }])).toBe('neutral')
+    expect(derivePipelineStatus([{ status: 'manual' }, { status: 'manual' }])).toBe('neutral')
+  })
+
+  it('counts skipped jobs as passing', () => {
+    expect(derivePipelineStatus([{ status: 'skipped' }, { status: 'skipped' }])).toBe('success')
   })
 
   it('handles a single object with status', () => {
@@ -249,8 +280,13 @@ describe('derivePipelineStatus', () => {
   it('keeps malformed and unknown array jobs neutral', () => {
     expect(derivePipelineStatus([{ status: 'future_status' }])).toBe('neutral')
     expect(derivePipelineStatus([{}])).toBe('neutral')
+  })
+
+  // Why: matches the shared rollup rule — one unresolved job must not demote a pipeline that has
+  // a passing job, or the same MR reads green in the Checks tab and grey on the card.
+  it('lets a passing job outweigh an unknown one', () => {
     expect(derivePipelineStatus([{ status: 'success' }, { status: 'future_status' }])).toBe(
-      'neutral'
+      'success'
     )
   })
 })
diff --git a/src/main/gitlab/mappers.ts b/src/main/gitlab/mappers.ts
index 7b45c9b64f0..ca1c5d794ee 100644
--- a/src/main/gitlab/mappers.ts
+++ b/src/main/gitlab/mappers.ts
@@ -9,6 +9,7 @@ import {
   mapGitLabPipelineJobStatusToCheckStatus,
   mapGitLabPipelineJobStatusToConclusion
 } from '../../shared/gitlab-pipeline-checks'
+import { summarizeProviderChecks } from '../../shared/provider-check-summary'
 
 // ── Pipeline job mapping (GitLab REST `/pipelines/:id/jobs`) ────────
 // Why: GitLab pipeline jobs roughly map to GitHub check-runs, but use a
@@ -156,34 +157,20 @@ export function derivePipelineStatus(
   if (!Array.isArray(rollup)) {
     return classifyPipelineString(rollup.status ?? '')
   }
-  if (rollup.length === 0) {
-    return 'neutral'
-  }
-  let hasFailure = false
-  let hasPending = false
-  let hasUnknown = false
-  for (const job of rollup) {
-    const s = job.status?.toLowerCase() ?? ''
-    const conclusion = mapPipelineJobStatusToConclusion(s)
-    if (
-      conclusion === 'failure' ||
-      conclusion === 'cancelled' ||
-      conclusion === 'action_required'
-    ) {
-      hasFailure = true
-    } else if (conclusion === 'pending') {
-      hasPending = true
-    } else if (conclusion !== 'success' && conclusion !== 'skipped' && conclusion !== 'neutral') {
-      hasUnknown = true
-    }
-  }
-  if (hasFailure) {
-    return 'failure'
-  }
-  if (hasPending) {
-    return 'pending'
-  }
-  return hasUnknown ? 'neutral' : 'success'
+  // Why: a job array is just a check list, so route it through the shared classifier instead of
+  // re-deriving the rules here — a local copy drifted (manual-only read green, an unrecognized
+  // status demoted a passing pipeline to neutral).
+  const { state } = summarizeProviderChecks(
+    rollup.map((job) => {
+      const s = job.status?.toLowerCase() ?? ''
+      return {
+        status: mapPipelineJobStatusToCheckStatus(s),
+        conclusion: mapPipelineJobStatusToConclusion(s)
+      }
+    })
+  )
+  // Why: CheckStatus has no 'none'; an empty job list carries the same "nothing to report" meaning.
+  return state === 'none' ? 'neutral' : state
 }
 
 // ── Raw → GitLabWorkItem mapping ────────────────────────────────────
@@ -289,9 +276,21 @@ function classifyPipelineString(status: string): CheckStatus {
   if (s === 'success') {
     return 'success'
   }
-  if (s === 'failed' || s === 'manual' || s === 'action_required') {
+  if (s === 'failed' || s === 'action_required') {
     return 'failure'
   }
+  // Why: GitLab only reports pipeline-level `manual` when the pipeline is *blocked* on a human
+  // trigger (a manual job with allow_failure: false), so it is outstanding rather than broken or
+  // done. Red overstated it; neutral would drop the cue entirely and paint the worktree card's MR
+  // icon green (worktree-review-helpers.tsx defaults `open` to emerald), which is worse — with
+  // "Pipelines must succeed" on, GitLab rejects this merge.
+  if (s === 'manual') {
+    return 'pending'
+  }
+  // Why: `skipped` and `canceled` pipelines stay neutral (the fall-through below) even though the
+  // job rollup calls the same jobs passing/failing. GitLab's own MR widget paints both grey, and
+  // `allow_merge_on_skipped_pipeline` defaults to false, so a skipped pipeline still blocks merge —
+  // flipping either tone is a product decision that belongs in its own change, not this one.
   if (
     s === 'created' ||
     s === 'pending' ||
diff --git a/src/renderer/src/components/GitHubItemDialog.tsx b/src/renderer/src/components/GitHubItemDialog.tsx
index bdb96e71941..c89805e05f3 100644
--- a/src/renderer/src/components/GitHubItemDialog.tsx
+++ b/src/renderer/src/components/GitHubItemDialog.tsx
@@ -232,6 +232,11 @@ import {
   type TaskPageGitHubCloseAction
 } from '@/components/task-page-github-status-actions'
 import { sortChecksBySeverity } from '../../../shared/pr-check-severity-order'
+import {
+  getCheckConclusion,
+  getCheckCounts,
+  getChecksSummaryLabel
+} from '@/components/pr-check-counts'
 
 // Why: the dialog lacks repository context, so recover its host-aware identity from the canonical item URL.
 function parseOwnerRepoFromItemUrl(url: string): GitHubOwnerRepo | null {
@@ -4321,10 +4326,6 @@ function CommentReplyForm({
   )
 }
 
-function getCheckConclusion(check: PRCheckDetail): NonNullable<PRCheckDetail['conclusion']> {
-  return check.conclusion ?? 'pending'
-}
-
 function getCheckStatusLabel(check: PRCheckDetail): string {
   const conclusion = getCheckConclusion(check)
   if (conclusion === 'success') {
@@ -4357,57 +4358,6 @@ function getCheckStatusLabel(check: PRCheckDetail): string {
   return 'Pending'
 }
 
-function getCheckCounts(checks: PRCheckDetail[]): {
-  passing: number
-  failing: number
-  needsAction: number
-  pending: number
-  skipped: number
-  neutral: number
-} {
-  return checks.reduce(
-    (counts, check) => {
-      const conclusion = getCheckConclusion(check)
-      if (conclusion === 'success') {
-        counts.passing += 1
-      } else if (conclusion === 'action_required') {
-        counts.needsAction += 1
-      } else if (['failure', 'cancelled', 'timed_out'].includes(conclusion)) {
-        counts.failing += 1
-      } else if (conclusion === 'skipped') {
-        counts.skipped += 1
-      } else if (conclusion === 'neutral') {
-        counts.neutral += 1
-      } else {
-        counts.pending += 1
-      }
-      return counts
-    },
-    { passing: 0, failing: 0, needsAction: 0, pending: 0, skipped: 0, neutral: 0 }
-  )
-}
-
-function getChecksSummaryLabel(checks: PRCheckDetail[]): string {
-  const counts = getCheckCounts(checks)
-  if (checks.length === 0) {
-    return 'No checks found'
-  }
-  if (counts.failing > 0) {
-    return `${counts.failing} ${counts.failing === 1 ? 'check' : 'checks'} failing`
-  }
-  // Why: action_required blocks merge but isn't a failure; surface it distinctly so users know a manual step is needed.
-  if (counts.needsAction > 0) {
-    return `${counts.needsAction} ${counts.needsAction === 1 ? 'check needs' : 'checks need'} action`
-  }
-  if (counts.pending > 0) {
-    return `${counts.pending} ${counts.pending === 1 ? 'check' : 'checks'} pending`
-  }
-  if (counts.passing === checks.length) {
-    return 'All checks passing'
-  }
-  return `${counts.passing} of ${checks.length} checks passing`
-}
-
 function getCheckDetailsKey(check: PRCheckDetail): string {
   return String(check.checkRunId ?? check.workflowRunId ?? check.url ?? check.name)
 }
@@ -4468,6 +4418,8 @@ function ChecksTab({
   const failedChecks = getBrokenChecks(list)
   const counts = getCheckCounts(list)
   const summaryLabel = getChecksSummaryLabel(list)
+  // Why: keying the green tick off `list.length` painted an all-neutral PR green above the words
+  // "0 of N checks passing"; nothing passed, so it reads unresolved like the checks pill does.
   const SummaryIcon =
     counts.failing > 0
       ? CHECK_ICON.failure
@@ -4475,7 +4427,7 @@ function ChecksTab({
         ? CHECK_ICON.action_required
         : counts.pending > 0
           ? CHECK_ICON.pending
-          : list.length > 0
+          : counts.passing > 0
             ? CHECK_ICON.success
             : CircleDashed
   const summaryColor =
@@ -4485,7 +4437,7 @@ function ChecksTab({
         ? CHECK_COLOR.action_required
         : counts.pending > 0
           ? CHECK_COLOR.pending
-          : list.length > 0
+          : counts.passing > 0
             ? CHECK_COLOR.success
             : 'text-muted-foreground'
   const canFixBrokenChecks = Boolean((repoId ?? item.repoId) && failedChecks.length > 0)
@@ -5208,10 +5160,10 @@ function ChecksTab({
         className: CHECK_COLOR.pending
       })
     }
-    if (counts.skipped + counts.neutral > 0) {
+    if (counts.neutral > 0) {
       countChips.push({
         label: translate('auto.components.GitHubItemDialog.d23bbb6416', '{{value0}} skipped', {
-          value0: counts.skipped + counts.neutral
+          value0: counts.neutral
         }),
         className: 'text-muted-foreground'
       })
diff --git a/src/renderer/src/components/PullRequestPage.tsx b/src/renderer/src/components/PullRequestPage.tsx
index a835ac96dd3..3620a69653e 100644
--- a/src/renderer/src/components/PullRequestPage.tsx
+++ b/src/renderer/src/components/PullRequestPage.tsx
@@ -228,6 +228,11 @@ import {
 import { translate } from '@/i18n/i18n'
 import { getSettingsForRepoRuntimeOwner } from '@/lib/repo-runtime-owner'
 import { sortChecksBySeverity } from '../../../shared/pr-check-severity-order'
+import {
+  getCheckConclusion,
+  getCheckCounts,
+  getChecksSummaryLabel
+} from '@/components/pr-check-counts'
 
 // Why: the item URL is the only host-aware repository identity present on every work item across IPC.
 function parseOwnerRepoFromItemUrl(url: string): GitHubOwnerRepo | null {
@@ -4330,10 +4335,6 @@ function CommentReplyForm({
   )
 }
 
-function getCheckConclusion(check: PRCheckDetail): NonNullable<PRCheckDetail['conclusion']> {
-  return check.conclusion ?? 'pending'
-}
-
 function getCheckStatusLabel(check: PRCheckDetail): string {
   const conclusion = getCheckConclusion(check)
   if (conclusion === 'success') {
@@ -4366,57 +4367,6 @@ function getCheckStatusLabel(check: PRCheckDetail): string {
   return 'Pending'
 }
 
-function getCheckCounts(checks: PRCheckDetail[]): {
-  passing: number
-  failing: number
-  needsAction: number
-  pending: number
-  skipped: number
-  neutral: number
-} {
-  return checks.reduce(
-    (counts, check) => {
-      const conclusion = getCheckConclusion(check)
-      if (conclusion === 'success') {
-        counts.passing += 1
-      } else if (conclusion === 'action_required') {
-        counts.needsAction += 1
-      } else if (['failure', 'cancelled', 'timed_out'].includes(conclusion)) {
-        counts.failing += 1
-      } else if (conclusion === 'skipped') {
-        counts.skipped += 1
-      } else if (conclusion === 'neutral') {
-        counts.neutral += 1
-      } else {
-        counts.pending += 1
-      }
-      return counts
-    },
-    { passing: 0, failing: 0, needsAction: 0, pending: 0, skipped: 0, neutral: 0 }
-  )
-}
-
-function getChecksSummaryLabel(checks: PRCheckDetail[]): string {
-  const counts = getCheckCounts(checks)
-  if (checks.length === 0) {
-    return 'No checks found'
-  }
-  if (counts.failing > 0) {
-    return `${counts.failing} ${counts.failing === 1 ? 'check' : 'checks'} failing`
-  }
-  // Why: action_required (e.g. workflow awaiting approval) blocks merge but isn't a failure, so surface it distinctly.
-  if (counts.needsAction > 0) {
-    return `${counts.needsAction} ${counts.needsAction === 1 ? 'check needs' : 'checks need'} action`
-  }
-  if (counts.pending > 0) {
-    return `${counts.pending} ${counts.pending === 1 ? 'check' : 'checks'} pending`
-  }
-  if (counts.passing === checks.length) {
-    return 'All checks passing'
-  }
-  return `${counts.passing} of ${checks.length} checks passing`
-}
-
 function getCheckDetailsKey(check: PRCheckDetail): string {
   return String(check.checkRunId ?? check.workflowRunId ?? check.url ?? check.name)
 }
@@ -4572,6 +4522,8 @@ function ChecksTab({
   const failedChecks = getBrokenChecks(list)
   const counts = getCheckCounts(list)
   const summaryLabel = getChecksSummaryLabel(list)
+  // Why: keying the green tick off `list.length` painted an all-neutral PR green above the words
+  // "0 of N checks passing"; nothing passed, so it reads unresolved like the checks pill does.
   const SummaryIcon =
     counts.failing > 0
       ? CHECK_ICON.failure
@@ -4579,7 +4531,7 @@ function ChecksTab({
         ? CHECK_ICON.action_required
         : counts.pending > 0
           ? CHECK_ICON.pending
-          : list.length > 0
+          : counts.passing > 0
             ? CHECK_ICON.success
             : CircleDashed
   const summaryColor =
@@ -4589,7 +4541,7 @@ function ChecksTab({
         ? CHECK_COLOR.action_required
         : counts.pending > 0
           ? CHECK_COLOR.pending
-          : list.length > 0
+          : counts.passing > 0
             ? CHECK_COLOR.success
             : 'text-muted-foreground'
   const canFixBrokenChecks = Boolean((repoId ?? item.repoId) && failedChecks.length > 0)
@@ -5342,10 +5294,10 @@ function ChecksTab({
         className: CHECK_COLOR.pending
       })
     }
-    if (counts.skipped + counts.neutral > 0) {
+    if (counts.neutral > 0) {
       countChips.push({
         label: translate('auto.components.PullRequestPage.e6ad0a8d06', '{{value0}} skipped', {
-          value0: counts.skipped + counts.neutral
+          value0: counts.neutral
         }),
         className: 'text-muted-foreground'
       })
diff --git a/src/renderer/src/components/TaskPage.tsx b/src/renderer/src/components/TaskPage.tsx
index f9dac6c9fa3..5c30fa545d0 100644
--- a/src/renderer/src/components/TaskPage.tsx
+++ b/src/renderer/src/components/TaskPage.tsx
@@ -209,6 +209,7 @@ import {
   taskPageToGitHubApiPage
 } from '@/components/task-page-work-item-pagination'
 import { sortWorkItemsByNumber } from '../../../shared/work-items'
+import { getChecksLabel, getChecksPillTone } from '@/components/task-page-checks-pill'
 import LinearIssueAttributeFilterDropdowns from '@/components/linear-issue-attribute-filter-dropdowns'
 import { resolveLinearIssueAttributeFilterPrimaryTeam } from '@/components/linear-issue-attribute-filter-primary-team'
 import {
@@ -2012,40 +2013,6 @@ function GHAssigneesCell({
   )
 }
 
-function getChecksLabel(item: GitHubWorkItem): string {
-  const summary = item.checksSummary
-  if (!summary) {
-    return 'Checks'
-  }
-  if (summary.total === 0) {
-    return 'No checks'
-  }
-  if (summary.failed > 0) {
-    return `${summary.failed} failing`
-  }
-  if (summary.pending > 0) {
-    return `${summary.pending} pending`
-  }
-  if (summary.neutral > 0) {
-    return `${summary.neutral} unresolved`
-  }
-  return `${summary.passed}/${summary.total} passed`
-}
-
-function getChecksPillTone(item: GitHubWorkItem): string {
-  const state = item.checksSummary?.state
-  if (state === 'success') {
-    return 'border-emerald-500/30 bg-emerald-500/10 text-emerald-700 dark:text-emerald-200'
-  }
-  if (state === 'failure') {
-    return 'border-rose-500/30 bg-rose-500/10 text-rose-700 dark:text-rose-200'
-  }
-  if (state === 'pending') {
-    return 'border-amber-500/30 bg-amber-500/10 text-amber-700 dark:text-amber-200'
-  }
-  return 'border-border/60 bg-background/70 text-muted-foreground'
-}
-
 function sameOptionalGitHubOwnerRepo(
   left: GitHubOwnerRepo | null | undefined,
   right: GitHubOwnerRepo | null | undefined
diff --git a/src/renderer/src/components/github-enterprise-slug-routing-boundary.test.ts b/src/renderer/src/components/github-enterprise-slug-routing-boundary.test.ts
index f5a3023d75f..984d73db719 100644
--- a/src/renderer/src/components/github-enterprise-slug-routing-boundary.test.ts
+++ b/src/renderer/src/components/github-enterprise-slug-routing-boundary.test.ts
@@ -18,10 +18,12 @@ describe('GitHub Enterprise slug routing boundaries', () => {
   it('keeps work-item URL hosts on TaskPage metadata and issue mutations', () => {
     const source = componentSource('TaskPage.tsx')
     const statusSection = sourceBetween(source, 'function GHStatusCell', 'function formatPRDelta')
+    // Why: the end sentinel just bounds GHAssigneesCell's body — getChecksLabel moved out to
+    // task-page-checks-pill.ts, so the next declaration is the boundary now.
     const assigneeSection = sourceBetween(
       source,
       'function GHAssigneesCell',
-      'function getChecksLabel'
+      'function sameOptionalGitHubOwnerRepo'
     )
 
     expect(statusSection).toContain('host: githubProjectHost(parsedOwnerRepo.host)')
diff --git a/src/renderer/src/components/pr-check-counts.test.ts b/src/renderer/src/components/pr-check-counts.test.ts
new file mode 100644
index 00000000000..8f2fa37c2ef
--- /dev/null
+++ b/src/renderer/src/components/pr-check-counts.test.ts
@@ -0,0 +1,84 @@
+import { describe, expect, it } from 'vitest'
+import { getCheckCounts, getChecksSummaryLabel } from './pr-check-counts'
+import {
+  getProviderChecksLabel,
+  summarizeProviderChecks
+} from '../../../shared/provider-check-summary'
+import type { PRCheckDetail } from '../../../shared/types'
+
+function check(conclusion: PRCheckDetail['conclusion'], name = String(conclusion)): PRCheckDetail {
+  return { name, status: 'completed', conclusion, url: null }
+}
+
+describe('getCheckCounts', () => {
+  // Why: the PR page, the work-item dialog and the sidebar Checks panel all count this same list;
+  // a 2-success/3-skipped PR used to read "2 passing · 3 skipped" here and "5 passing" there.
+  it('counts skipped checks as passing, matching the sidebar header and the checks pill', () => {
+    const checks = [
+      check('success', 'build'),
+      check('success', 'test'),
+      check('skipped', 'deploy'),
+      check('skipped', 'docs'),
+      check('skipped', 'e2e')
+    ]
+
+    expect(getCheckCounts(checks)).toEqual({
+      passing: 5,
+      failing: 0,
+      needsAction: 0,
+      pending: 0,
+      neutral: 0
+    })
+    expect(getChecksSummaryLabel(checks)).toBe('All checks passing')
+    expect(summarizeProviderChecks(checks).passed).toBe(5)
+    expect(getProviderChecksLabel(summarizeProviderChecks(checks))).toBe('5/5 passed')
+  })
+
+  // Why: action_required blocks merge but is not a red failure, so it keeps its own amber bucket
+  // even though the shared rollup treats it as failing.
+  it('keeps action_required separate from failures', () => {
+    expect(getCheckCounts([check('action_required'), check('failure')])).toEqual({
+      passing: 0,
+      failing: 1,
+      needsAction: 1,
+      pending: 0,
+      neutral: 0
+    })
+    expect(getChecksSummaryLabel([check('action_required')])).toBe('1 check needs action')
+  })
+
+  it('buckets neutral and still-running checks apart', () => {
+    const checks: PRCheckDetail[] = [
+      check('neutral'),
+      { name: 'ci', status: 'in_progress', conclusion: null, url: null }
+    ]
+
+    expect(getCheckCounts(checks)).toEqual({
+      passing: 0,
+      failing: 0,
+      needsAction: 0,
+      pending: 1,
+      neutral: 1
+    })
+    expect(getChecksSummaryLabel(checks)).toBe('1 check pending')
+  })
+
+  it('keeps a completed check without a conclusion unresolved', () => {
+    const checks: PRCheckDetail[] = [
+      { name: 'external', status: 'completed', conclusion: null, url: null }
+    ]
+
+    expect(getCheckCounts(checks)).toEqual({
+      passing: 0,
+      failing: 0,
+      needsAction: 0,
+      pending: 0,
+      neutral: 1
+    })
+    expect(getChecksSummaryLabel(checks)).toBe('0 of 1 checks passing')
+  })
+
+  it('reports no checks for an empty list', () => {
+    expect(getChecksSummaryLabel([])).toBe('No checks found')
+  })
+})
diff --git a/src/renderer/src/components/pr-check-counts.ts b/src/renderer/src/components/pr-check-counts.ts
new file mode 100644
index 00000000000..9cf91a3c89b
--- /dev/null
+++ b/src/renderer/src/components/pr-check-counts.ts
@@ -0,0 +1,66 @@
+import { classifyCheckOutcome } from '../../../shared/provider-check-summary'
+import type { PRCheckDetail } from '../../../shared/types'
+
+export type PRCheckCounts = {
+  passing: number
+  failing: number
+  needsAction: number
+  pending: number
+  neutral: number
+}
+
+export function getCheckConclusion(check: PRCheckDetail): NonNullable<PRCheckDetail['conclusion']> {
+  if (check.conclusion) {
+    return check.conclusion
+  }
+  return check.status === 'completed' ? 'neutral' : 'pending'
+}
+
+/**
+ * The check-tab breakdown shared by the PR page and the work-item dialog. Both panes used to keep
+ * private copies, which is how one drifted from the Checks panel's own header.
+ */
+export function getCheckCounts(checks: readonly PRCheckDetail[]): PRCheckCounts {
+  return checks.reduce<PRCheckCounts>(
+    (counts, check) => {
+      const conclusion = getCheckConclusion(check)
+      // Why: the shared classifier counts a skipped check as passing, so bucketing it separately
+      // made this pane say "2 passing" for the same list the Checks panel called "5 passing".
+      // action_required stays its own bucket: it blocks merge but is not a red failure.
+      if (classifyCheckOutcome(check) === 'passed') {
+        counts.passing += 1
+      } else if (conclusion === 'action_required') {
+        counts.needsAction += 1
+      } else if (['failure', 'cancelled', 'timed_out'].includes(conclusion)) {
+        counts.failing += 1
+      } else if (conclusion === 'neutral') {
+        counts.neutral += 1
+      } else {
+        counts.pending += 1
+      }
+      return counts
+    },
+    { passing: 0, failing: 0, needsAction: 0, pending: 0, neutral: 0 }
+  )
+}
+
+export function getChecksSummaryLabel(checks: readonly PRCheckDetail[]): string {
+  const counts = getCheckCounts(checks)
+  if (checks.length === 0) {
+    return 'No checks found'
+  }
+  if (counts.failing > 0) {
+    return `${counts.failing} ${counts.failing === 1 ? 'check' : 'checks'} failing`
+  }
+  // Why: action_required (e.g. workflow awaiting approval) blocks merge but isn't a failure, so surface it distinctly.
+  if (counts.needsAction > 0) {
+    return `${counts.needsAction} ${counts.needsAction === 1 ? 'check needs' : 'checks need'} action`
+  }
+  if (counts.pending > 0) {
+    return `${counts.pending} ${counts.pending === 1 ? 'check' : 'checks'} pending`
+  }
+  if (counts.passing === checks.length) {
+    return 'All checks passing'
+  }
+  return `${counts.passing} of ${checks.length} checks passing`
+}
diff --git a/src/renderer/src/components/provider-check-classification-parity.test.ts b/src/renderer/src/components/provider-check-classification-parity.test.ts
new file mode 100644
index 00000000000..91830041bec
--- /dev/null
+++ b/src/renderer/src/components/provider-check-classification-parity.test.ts
@@ -0,0 +1,201 @@
+import { describe, expect, it } from 'vitest'
+import { deriveTaskPagePRCheckSummary } from './task-page-pr-check-summary'
+import { derivePipelineStatus } from '../../../main/gitlab/mappers'
+import { gitLabPipelineJobsToPRChecks } from '../../../shared/gitlab-pipeline-checks'
+import { derivePRCheckStatus, derivePRCheckStatusFromRollup } from '../../../shared/pr-check-status'
+import {
+  getProviderChecksLabel,
+  summarizeProviderChecks
+} from '../../../shared/provider-check-summary'
+import type { GitLabPipelineJob } from '../../../shared/gitlab-types'
+import type { PRCheckDetail, ProviderCheckSummary } from '../../../shared/types'
+
+function completed(conclusion: string): PRCheckDetail {
+  return {
+    name: conclusion,
+    status: 'completed',
+    conclusion: conclusion as PRCheckDetail['conclusion'],
+    url: null
+  }
+}
+
+function gitLabJobs(...statuses: string[]): PRCheckDetail[] {
+  return gitLabPipelineJobsToPRChecks(
+    statuses.map(
+      (status, index): GitLabPipelineJob => ({
+        id: index,
+        name: status,
+        stage: 'deploy',
+        status,
+        webUrl: '',
+        duration: null
+      })
+    )
+  )
+}
+
+// Why: GraphQL rollups arrive upper-cased and status-first; the main process must land on the
+// same verdict as the renderer for the same checks.
+function toGraphQLRollup(check: PRCheckDetail): { status: string; conclusion: string | null } {
+  return {
+    status: check.status.toUpperCase(),
+    conclusion: check.conclusion ? check.conclusion.toUpperCase() : null
+  }
+}
+
+type ParityExpectation = Omit<ProviderCheckSummary, 'total'>
+
+type ParityCase = {
+  name: string
+  checks: PRCheckDetail[]
+  /** Set when the case also pins the main-process job-array rollup for the same jobs. */
+  gitLabJobStatuses?: string[]
+  /**
+   * The `head_pipeline.status` GitLab reports for this same job set. This is the only GitLab path
+   * with production callers (client.ts passes pipeline objects, never job arrays), so it is the
+   * surface that decides the MR card's tone. Left unset for the shapes where the pipeline string
+   * knowingly disagrees with the job rollup — a `manual`/`skipped`/`canceled` pipeline is grey on
+   * the card but its jobs roll up green/red in the Checks tab. Those are the deferred tone changes
+   * documented in `classifyPipelineString`; pinning them here would just freeze the disagreement.
+   */
+  gitLabPipelineStatus?: string
+  expected: ParityExpectation
+}
+
+function gitLabCase(
+  name: string,
+  statuses: string[],
+  expected: ParityExpectation,
+  pipelineStatus?: string
+): ParityCase {
+  return {
+    name,
+    checks: gitLabJobs(...statuses),
+    gitLabJobStatuses: statuses,
+    ...(pipelineStatus ? { gitLabPipelineStatus: pipelineStatus } : {}),
+    expected
+  }
+}
+
+const PARITY_CASES: ParityCase[] = [
+  {
+    name: 'all success',
+    checks: [completed('success'), completed('success')],
+    expected: { state: 'success', passed: 2, failed: 0, pending: 0, neutral: 0 }
+  },
+  {
+    name: 'success plus skipped',
+    checks: [completed('success'), completed('skipped')],
+    expected: { state: 'success', passed: 2, failed: 0, pending: 0, neutral: 0 }
+  },
+  {
+    name: 'all skipped',
+    checks: [completed('skipped'), completed('skipped')],
+    expected: { state: 'success', passed: 2, failed: 0, pending: 0, neutral: 0 }
+  },
+  {
+    name: 'success plus neutral',
+    checks: [completed('success'), completed('neutral')],
+    expected: { state: 'success', passed: 1, failed: 0, pending: 0, neutral: 1 }
+  },
+  {
+    name: 'all neutral',
+    checks: [completed('neutral')],
+    expected: { state: 'neutral', passed: 0, failed: 0, pending: 0, neutral: 1 }
+  },
+  {
+    name: 'success plus failure',
+    checks: [completed('success'), completed('failure')],
+    expected: { state: 'failure', passed: 1, failed: 1, pending: 0, neutral: 0 }
+  },
+  {
+    name: 'success plus running',
+    checks: [
+      completed('success'),
+      { name: 'ci', status: 'in_progress', conclusion: null, url: null }
+    ],
+    expected: { state: 'pending', passed: 1, failed: 0, pending: 1, neutral: 0 }
+  },
+  gitLabCase('GitLab manual gate only', ['manual'], {
+    state: 'neutral',
+    passed: 0,
+    failed: 0,
+    pending: 0,
+    neutral: 1
+  }),
+  gitLabCase('GitLab manual gate alongside a green pipeline', ['manual', 'success'], {
+    state: 'success',
+    passed: 1,
+    failed: 0,
+    pending: 0,
+    neutral: 1
+  }),
+  gitLabCase('GitLab skipped-only pipeline', ['skipped', 'skipped'], {
+    state: 'success',
+    passed: 2,
+    failed: 0,
+    pending: 0,
+    neutral: 0
+  }),
+  gitLabCase('GitLab success alongside an unrecognized job status', ['success', 'wat'], {
+    state: 'success',
+    passed: 1,
+    failed: 0,
+    pending: 0,
+    neutral: 1
+  }),
+  gitLabCase('GitLab canceled job', ['success', 'canceled'], {
+    state: 'failure',
+    passed: 1,
+    failed: 1,
+    pending: 0,
+    neutral: 0
+  }),
+  gitLabCase(
+    'GitLab manual gate alongside a running job',
+    ['manual', 'running'],
+    { state: 'pending', passed: 0, failed: 0, pending: 1, neutral: 1 },
+    'running'
+  ),
+  {
+    name: 'genuine action_required',
+    checks: [completed('success'), completed('action_required')],
+    expected: { state: 'failure', passed: 1, failed: 1, pending: 0, neutral: 0 }
+  }
+]
+
+describe('provider check classification parity', () => {
+  it.each(PARITY_CASES)(
+    '$name resolves identically on every desktop surface',
+    ({ checks, expected, gitLabJobStatuses, gitLabPipelineStatus }) => {
+      const summary = { ...expected, total: checks.length }
+      expect(summarizeProviderChecks(checks)).toEqual(summary)
+      expect(deriveTaskPagePRCheckSummary(checks)).toEqual(summary)
+      expect(derivePRCheckStatus(checks)).toBe(expected.state)
+      expect(derivePRCheckStatusFromRollup(checks.map(toGraphQLRollup))).toBe(expected.state)
+      if (gitLabJobStatuses) {
+        // Why: the job-array rollup has no production caller today (client.ts only ever passes
+        // pipeline objects) — it is pinned so a future caller cannot inherit a drifted copy.
+        expect(derivePipelineStatus(gitLabJobStatuses.map((status) => ({ status })))).toBe(
+          expected.state
+        )
+      }
+      if (gitLabPipelineStatus) {
+        // Why: this *is* the production GitLab entry point — the MR card and the hosted-review
+        // queue read it, so where it is pinned it must not disagree with the Checks tab for the
+        // same jobs.
+        expect(derivePipelineStatus(gitLabPipelineStatus)).toBe(expected.state)
+        expect(derivePipelineStatus({ status: gitLabPipelineStatus })).toBe(expected.state)
+      }
+      // Why: the pill's label, tone and icon all read this one summary, so a green pill must never say "unresolved".
+      expect(getProviderChecksLabel(summary).includes('Unresolved')).toBe(
+        expected.state === 'neutral'
+      )
+    }
+  )
+
+  it('labels a green PR carrying one neutral check as passing', () => {
+    const checks = [...Array.from({ length: 19 }, () => completed('success')), completed('neutral')]
+    expect(getProviderChecksLabel(summarizeProviderChecks(checks))).toBe('19/20 passed')
+  })
+})
diff --git a/src/renderer/src/components/right-sidebar/checks-panel-content.test.tsx b/src/renderer/src/components/right-sidebar/checks-panel-content.test.tsx
index 1bc4c291821..69fd873c89b 100644
--- a/src/renderer/src/components/right-sidebar/checks-panel-content.test.tsx
+++ b/src/renderer/src/components/right-sidebar/checks-panel-content.test.tsx
@@ -210,6 +210,95 @@ describe('ChecksList', () => {
     expect(markup).not.toContain('opacity-0')
     expect(markup).not.toContain('Open details')
   })
+
+  // Why: the pill above this list already calls skipped checks passing; a "2 passing" header on the
+  // same 2-success/3-skipped PR contradicts its own "5/5 passed" pill.
+  it('counts skipped checks in the passing header, matching the checks pill', () => {
+    const markup = renderToStaticMarkup(
+      React.createElement(
+        TooltipProvider,
+        null,
+        React.createElement(ChecksList, {
+          checks: [
+            { name: 'build', status: 'completed', conclusion: 'success', url: null },
+            { name: 'test', status: 'completed', conclusion: 'success', url: null },
+            { name: 'deploy', status: 'completed', conclusion: 'skipped', url: null },
+            { name: 'docs', status: 'completed', conclusion: 'skipped', url: null },
+            { name: 'e2e', status: 'completed', conclusion: 'skipped', url: null }
+          ],
+          checksLoading: false,
+          checkDetailsContextKey: 'repo:43'
+        })
+      )
+    )
+
+    expect(markup).toContain('5 passing')
+    expect(markup).not.toContain('2 passing')
+  })
+
+  // Why: a completed check with no conclusion will never resolve, so calling it pending kept an
+  // amber spinner next to a grey "Unresolved checks" pill reading the same list.
+  it('reports a completed check with no conclusion as unresolved, not pending', () => {
+    const markup = renderToStaticMarkup(
+      React.createElement(
+        TooltipProvider,
+        null,
+        React.createElement(ChecksList, {
+          checks: [{ name: 'legacy', status: 'completed', conclusion: null, url: null }],
+          checksLoading: false,
+          checkDetailsContextKey: 'repo:44'
+        })
+      )
+    )
+
+    expect(markup).toContain('1 unresolved')
+    expect(markup).not.toContain('1 pending')
+  })
+})
+
+describe('PRTriageStrip check counts', () => {
+  function renderStrip(checks: PRCheckDetail[]): string {
+    return renderToStaticMarkup(
+      React.createElement(PRTriageStrip, {
+        pr: makePR({ mergeable: 'MERGEABLE' }),
+        checks,
+        isResolvingConflictsWithAI: false,
+        onResolveConflictsWithAI: () => {},
+        isFixingChecksWithAI: false,
+        onFixChecksWithAI: () => {}
+      })
+    )
+  }
+
+  // Why: the strip and the checks pill read the same list, so a check that completed without a
+  // verdict must not spin here as pending while the pill calls it unresolved.
+  it('shows a completed check with no conclusion as unresolved instead of pending', () => {
+    const markup = renderStrip([
+      { name: 'legacy', status: 'completed', conclusion: null, url: null }
+    ])
+
+    expect(markup).toContain('1 check unresolved')
+    expect(markup).not.toContain('1 check pending')
+    expect(markup).not.toContain('No blocking PR action')
+  })
+
+  it('still reports a running check as pending', () => {
+    const markup = renderStrip([{ name: 'ci', status: 'in_progress', conclusion: null, url: null }])
+
+    expect(markup).toContain('1 check pending')
+  })
+
+  // Why: one unresolved check must not demote a PR that has a passing one — that is the same
+  // rollup rule the pill uses, so both keep saying the PR is green.
+  it('keeps a passing check green even when another check is unresolved', () => {
+    const markup = renderStrip([
+      { name: 'build', status: 'completed', conclusion: 'success', url: null },
+      { name: 'legacy', status: 'completed', conclusion: 'neutral', url: null }
+    ])
+
+    expect(markup).toContain('No blocking PR action')
+    expect(markup).not.toContain('unresolved')
+  })
 })
 
 describe('isMutablePRConversationComment', () => {
diff --git a/src/renderer/src/components/right-sidebar/checks-panel-content.tsx b/src/renderer/src/components/right-sidebar/checks-panel-content.tsx
index 1d83301ae8e..5084bc27c46 100644
--- a/src/renderer/src/components/right-sidebar/checks-panel-content.tsx
+++ b/src/renderer/src/components/right-sidebar/checks-panel-content.tsx
@@ -100,6 +100,7 @@ import { translate } from '@/i18n/i18n'
 import { useActiveWorktree } from '@/store/selectors'
 import { useAppStore } from '@/store'
 import { sortChecksBySeverity } from '../../../../shared/pr-check-severity-order'
+import { summarizeProviderChecks } from '../../../../shared/provider-check-summary'
 
 export const PullRequestIcon = GitPullRequest
 
@@ -345,10 +346,12 @@ export function PRTriageStrip({
   fixChecksDisabledReason?: string
 }): React.JSX.Element {
   const resolvedReview = review ?? pr
-  const failingCount = checks.filter((check) => isFailedCheck(check)).length
-  const pendingCount = checks.filter(
-    (check) => check.conclusion === 'pending' || check.conclusion === null
-  ).length
+  // Why: the whole strip reads one shared summary so it cannot contradict the checks pill — a
+  // `{status: completed, conclusion: null}` check used to spin here as "1 pending" forever while
+  // the pill two panes away called it unresolved.
+  const summary = summarizeProviderChecks(checks)
+  const failingCount = summary.failed
+  const pendingCount = summary.pending
 
   if (resolvedReview?.mergeable === 'CONFLICTING') {
     return (
@@ -430,6 +433,35 @@ export function PRTriageStrip({
     )
   }
 
+  // Why: nothing passed, failed or is still running — a green tick here would contradict the grey
+  // "Unresolved checks" pill reading the same list.
+  if (summary.state === 'neutral') {
+    return (
+      <div className="border-b border-border px-3 py-2">
+        <div className="flex min-w-0 items-center gap-2">
+          <CircleDashed className="size-3.5 shrink-0 text-muted-foreground" />
+          <div className="min-w-0 flex-1">
+            <div className="truncate text-[11px] font-medium text-foreground">
+              {summary.neutral}{' '}
+              {translate('auto.components.right.sidebar.checks.panel.content.5341023167', 'check')}
+              {summary.neutral === 1 ? '' : 's'}{' '}
+              {translate(
+                'auto.components.right.sidebar.checks.panel.content.checksUnresolvedChip',
+                'unresolved'
+              )}
+            </div>
+            <div className="truncate text-[10px] text-muted-foreground">
+              {translate(
+                'auto.components.right.sidebar.checks.panel.content.checksUnresolvedStripHint',
+                'These checks finished without a pass or fail verdict.'
+              )}
+            </div>
+          </div>
+        </div>
+      </div>
+    )
+  }
+
   return (
     <div className="border-b border-border px-3 py-2">
       <div className="flex min-w-0 items-center gap-2">
@@ -969,11 +1001,15 @@ export function ChecksList({
       })),
     [checkDetailsContextKey, sorted]
   )
-  const passingCount = checks.filter((c) => c.conclusion === 'success').length
-  const failingCount = checks.filter((c) => isFailedCheck(c)).length
-  const pendingCount = checks.filter(
-    (c) => c.conclusion === 'pending' || c.conclusion === null
-  ).length
+  // Why: every header count comes from the same classifier the checks pill uses — counting only
+  // `success` made a 2-success/3-skipped PR say "2 passing" next to "5/5 passed", and treating a
+  // null conclusion as pending kept a completed-but-unresolved check spinning forever.
+  const {
+    passed: passingCount,
+    failed: failingCount,
+    pending: pendingCount,
+    neutral: neutralCount
+  } = summarizeProviderChecks(checks)
 
   useEffect(() => {
     const validKeys = new Set(rows.map((row) => row.key))
@@ -1185,6 +1221,18 @@ export function ChecksList({
               )}
             </span>
           )}
+          {/* Why: without this chip a list of only unresolved checks rendered a header with no
+              counts at all, so nothing said why the pill was grey. */}
+          {neutralCount > 0 && (
+            <span className="flex items-center gap-1">
+              <CircleDashed className="size-3 text-muted-foreground" />
+              {neutralCount}{' '}
+              {translate(
+                'auto.components.right.sidebar.checks.panel.content.checksUnresolvedChip',
+                'unresolved'
+              )}
+            </span>
+          )}
           <span className="flex-1" />
           {checksLoading && <LoaderCircle className="size-3 animate-spin text-muted-foreground" />}
         </button>
@@ -1990,7 +2038,9 @@ function PRCommentGroupView({
     ) : null
   const startReply = onStartReply ? (comment: PRComment) => onStartReply(comment.id) : undefined
   const surfaceClassName = cn(
-    getPRCommentGroupSurfaceClasses(presentation, actionState, { queued: isQueued }),
+    getPRCommentGroupSurfaceClasses(presentation, actionState, {
+      queued: isQueued
+    }),
     group.kind === 'standalone' ? presentation.groupStandalone : presentation.groupThread
   )
   const sharedRowProps = {
diff --git a/src/renderer/src/components/sidebar/worktree-review-helpers.test.tsx b/src/renderer/src/components/sidebar/worktree-review-helpers.test.tsx
index f8e94b8d375..7ca741d4ced 100644
--- a/src/renderer/src/components/sidebar/worktree-review-helpers.test.tsx
+++ b/src/renderer/src/components/sidebar/worktree-review-helpers.test.tsx
@@ -1,6 +1,7 @@
 import { renderToStaticMarkup } from 'react-dom/server'
 import { describe, expect, it } from 'vitest'
 import { ReviewIcon } from './worktree-review-helpers'
+import { derivePipelineStatus } from '../../../../main/gitlab/mappers'
 import type { WorktreeCardPrDisplay } from './worktree-card-pr-display'
 
 const gitlabReview: WorktreeCardPrDisplay = {
@@ -26,4 +27,21 @@ describe('ReviewIcon', () => {
     expect(markup).toContain('viewBox="0 0 16 16"')
     expect(markup).not.toContain('lucide-git-merge')
   })
+
+  // Why: an open MR with no explicit check tone falls through to the emerald "open" colour, so a
+  // GitLab pipeline blocked on a manual gate must not resolve to a tone-less status — the card
+  // would read exactly like a passing pipeline while GitLab still refuses the merge.
+  it('does not paint a manual-blocked GitLab pipeline like a passing one', () => {
+    const status = derivePipelineStatus({ status: 'manual' })
+    const blocked = renderToStaticMarkup(
+      <ReviewIcon review={{ ...gitlabReview, status }} className="size-3" />
+    )
+    const passing = renderToStaticMarkup(
+      <ReviewIcon review={{ ...gitlabReview, status: 'success' }} className="size-3" />
+    )
+
+    expect(blocked).toContain('text-amber-500/85')
+    expect(blocked).not.toContain('text-emerald-500/80')
+    expect(blocked).not.toBe(passing)
+  })
 })
diff --git a/src/renderer/src/components/task-page-checks-pill.test.ts b/src/renderer/src/components/task-page-checks-pill.test.ts
new file mode 100644
index 00000000000..4f54bc6785d
--- /dev/null
+++ b/src/renderer/src/components/task-page-checks-pill.test.ts
@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest'
+import { getChecksLabel, getChecksPillTone } from './task-page-checks-pill'
+
+describe('task page checks pill', () => {
+  // Why: the pill's tone reads `state`, so a label branch keyed off `neutral > 0` painted a green
+  // pill that said "1 unresolved" for a PR the same summary called successful.
+  it('labels a green summary carrying one neutral check as passing', () => {
+    const item = {
+      checksSummary: {
+        state: 'success' as const,
+        total: 2,
+        passed: 1,
+        failed: 0,
+        pending: 0,
+        neutral: 1
+      }
+    }
+
+    expect(getChecksLabel(item)).toBe('1/2 passed')
+    expect(getChecksPillTone(item)).toContain('emerald')
+  })
+
+  it('only says unresolved when nothing passed, failed or is running', () => {
+    const item = {
+      checksSummary: {
+        state: 'neutral' as const,
+        total: 1,
+        passed: 0,
+        failed: 0,
+        pending: 0,
+        neutral: 1
+      }
+    }
+
+    expect(getChecksLabel(item)).toBe('Unresolved checks')
+    expect(getChecksPillTone(item)).toContain('text-muted-foreground')
+  })
+
+  it('falls back while the summary is unknown or empty', () => {
+    expect(getChecksLabel({})).toBe('Checks')
+    expect(
+      getChecksLabel({
+        checksSummary: {
+          state: 'none',
+          total: 0,
+          passed: 0,
+          failed: 0,
+          pending: 0,
+          neutral: 0
+        }
+      })
+    ).toBe('No checks')
+  })
+})
diff --git a/src/renderer/src/components/task-page-checks-pill.ts b/src/renderer/src/components/task-page-checks-pill.ts
new file mode 100644
index 00000000000..ba3252a46f3
--- /dev/null
+++ b/src/renderer/src/components/task-page-checks-pill.ts
@@ -0,0 +1,26 @@
+import { getProviderChecksLabel } from '../../../shared/provider-check-summary'
+import type { ProviderCheckSummary } from '../../../shared/types'
+
+type ChecksPillItem = { checksSummary?: ProviderCheckSummary }
+
+/**
+ * The Tasks-grid checks pill. Label and tone both read the one shared summary so the pill can never
+ * contradict its own colour — a green pill used to read "1 unresolved" whenever neutral > 0.
+ */
+export function getChecksLabel(item: ChecksPillItem): string {
+  return getProviderChecksLabel(item.checksSummary)
+}
+
+export function getChecksPillTone(item: ChecksPillItem): string {
+  const state = item.checksSummary?.state
+  if (state === 'success') {
+    return 'border-emerald-500/30 bg-emerald-500/10 text-emerald-700 dark:text-emerald-200'
+  }
+  if (state === 'failure') {
+    return 'border-rose-500/30 bg-rose-500/10 text-rose-700 dark:text-rose-200'
+  }
+  if (state === 'pending') {
+    return 'border-amber-500/30 bg-amber-500/10 text-amber-700 dark:text-amber-200'
+  }
+  return 'border-border/60 bg-background/70 text-muted-foreground'
+}
diff --git a/src/renderer/src/components/task-page-pr-check-summary.test.ts b/src/renderer/src/components/task-page-pr-check-summary.test.ts
index 2258d89fdbb..ccd63d94c04 100644
--- a/src/renderer/src/components/task-page-pr-check-summary.test.ts
+++ b/src/renderer/src/components/task-page-pr-check-summary.test.ts
@@ -50,7 +50,7 @@ describe('deriveTaskPagePRCheckSummary', () => {
         check({ conclusion: 'skipped' })
       ])
     ).toEqual({
-      state: 'neutral',
+      state: 'success',
       total: 3,
       passed: 2,
       failed: 0,
diff --git a/src/renderer/src/components/task-page-pr-check-summary.ts b/src/renderer/src/components/task-page-pr-check-summary.ts
index b0bc88091ff..c7531040923 100644
--- a/src/renderer/src/components/task-page-pr-check-summary.ts
+++ b/src/renderer/src/components/task-page-pr-check-summary.ts
@@ -1,55 +1,6 @@
+import { summarizeProviderChecks } from '../../../shared/provider-check-summary'
 import type { PRCheckDetail, ProviderCheckSummary } from '../../../shared/types'
 
-function getCheckConclusion(check: PRCheckDetail): NonNullable<PRCheckDetail['conclusion']> {
-  return check.conclusion ?? 'pending'
-}
-
-function isPendingCheck(check: PRCheckDetail): boolean {
-  return (
-    check.status === 'queued' ||
-    check.status === 'in_progress' ||
-    getCheckConclusion(check) === 'pending'
-  )
-}
-
 export function deriveTaskPagePRCheckSummary(checks: PRCheckDetail[]): ProviderCheckSummary {
-  if (checks.length === 0) {
-    return { state: 'none', total: 0, passed: 0, failed: 0, pending: 0, neutral: 0 }
-  }
-
-  let passed = 0
-  let failed = 0
-  let pending = 0
-  let neutral = 0
-
-  for (const check of checks) {
-    const conclusion = getCheckConclusion(check)
-    if (conclusion === 'success' || conclusion === 'skipped') {
-      passed += 1
-    } else if (conclusion === 'neutral') {
-      neutral += 1
-    } else if (
-      conclusion === 'failure' ||
-      conclusion === 'timed_out' ||
-      conclusion === 'cancelled' ||
-      // Why: action_required (e.g. a workflow awaiting approval) blocks merge; it
-      // must count as failed so the summary never reads "passing" while blocked.
-      conclusion === 'action_required'
-    ) {
-      failed += 1
-    } else if (isPendingCheck(check)) {
-      pending += 1
-    } else {
-      neutral += 1
-    }
-  }
-
-  return {
-    state: failed > 0 ? 'failure' : pending > 0 ? 'pending' : neutral > 0 ? 'neutral' : 'success',
-    total: checks.length,
-    passed,
-    failed,
-    pending,
-    neutral
-  }
+  return summarizeProviderChecks(checks)
 }
diff --git a/src/renderer/src/i18n/locales/en.json b/src/renderer/src/i18n/locales/en.json
index b38e6915083..7283f862c91 100644
--- a/src/renderer/src/i18n/locales/en.json
+++ b/src/renderer/src/i18n/locales/en.json
@@ -10680,6 +10680,8 @@
                 "9ad98f2a17": "pending",
                 "5e52f4ef7f": "failing",
                 "02ca4f9074": "passing",
+                "checksUnresolvedChip": "unresolved",
+                "checksUnresolvedStripHint": "These checks finished without a pass or fail verdict.",
                 "e15a8b77ef": "No inline details are available for this check.",
                 "679bf2093c": "Copy log excerpt",
                 "d713f500b2": "Log excerpt",
diff --git a/src/shared/gitlab-pipeline-checks.test.ts b/src/shared/gitlab-pipeline-checks.test.ts
index 48faafc38e0..673fcf3cd16 100644
--- a/src/shared/gitlab-pipeline-checks.test.ts
+++ b/src/shared/gitlab-pipeline-checks.test.ts
@@ -49,7 +49,7 @@ describe('gitLabPipelineJobsToPRChecks', () => {
       {
         name: 'deploy: deploy',
         status: 'completed',
-        conclusion: 'action_required',
+        conclusion: 'neutral',
         url: null
       },
       {
diff --git a/src/shared/gitlab-pipeline-checks.ts b/src/shared/gitlab-pipeline-checks.ts
index a988967fa32..f993be157a3 100644
--- a/src/shared/gitlab-pipeline-checks.ts
+++ b/src/shared/gitlab-pipeline-checks.ts
@@ -35,7 +35,12 @@ export function mapGitLabPipelineJobStatusToConclusion(
   if (s === 'skipped') {
     return 'skipped'
   }
-  if (s === 'manual' || s === 'action_required') {
+  // Why: manual GitLab jobs are intentionally waiting for a human trigger; calling them pending
+  // would make the Checks tab look stuck forever, and action_required flags green MRs as failing.
+  if (s === 'manual') {
+    return 'neutral'
+  }
+  if (s === 'action_required') {
     return 'action_required'
   }
   if (
diff --git a/src/shared/pr-check-severity-order.test.ts b/src/shared/pr-check-severity-order.test.ts
index 126ab012723..685886513aa 100644
--- a/src/shared/pr-check-severity-order.test.ts
+++ b/src/shared/pr-check-severity-order.test.ts
@@ -116,10 +116,11 @@ describe('PR check severity order', () => {
       check('pass-b', 'success')
     ]
 
+    // A manual GitLab gate is neutral, so it sinks below the passing checks a reviewer reads first.
     expect(sortChecksBySeverity(checks).map((item) => item.name)).toEqual([
-      'manual',
       'pass-a',
       'pass-b',
+      'manual',
       'future'
     ])
   })
diff --git a/src/shared/pr-check-status.ts b/src/shared/pr-check-status.ts
index 2f8e68e1546..b2127671d1a 100644
--- a/src/shared/pr-check-status.ts
+++ b/src/shared/pr-check-status.ts
@@ -1,38 +1,11 @@
+import { summarizeProviderChecks } from './provider-check-summary'
 import type { CheckStatus, PRCheckDetail } from './types'
 
 /** Derives the review status from the normalized check contract. */
 export function derivePRCheckStatus(checks: readonly PRCheckDetail[]): CheckStatus {
-  if (checks.length === 0) {
-    return 'neutral'
-  }
-
-  let hasPending = false
-  let hasSuccess = false
-  for (const check of checks) {
-    if (
-      check.conclusion === 'failure' ||
-      check.conclusion === 'timed_out' ||
-      check.conclusion === 'cancelled' ||
-      check.conclusion === 'action_required'
-    ) {
-      return 'failure'
-    }
-    if (
-      check.status === 'queued' ||
-      check.status === 'in_progress' ||
-      check.conclusion === 'pending'
-    ) {
-      hasPending = true
-    }
-    if (check.conclusion === 'success') {
-      hasSuccess = true
-    }
-  }
-
-  if (hasPending) {
-    return 'pending'
-  }
-  return hasSuccess ? 'success' : 'neutral'
+  const { state } = summarizeProviderChecks(checks)
+  // Why: CheckStatus has no 'none'; an empty rollup carries the same "nothing to report" meaning.
+  return state === 'none' ? 'neutral' : state
 }
 
 type RawCheckRollup = { status?: unknown; conclusion?: unknown; state?: unknown }
diff --git a/src/shared/provider-check-summary.ts b/src/shared/provider-check-summary.ts
new file mode 100644
index 00000000000..a3fe8813458
--- /dev/null
+++ b/src/shared/provider-check-summary.ts
@@ -0,0 +1,101 @@
+import type { ProviderCheckSummary } from './types'
+
+export type CheckOutcome = 'passed' | 'failed' | 'pending' | 'neutral'
+
+export type CheckOutcomeInput = { status?: string | null; conclusion?: string | null }
+
+// Why: a skipped job is a deliberate "not applicable", not an unresolved signal — every surface
+// must count it as passing or the same PR reads green on desktop and grey on mobile.
+const PASSED_CONCLUSIONS = new Set(['success', 'skipped'])
+
+// Why: these block the merge. GitLab `manual` is deliberately absent — it waits on a human.
+const FAILED_CONCLUSIONS = new Set([
+  'failure',
+  'error',
+  'startup_failure',
+  'timed_out',
+  'cancelled',
+  'action_required'
+])
+
+/** The single provider-neutral verdict for one check; every check surface must route through it. */
+export function classifyCheckOutcome(check: CheckOutcomeInput): CheckOutcome {
+  const conclusion = (check.conclusion ?? '').toLowerCase()
+  const status = (check.status ?? '').toLowerCase()
+  if (FAILED_CONCLUSIONS.has(conclusion)) {
+    return 'failed'
+  }
+  if (PASSED_CONCLUSIONS.has(conclusion)) {
+    return 'passed'
+  }
+  // Why: anything that has not reached a terminal status is still running, whatever it calls itself.
+  if (conclusion === 'pending' || status !== 'completed') {
+    return 'pending'
+  }
+  return 'neutral'
+}
+
+/** Rolls up counted outcomes; passing checks win over neutral ones so one neutral cannot demote a green PR. */
+export function resolveProviderCheckState(
+  counts: Pick<ProviderCheckSummary, 'total' | 'passed' | 'failed' | 'pending'>
+): ProviderCheckSummary['state'] {
+  if (counts.total === 0) {
+    return 'none'
+  }
+  if (counts.failed > 0) {
+    return 'failure'
+  }
+  if (counts.pending > 0) {
+    return 'pending'
+  }
+  return counts.passed > 0 ? 'success' : 'neutral'
+}
+
+export function summarizeProviderChecks(
+  checks: readonly CheckOutcomeInput[]
+): ProviderCheckSummary {
+  let passed = 0
+  let failed = 0
+  let pending = 0
+  let neutral = 0
+  for (const check of checks) {
+    const outcome = classifyCheckOutcome(check)
+    if (outcome === 'passed') {
+      passed += 1
+    } else if (outcome === 'failed') {
+      failed += 1
+    } else if (outcome === 'pending') {
+      pending += 1
+    } else {
+      neutral += 1
+    }
+  }
+  const total = checks.length
+  return {
+    state: resolveProviderCheckState({ total, passed, failed, pending }),
+    total,
+    passed,
+    failed,
+    pending,
+    neutral
+  }
+}
+
+/** The one checks-pill label; it keys off `state` so the text can never contradict the pill's tone or icon. */
+export function getProviderChecksLabel(summary: ProviderCheckSummary | undefined): string {
+  if (!summary) {
+    return 'Checks'
+  }
+  if (summary.total === 0) {
+    return 'No checks'
+  }
+  if (summary.failed > 0) {
+    return `${summary.failed} failing`
+  }
+  if (summary.pending > 0) {
+    return `${summary.pending} pending`
+  }
+  return summary.state === 'neutral'
+    ? 'Unresolved checks'
+    : `${summary.passed}/${summary.total} passed`
+}

From 651f707ce08bf0fb18961add08d835612098e762 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Fri, 31 Jul 2026 05:01:20 -0700
Subject: [PATCH 18/23] [P1] fix(mobile): restore pairing self-heal and recover
 a wedged handshake (#11690)

* fix(mobile): restore pairing self-heal and recover a wedged handshake

readPairingKeychainItem threw when an Android presence record pointed at a
SecureStore entry that read back null. Android reports absent and undecryptable
identically, so the keystore fault the presence record was added to survive
latched every caller out of its own orphan cleanup: the pairing journal store
never reached its null-secret branch, stale winner-stamped metadata survived,
and every later QR scan failed with "mobile relay pairing recovery pending".
Report absent instead and drop the stale presence claim, still without falling
back to the superseded older generation.

The handshake-timeout path closed the socket with no handleSocketClosed
fallback, unlike the connect-timeout and activity-probe paths. When React
Native omits onclose for a wedged transport the client stayed in 'handshaking'
forever with no reconnect armed.

* fix(mobile): keep the presence pin when a recorded keychain item reads null

Clearing the presence record on the self-heal removed the only thing that
stops readPairingKeychainItem's generation walk, so the next read fell back to
the superseded value under an older generation -- exactly what #11430's
presence record exists to prevent, and reachable for host device tokens and
relay resume bundles after an Android encrypt rotation. Return null and leave
the record in place; the null return alone unlatches every caller's orphan
cleanup, and delete/re-pair already clear or re-stamp the record.

Co-authored-by: Orca <help@stably.ai>

* fix(mobile): date synthesized socket closes in transport diagnostics

Move the log-only close clocks behind handleSocketClosed's stale guard so a
synthesized close records them and a late onclose can't clobber the replacement.

Co-authored-by: Orca <help@stably.ai>

* fix(mobile): account for delayed synthesized closes

---------

Co-authored-by: Orca <help@stably.ai>
---
 .../cellular-connecting-label-stall.test.ts   |  42 +++-
 ...mobile-relay-pairing-journal-store.test.ts |  42 ++++
 mobile/src/transport/pairing-keychain.test.ts |  16 +-
 mobile/src/transport/pairing-keychain.ts      |   7 +-
 ...ient-synthesized-close-diagnostics.test.ts | 221 ++++++++++++++++++
 mobile/src/transport/rpc-client.ts            | 116 ++++-----
 .../transport/rpc-socket-close-evidence.ts    |  70 ++++++
 mobile/src/transport/socket-event-debug.ts    |   8 +
 8 files changed, 460 insertions(+), 62 deletions(-)
 create mode 100644 mobile/src/transport/rpc-client-synthesized-close-diagnostics.test.ts
 create mode 100644 mobile/src/transport/rpc-socket-close-evidence.ts

diff --git a/mobile/src/transport/cellular-connecting-label-stall.test.ts b/mobile/src/transport/cellular-connecting-label-stall.test.ts
index e7bc6731462..e9a46d3b406 100644
--- a/mobile/src/transport/cellular-connecting-label-stall.test.ts
+++ b/mobile/src/transport/cellular-connecting-label-stall.test.ts
@@ -31,6 +31,9 @@ type CarrierBehavior =
   // Endpoint is healthy but its e2ee_ready lands after readyAfterMs, which a
   // high-latency / lossy cellular link readily pushes past the 5s budget.
   | { kind: 'slow-handshake'; readyAfterMs: number }
+  // Upgrade completes, nothing is ever answered, and the native socket is already
+  // half-open, so RN never delivers a close event for the client's own close().
+  | { kind: 'wedged-open-then-silent' }
 
 let carrier: CarrierBehavior = { kind: 'blackhole' }
 const sockets: CarrierWebSocket[] = []
@@ -54,7 +57,11 @@ class CarrierWebSocket {
       setTimeout(() => this.fail(), 1)
       return
     }
-    if (carrier.kind === 'open-then-silent' || carrier.kind === 'slow-handshake') {
+    if (
+      carrier.kind === 'open-then-silent' ||
+      carrier.kind === 'slow-handshake' ||
+      carrier.kind === 'wedged-open-then-silent'
+    ) {
       setTimeout(() => {
         this.readyState = 1
         this.onopen?.()
@@ -88,6 +95,10 @@ class CarrierWebSocket {
     if (this.readyState === 3) {
       return
     }
+    if (carrier.kind === 'wedged-open-then-silent') {
+      this.readyState = 3
+      return
+    }
     this.fail()
   }
 
@@ -235,6 +246,35 @@ describe('issue #10119 — what a phone shows while it cannot reach the desktop'
     client.close()
   })
 
+  it('redials after a handshake timeout the wedged transport never reports as closed', () => {
+    carrier = { kind: 'wedged-open-then-silent' }
+    const client = connect('ws://192.168.0.56:6769', 'device-token', 'server-public-key')
+
+    // 200ms upgrade plus the 5s handshake budget, still inside the reconnect delay.
+    vi.advanceTimersByTime(5_400)
+
+    // Without the onclose fallback nothing else leaves 'handshaking': no reconnect
+    // timer is armed, the activity probe bails, and foregrounding is a no-op.
+    expect(sockets).toHaveLength(1)
+    expect(client.getState()).toBe('reconnecting')
+
+    vi.advanceTimersByTime(1_000)
+    expect(sockets).toHaveLength(2)
+
+    client.close()
+  })
+
+  it('escalates past "Connecting…" while every wedged dial swallows its close event', () => {
+    carrier = { kind: 'wedged-open-then-silent' }
+    const samples = observe('ws://192.168.0.56:6769', 900_000)
+
+    expect(Math.max(...samples.map((s) => s.attempts))).toBeGreaterThanOrEqual(12)
+    expect(samples.some((s) => s.label === "Can't reach desktop")).toBe(true)
+
+    const after = labelsAfterFirstEscalation(samples)
+    expect(after.every((s) => s.label !== 'Connecting…')).toBe(true)
+  })
+
   it('contrast: an endpoint that RSTs escalates the same way', () => {
     carrier = { kind: 'refused' }
     const samples = observe('ws://192.168.0.56:6769', 60_000)
diff --git a/mobile/src/transport/mobile-relay-pairing-journal-store.test.ts b/mobile/src/transport/mobile-relay-pairing-journal-store.test.ts
index cf249a90506..2169d360b8f 100644
--- a/mobile/src/transport/mobile-relay-pairing-journal-store.test.ts
+++ b/mobile/src/transport/mobile-relay-pairing-journal-store.test.ts
@@ -339,6 +339,48 @@ describe('mobile relay pairing journal store', () => {
     await expect(loadMobileRelayPairingJournal()).resolves.toEqual(journal)
   })
 
+  it('self-heals an undecryptable Android secret so the next QR scan can pair', async () => {
+    platform.OS = 'android'
+    const created = createMobileRelayPairingJournal({
+      offer: offer as PairingOffer & { relay: NonNullable<PairingOffer['relay']> },
+      hostId: 'host-1',
+      hostName: 'Blue Whale',
+      randomBytes: (length) => new Uint8Array(length).fill(13)
+    })
+    // Why: the candidate race stamps winner/authorizationMode long before pairing completes.
+    const journal = {
+      ...created,
+      metadata: {
+        ...created.metadata,
+        winner: 'relay' as const,
+        authorizationMode: 'relay-basis' as const
+      }
+    }
+    await saveMobileRelayPairingJournal(journal)
+    expect(presenceRaw).toBe('0')
+
+    // Why: Android SecureStore reports an undecryptable keystore entry as null (#6600).
+    secretRaw = null
+
+    await expect(loadMobileRelayPairingJournal()).resolves.toBeNull()
+    expect(metadataRaw).toBeNull()
+    // Why: the presence record must outlive the self-heal so reads stay absent instead of
+    // walking back to an older generation; the metadata-less load sweeps it next.
+    expect(presenceRaw).toBe('0')
+
+    await expect(loadMobileRelayPairingJournal()).resolves.toBeNull()
+    expect(presenceRaw).toBeNull()
+
+    const rescan = createMobileRelayPairingJournal({
+      offer: offer as PairingOffer & { relay: NonNullable<PairingOffer['relay']> },
+      hostId: 'host-2',
+      hostName: 'Red Panda',
+      randomBytes: (length) => new Uint8Array(length).fill(14)
+    })
+    await expect(saveMobileRelayPairingJournal(rescan)).resolves.toBeUndefined()
+    await expect(loadMobileRelayPairingJournal()).resolves.toEqual(rescan)
+  })
+
   it('clears metadata before deleting its secret and keeps relay unavailable on web', async () => {
     const journal = createMobileRelayPairingJournal({
       offer: offer as PairingOffer & { relay: NonNullable<PairingOffer['relay']> },
diff --git a/mobile/src/transport/pairing-keychain.test.ts b/mobile/src/transport/pairing-keychain.test.ts
index fda46d0a328..0ef80ca889c 100644
--- a/mobile/src/transport/pairing-keychain.test.ts
+++ b/mobile/src/transport/pairing-keychain.test.ts
@@ -246,7 +246,7 @@ describe('pairing keychain', () => {
     expect(secureStoreMock.getItemAsync).toHaveBeenCalledTimes(1)
   })
 
-  it('does not return a stale older value when a recorded current item decrypts as null', async () => {
+  it('self-heals to absent, never a stale older value, when a recorded item decrypts as null', async () => {
     generationRecord = '1'
     let presenceRecord: string | null = null
     asyncStorageMock.getItem.mockImplementation(async (key: string) => {
@@ -263,6 +263,11 @@ describe('pairing keychain', () => {
         presenceRecord = raw
       }
     })
+    asyncStorageMock.removeItem.mockImplementation(async (key: string) => {
+      if (key === TOKEN_PRESENCE_KEY) {
+        presenceRecord = null
+      }
+    })
 
     await writePairingKeychainItem(TOKEN_KEY, 'rotated-token')
     expect(presenceRecord).toBe('1')
@@ -275,8 +280,15 @@ describe('pairing keychain', () => {
       serviceOf(options) === undefined ? 'legacy-token' : null
     )
 
-    await expect(readPairingKeychainItem(TOKEN_KEY)).rejects.toThrow(/recorded generation/)
+    // Why: Android cannot distinguish absent from undecryptable, and a throw here left every
+    // caller's orphan cleanup unreachable; absent is the only self-healing answer.
+    await expect(readPairingKeychainItem(TOKEN_KEY)).resolves.toBeNull()
     expect(secureStoreMock.getItemAsync).toHaveBeenCalledTimes(1)
+
+    // Why: clearing the presence record would let the next read walk back to 'legacy-token'.
+    expect(presenceRecord).toBe('1')
+    await expect(readPairingKeychainItem(TOKEN_KEY)).resolves.toBeNull()
+    expect(secureStoreMock.getItemAsync).toHaveBeenCalledTimes(2)
   })
 
   it('reads an older value while a newly recorded alias has no item yet', async () => {
diff --git a/mobile/src/transport/pairing-keychain.ts b/mobile/src/transport/pairing-keychain.ts
index bf3b1810807..078d5614981 100644
--- a/mobile/src/transport/pairing-keychain.ts
+++ b/mobile/src/transport/pairing-keychain.ts
@@ -162,7 +162,12 @@ export async function readPairingKeychainItem(key: string): Promise<string | nul
   if (presenceGeneration !== null) {
     const value = await SecureStore.getItemAsync(key, optionsForGeneration(presenceGeneration))
     if (value === null) {
-      throw new Error('pairing keychain item is unavailable at its recorded generation')
+      // Why: Android reports an undecryptable entry as null, so failing closed here latched
+      // callers out of their own orphan cleanup forever; report absent instead. The presence
+      // record must survive — it is the only thing that keeps a later read from resurrecting
+      // the superseded value under an older generation. Callers clear it via delete or a
+      // re-pair write, so a legitimately-current older value is traded for re-pairing.
+      return null
     }
     return value
   }
diff --git a/mobile/src/transport/rpc-client-synthesized-close-diagnostics.test.ts b/mobile/src/transport/rpc-client-synthesized-close-diagnostics.test.ts
new file mode 100644
index 00000000000..832180ad6c1
--- /dev/null
+++ b/mobile/src/transport/rpc-client-synthesized-close-diagnostics.test.ts
@@ -0,0 +1,221 @@
+// Why: RN can swallow onclose for a wedged iOS transport, so the client synthesizes the close.
+// These cover the diagnostic clocks that synthesis has to keep honest, and prove synthesis
+// never costs us the auth-failed latch when the real close lands late.
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { connect } from './rpc-client'
+
+vi.mock('./e2ee', () => ({
+  generateKeyPair: () => ({
+    publicKey: new Uint8Array(32),
+    secretKey: new Uint8Array(32)
+  }),
+  deriveSharedKey: () => new Uint8Array(32),
+  publicKeyFromBase64: () => new Uint8Array(32),
+  publicKeyToBase64: () => 'client-public-key',
+  encrypt: (plaintext: string) => `encrypted:${plaintext}`,
+  decrypt: (raw: string) => raw.replace(/^encrypted:/, ''),
+  decryptBytes: (bytes: Uint8Array) => bytes
+}))
+
+// Why: close() deliberately never fires onclose — that is the wedged-transport bug being modelled.
+class WedgedWebSocket {
+  static CONNECTING = 0
+  static OPEN = 1
+  static CLOSING = 2
+  static CLOSED = 3
+
+  readonly CONNECTING = WedgedWebSocket.CONNECTING
+  readonly OPEN = WedgedWebSocket.OPEN
+  readonly CLOSING = WedgedWebSocket.CLOSING
+  readonly CLOSED = WedgedWebSocket.CLOSED
+
+  readyState = WedgedWebSocket.CONNECTING
+  onopen: (() => void) | null = null
+  onclose: ((event?: { code?: number; reason?: string; wasClean?: boolean }) => void) | null = null
+  onmessage: ((event: { data: unknown }) => void) | null = null
+  onerror: (() => void) | null = null
+  sent: string[] = []
+  close = vi.fn(() => {
+    this.readyState = WedgedWebSocket.CLOSED
+  })
+
+  constructor(readonly endpoint: string) {
+    sockets.push(this)
+  }
+
+  send(payload: string): void {
+    this.sent.push(payload)
+  }
+
+  open(): void {
+    this.readyState = WedgedWebSocket.OPEN
+    this.onopen?.()
+  }
+
+  receive(payload: unknown): void {
+    this.onmessage?.({ data: payload })
+  }
+
+  // Why: the close event the native layer eventually coughs up, possibly long after we gave up.
+  deliverClose(code: number, reason = ''): void {
+    this.readyState = WedgedWebSocket.CLOSED
+    this.onclose?.({ code, reason, wasClean: true })
+  }
+}
+
+const sockets: WedgedWebSocket[] = []
+const originalWebSocket = globalThis.WebSocket
+
+function lastSocket(): WedgedWebSocket {
+  return sockets[sockets.length - 1]!
+}
+
+function openConnectionLogs(spy: ReturnType<typeof vi.spyOn>): Record<string, unknown>[] {
+  return spy.mock.calls
+    .filter((call) => call[0] === '[net] openConnection')
+    .map((call) => call[1] as Record<string, unknown>)
+}
+
+describe('synthesized close diagnostics', () => {
+  let logSpy: ReturnType<typeof vi.spyOn>
+
+  beforeEach(() => {
+    vi.useFakeTimers()
+    sockets.length = 0
+    globalThis.WebSocket = WedgedWebSocket as unknown as typeof WebSocket
+    logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+  })
+
+  afterEach(() => {
+    logSpy.mockRestore()
+    vi.useRealTimers()
+    globalThis.WebSocket = originalWebSocket
+  })
+
+  it('records the close clock when a handshake timeout synthesizes the close', async () => {
+    const client = connect('ws://desktop.invalid', 'token', 'server-key')
+    lastSocket().open()
+
+    // 5s handshake budget elapses with no e2ee_ready — the client closes and synthesizes onclose.
+    await vi.advanceTimersByTimeAsync(5_000)
+    expect(client.getState()).toBe('reconnecting')
+
+    // 500ms is the first reconnect delay; the redial log must date the close it just made.
+    await vi.advanceTimersByTimeAsync(500)
+    expect(sockets).toHaveLength(2)
+
+    const redial = openConnectionLogs(logSpy)[1]
+    expect(redial?.msSinceLastClose).toBe(500)
+
+    client.close()
+  })
+
+  it('keeps the replacement socket clock when the swallowed close arrives late', async () => {
+    const client = connect('ws://desktop.invalid', 'token', 'server-key')
+    const wedged = lastSocket()
+    wedged.open()
+
+    await vi.advanceTimersByTimeAsync(100)
+    wedged.receive(JSON.stringify({ type: 'e2ee_ready' }))
+    await vi.advanceTimersByTimeAsync(4_900)
+    await vi.advanceTimersByTimeAsync(500)
+    expect(sockets).toHaveLength(2)
+    const replacement = lastSocket()
+    replacement.open()
+    replacement.receive(JSON.stringify({ type: 'e2ee_ready' }))
+    replacement.receive('encrypted:{"type":"e2ee_authenticated"}')
+
+    // The native layer finally reports the dead socket's close, 200ms into the replacement's life.
+    await vi.advanceTimersByTimeAsync(200)
+    wedged.deliverClose(1006)
+    const staleCloseLog = logSpy.mock.calls.findLast(
+      (call) => call[0] === '[net] ws.onclose'
+    )?.[1] as Record<string, unknown> | undefined
+    expect(staleCloseLog?.constructToCloseMs).toBe(5_700)
+    expect(staleCloseLog?.aliveMs).toBeNull()
+    expect(staleCloseLog?.inboundIdleMs).toBe(5_600)
+
+    // The replacement's own close must still be able to date itself against its open.
+    await vi.advanceTimersByTimeAsync(300)
+    lastSocket().deliverClose(1006)
+    const closeLog = logSpy.mock.calls.findLast((call) => call[0] === '[net] ws.onclose')?.[1] as
+      | Record<string, unknown>
+      | undefined
+    expect(closeLog?.constructToCloseMs).toBe(500)
+    expect(closeLog?.aliveMs).toBe(500)
+    expect(closeLog?.inboundIdleMs).toBe(500)
+
+    client.close()
+  })
+
+  it('still latches auth-failed when a real 4001 lands after a synthesized close', async () => {
+    const client = connect('ws://desktop.invalid', 'token', 'server-key')
+    const wedged = lastSocket()
+    wedged.open()
+    await vi.advanceTimersByTimeAsync(5_000)
+    expect(client.getState()).toBe('reconnecting')
+    await vi.advanceTimersByTimeAsync(500)
+    const replacement = lastSocket()
+
+    // The rejection counts, but stale cleanup must not disturb the replacement or its timer path.
+    wedged.deliverClose(4001, 'Unauthorized')
+    expect(lastSocket()).toBe(replacement)
+    expect(replacement.close).not.toHaveBeenCalled()
+    await vi.advanceTimersByTimeAsync(1_000)
+    expect(sockets).toHaveLength(2)
+    expect(lastSocket()).toBe(replacement)
+    expect(client.getState()).toBe('connecting')
+
+    for (let rejection = 0; rejection < 2; rejection += 1) {
+      const socket = lastSocket()
+      socket.open()
+      socket.receive(JSON.stringify({ type: 'e2ee_ready' }))
+      socket.deliverClose(4001, 'Unauthorized')
+      if (rejection === 0) {
+        await vi.advanceTimersByTimeAsync(2_500)
+      }
+    }
+
+    expect(client.getState()).toBe('auth-failed')
+    expect(sockets).toHaveLength(3)
+
+    // A latched client must stay latched and stop redialling.
+    const dialCount = sockets.length
+    await vi.advanceTimersByTimeAsync(10 * 60_000)
+    expect(sockets).toHaveLength(dialCount)
+    expect(client.getState()).toBe('auth-failed')
+
+    client.close()
+  })
+
+  it('ignores a stale 4001 after the replacement authenticates', async () => {
+    const client = connect('ws://desktop.invalid', 'token', 'server-key')
+    const wedged = lastSocket()
+    wedged.open()
+    await vi.advanceTimersByTimeAsync(5_500)
+
+    const replacement = lastSocket()
+    replacement.open()
+    replacement.receive(JSON.stringify({ type: 'e2ee_ready' }))
+    replacement.receive('encrypted:{"type":"e2ee_authenticated"}')
+    expect(client.getState()).toBe('connected')
+
+    wedged.deliverClose(4001, 'Unauthorized')
+    expect(client.getState()).toBe('connected')
+    expect(replacement.close).not.toHaveBeenCalled()
+
+    for (let rejection = 0; rejection < 2; rejection += 1) {
+      const socket = lastSocket()
+      socket.deliverClose(4001, 'Unauthorized')
+      expect(client.getState()).toBe('reconnecting')
+      await vi.advanceTimersByTimeAsync(rejection === 0 ? 500 : 1_000)
+      lastSocket().open()
+      lastSocket().receive(JSON.stringify({ type: 'e2ee_ready' }))
+    }
+
+    lastSocket().deliverClose(4001, 'Unauthorized')
+    expect(client.getState()).toBe('auth-failed')
+
+    client.close()
+  })
+})
diff --git a/mobile/src/transport/rpc-client.ts b/mobile/src/transport/rpc-client.ts
index 9aebcc28db4..3cdc612afb9 100644
--- a/mobile/src/transport/rpc-client.ts
+++ b/mobile/src/transport/rpc-client.ts
@@ -27,7 +27,12 @@ import {
   buildTerminalUnsubscribeParams,
   updateTerminalSubscriptionViewport as updateCachedTerminalSubscriptionViewport
 } from './rpc-client-terminal-subscription'
-import { describeSocketEvent } from './socket-event-debug'
+import { describeSocketEvent, redactSocketEndpoint } from './socket-event-debug'
+import {
+  isStaleRpcSocketEvent,
+  logRpcSocketClose,
+  RpcSynthesizedCloseIndex
+} from './rpc-socket-close-evidence'
 import { markRpcDeliveryUnknown } from './rpc-delivery-ambiguity'
 import { openRpcRequestBudget, resolvePostConnectRequestTimeout } from './rpc-request-budget'
 import { isRpcResponse } from './rpc-response-shape'
@@ -157,6 +162,7 @@ export function connect(
     })
   }
   let ws: WebSocket | null = null
+  const synthesizedCloses = new RpcSynthesizedCloseIndex()
   let state: ConnectionState = 'disconnected'
   let requestCounter = 0
   let reconnectAttempt = 0
@@ -168,13 +174,13 @@ export function connect(
   let intentionallyClosed = false
   // Consecutive auth rejections; tolerate up to AUTH_RETRY_BUDGET (issue #5200) before latching to avoid a needless re-pair.
   let authRejectionCount = 0
+  let authenticationGeneration = 0
   let lastConnectedAt: number | null = null
   // Why: cheap diagnostics for RN/OkHttp process-state poisoning (retry cadence, inbound traffic, close timing).
   let lastInboundAt: number | null = null
   let inboundSequence = 0
   let lastWsClosedAt: number | null = null
   let wsConstructionCounter = 0
-  let currentWsOpenedAt: number | null = null
 
   // Why: fresh ephemeral keypair per connection provides forward secrecy.
   let sharedKey: Uint8Array | null = null
@@ -220,10 +226,11 @@ export function connect(
       to: next,
       dweltMs: dwelt,
       attempt: reconnectAttempt,
-      endpoint: redactedEndpoint(endpoint)
+      endpoint: redactSocketEndpoint(endpoint)
     })
     if (next === 'connected') {
       lastConnectedAt = Date.now()
+      authenticationGeneration++
       // Why: only a completed E2EE handshake proves the path is healthy (issue #10119).
       reconnectAttempt = 0
       // Why: a clean handshake proves the token is valid — reset the auth retry budget.
@@ -244,15 +251,6 @@ export function connect(
     }
   }
 
-  // Why: keep device tokens / full URLs out of log scrolls — truncate to host:port.
-  function redactedEndpoint(ep: string): string {
-    try {
-      return new URL(ep).host || 'unknown'
-    } catch {
-      return 'unknown'
-    }
-  }
-
   function waitForConnected(timeoutMs?: number): Promise<void> {
     if (state === 'connected') {
       return Promise.resolve()
@@ -296,7 +294,7 @@ export function connect(
     wsConstructionCounter++
     console.log('[net] openConnection', {
       attempt: reconnectAttempt,
-      endpoint: redactedEndpoint(endpoint),
+      endpoint: redactSocketEndpoint(endpoint),
       // Why: diagnostic for RN/OkHttp pool corruption — high wsCount + repeated 1006 closes means process-state stuck.
       wsCount: wsConstructionCounter,
       msSinceLastConnected: lastConnectedAt != null ? now - lastConnectedAt : null,
@@ -306,27 +304,16 @@ export function connect(
     setState('connecting')
     sharedKey = null
 
-    currentWsOpenedAt = now
     emitLog(
       'info',
       reconnectAttempt > 0 ? `Reconnecting (attempt ${reconnectAttempt + 1})` : 'Opening WebSocket',
-      redactedEndpoint(endpoint)
+      redactSocketEndpoint(endpoint)
     )
 
     ws = new WebSocket(endpoint)
     const openingWs = ws
-    const ignoreStaleSocketEvent = (eventName: string): boolean => {
-      if (ws === openingWs) {
-        return false
-      }
-      // Why: RN can deliver callbacks from a timed-out socket after reconnect swapped in a replacement — ignore them.
-      console.log('[net] stale ws event ignored', {
-        eventName,
-        state,
-        attempt: reconnectAttempt
-      })
-      return true
-    }
+    let openingWsAuthenticated = false
+    let openingWsLastInboundAt: number | null = null
 
     // Why: RN can leave opens pending forever on flaky handoffs — force reconnect if onopen never arrives.
     connectTimer = setTimeout(() => {
@@ -343,13 +330,14 @@ export function connect(
         )
         openingWs.close()
         if (ws === openingWs) {
+          synthesizedCloses.remember(openingWs, authenticationGeneration)
           handleSocketClosed(openingWs, { timedOut: true })
         }
       }
     }, CONNECT_TIMEOUT_MS)
 
     ws.onopen = () => {
-      if (ignoreStaleSocketEvent('open')) {
+      if (isStaleRpcSocketEvent(ws, openingWs, 'open', state, reconnectAttempt)) {
         return
       }
       console.log('[net] ws.onopen', { attempt: reconnectAttempt })
@@ -385,18 +373,25 @@ export function connect(
           `No e2ee_ready/e2ee_authenticated within ${HANDSHAKE_TIMEOUT_MS / 1000}s`
         )
         openingWs.close()
+        // Why: React Native can omit onclose for a wedged iOS transport.
+        if (ws === openingWs) {
+          synthesizedCloses.remember(openingWs, authenticationGeneration)
+          handleSocketClosed(openingWs, { timedOut: true })
+        }
       }, HANDSHAKE_TIMEOUT_MS)
     }
 
     ws.onmessage = (event) => {
-      if (ignoreStaleSocketEvent('message')) {
+      if (isStaleRpcSocketEvent(ws, openingWs, 'message', state, reconnectAttempt)) {
         return
       }
       void handleSocketMessage(event.data)
     }
 
     async function handleSocketMessage(rawData: unknown) {
-      lastInboundAt = Date.now()
+      const receivedAt = Date.now()
+      lastInboundAt = receivedAt
+      openingWsLastInboundAt = receivedAt
       const raw = typeof rawData === 'string' ? rawData : null
 
       // Why: e2ee_ready is plaintext (precedes encrypted auth); e2ee_authenticated/e2ee_error are encrypted.
@@ -434,6 +429,7 @@ export function connect(
             console.log('[net] e2ee_authenticated — connected', {
               streamCount: streamListeners.size
             })
+            openingWsAuthenticated = true
             setState('connected')
             emitLog('success', 'Authenticated', 'Channel ready for RPC')
             startActivityProbe()
@@ -599,36 +595,21 @@ export function connect(
     }
 
     ws.onclose = (event) => {
-      const e = event as { code?: number; reason?: string; wasClean?: boolean } | undefined
-      const closeAt = Date.now()
-      // Why: time-since-construct classifies the failure — instant close = RST/unreachable, slow = SYN timeout/packet loss.
-      const constructToCloseMs = currentWsOpenedAt != null ? closeAt - currentWsOpenedAt : null
-      const aliveMs =
-        currentWsOpenedAt != null && state === 'connected' ? closeAt - currentWsOpenedAt : null
-      const inboundIdleMs = lastInboundAt != null ? closeAt - lastInboundAt : null
-      // Why: statically imported — a hot-reload bug came from a stale closure capturing a half-loaded module.
-      const closeEvent = describeSocketEvent(event)
-      console.log('[net] ws.onclose', {
-        code: e?.code,
-        reason: e?.reason,
-        wasClean: e?.wasClean,
+      const closeCode = logRpcSocketClose({
+        event,
         state,
         attempt: reconnectAttempt,
         intentionallyClosed,
-        endpoint: redactedEndpoint(endpoint),
-        constructToCloseMs,
-        aliveMs,
-        inboundIdleMs,
-        eventKeys: closeEvent.keys,
-        eventStr: closeEvent.json
+        endpoint: redactSocketEndpoint(endpoint),
+        constructedAt: now,
+        authenticated: openingWsAuthenticated,
+        lastInboundAt: openingWsLastInboundAt
       })
-      lastWsClosedAt = closeAt
-      currentWsOpenedAt = null
-      handleSocketClosed(openingWs, { closeCode: e?.code })
+      handleSocketClosed(openingWs, { closeCode })
     }
 
     ws.onerror = (event) => {
-      if (ignoreStaleSocketEvent('error')) {
+      if (isStaleRpcSocketEvent(ws, openingWs, 'error', state, reconnectAttempt)) {
         return
       }
       // Why: RN surfaces the original network error here — onclose follows but its close code alone hides the cause.
@@ -649,12 +630,24 @@ export function connect(
     opts: { timedOut?: boolean; closeCode?: number } = {}
   ) {
     if (ws !== closedWs) {
+      if (
+        synthesizedCloses.takeUnauthorized(
+          closedWs,
+          opts.closeCode,
+          authenticationGeneration,
+          UNAUTHORIZED_CLOSE_CODE
+        )
+      ) {
+        handleAuthRejection('Unauthorized — pairing may be revoked', true)
+        return
+      }
       console.log('[net] handleSocketClosed STALE — ignoring (ws already swapped)', {
         state,
         attempt: reconnectAttempt
       })
       return
     }
+    lastWsClosedAt = Date.now()
     clearConnectTimer()
     ws = null
     sharedKey = null
@@ -695,21 +688,24 @@ export function connect(
   }
 
   // Why: an auth rejection may be transient (issue #5200) — retry up to AUTH_RETRY_BUDGET times before latching auth-failed.
-  function handleAuthRejection(reason: string): void {
-    activeBrowserScreencastRequestId = null
-    pendingBrowserScreencastRequestId = null
+  function handleAuthRejection(reason: string, preserveRecovery = false): void {
     authRejectionCount++
     if (authRejectionCount < AUTH_RETRY_BUDGET) {
       console.log('[net] auth rejected — retrying handshake', {
         attempt: authRejectionCount,
         budget: AUTH_RETRY_BUDGET,
-        endpoint: redactedEndpoint(endpoint)
+        endpoint: redactSocketEndpoint(endpoint)
       })
       emitLog(
         'warn',
         'Authentication rejected',
         `Retrying (${authRejectionCount}/${AUTH_RETRY_BUDGET})`
       )
+      if (preserveRecovery) {
+        return
+      }
+      activeBrowserScreencastRequestId = null
+      pendingBrowserScreencastRequestId = null
       // Why: close without setting intentionallyClosed so handleSocketClosed routes to reconnect and retries the handshake.
       const closing = ws
       ws = null
@@ -724,9 +720,11 @@ export function connect(
       scheduleReconnect()
       return
     }
+    activeBrowserScreencastRequestId = null
+    pendingBrowserScreencastRequestId = null
     console.log('[net] auth rejected — budget exhausted, latching auth-failed', {
       attempt: authRejectionCount,
-      endpoint: redactedEndpoint(endpoint)
+      endpoint: redactSocketEndpoint(endpoint)
     })
     intentionallyClosed = true
     ws?.close()
@@ -793,6 +791,7 @@ export function connect(
         probeWs.close()
         // Why: React Native can omit onclose for a wedged iOS transport.
         if (probeWs === ws) {
+          synthesizedCloses.remember(probeWs, authenticationGeneration)
           handleSocketClosed(probeWs, { timedOut: true })
         }
       }
@@ -973,6 +972,7 @@ export function connect(
       console.log('[net] sendEncrypted detected ws desync — forcing reconnect', {
         readyState: ws.readyState
       })
+      synthesizedCloses.remember(ws, authenticationGeneration)
       handleSocketClosed(ws, { timedOut: false })
     }
     return false
diff --git a/mobile/src/transport/rpc-socket-close-evidence.ts b/mobile/src/transport/rpc-socket-close-evidence.ts
new file mode 100644
index 00000000000..7f57a6a6f59
--- /dev/null
+++ b/mobile/src/transport/rpc-socket-close-evidence.ts
@@ -0,0 +1,70 @@
+import { describeSocketEvent } from './socket-event-debug'
+import type { ConnectionState } from './types'
+
+type SocketCloseLogOptions = {
+  event: unknown
+  state: ConnectionState
+  attempt: number
+  intentionallyClosed: boolean
+  endpoint: string
+  constructedAt: number
+  authenticated: boolean
+  lastInboundAt: number | null
+}
+
+export class RpcSynthesizedCloseIndex {
+  private readonly authenticationBySocket = new WeakMap<WebSocket, number>()
+
+  remember(socket: WebSocket, authenticationGeneration: number): void {
+    this.authenticationBySocket.set(socket, authenticationGeneration)
+  }
+
+  takeUnauthorized(
+    socket: WebSocket,
+    closeCode: number | undefined,
+    authenticationGeneration: number,
+    unauthorizedCloseCode: number
+  ): boolean {
+    const synthesizedAtGeneration = this.authenticationBySocket.get(socket)
+    this.authenticationBySocket.delete(socket)
+    return (
+      closeCode === unauthorizedCloseCode && synthesizedAtGeneration === authenticationGeneration
+    )
+  }
+}
+
+export function isStaleRpcSocketEvent(
+  current: WebSocket | null,
+  opening: WebSocket,
+  eventName: string,
+  state: ConnectionState,
+  attempt: number
+): boolean {
+  if (current === opening) {
+    return false
+  }
+  console.log('[net] stale ws event ignored', { eventName, state, attempt })
+  return true
+}
+
+export function logRpcSocketClose(options: SocketCloseLogOptions): number | undefined {
+  const event = options.event as { code?: number; reason?: string; wasClean?: boolean } | undefined
+  const closeAt = Date.now()
+  const constructToCloseMs = closeAt - options.constructedAt
+  const closeEvent = describeSocketEvent(options.event)
+  console.log('[net] ws.onclose', {
+    code: event?.code,
+    reason: event?.reason,
+    wasClean: event?.wasClean,
+    state: options.state,
+    attempt: options.attempt,
+    intentionallyClosed: options.intentionallyClosed,
+    endpoint: options.endpoint,
+    constructToCloseMs,
+    aliveMs: options.authenticated ? constructToCloseMs : null,
+    inboundIdleMs: options.lastInboundAt != null ? closeAt - options.lastInboundAt : null,
+    eventKeys: closeEvent.keys,
+    eventStr: closeEvent.json
+  })
+  return event?.code
+}
diff --git a/mobile/src/transport/socket-event-debug.ts b/mobile/src/transport/socket-event-debug.ts
index 89b2167c79f..dab927ad6b0 100644
--- a/mobile/src/transport/socket-event-debug.ts
+++ b/mobile/src/transport/socket-event-debug.ts
@@ -32,3 +32,11 @@ export function describeSocketEvent(event: unknown): { keys: string[]; json: str
   }
   return { keys, json }
 }
+
+export function redactSocketEndpoint(endpoint: string): string {
+  try {
+    return new URL(endpoint).host || 'unknown'
+  } catch {
+    return 'unknown'
+  }
+}

From 886fa7b4389fd309aee6a8674554f542be3b0eea Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Fri, 31 Jul 2026 05:44:53 -0700
Subject: [PATCH 19/23] [P0] fix(relay): stop the retired exit record from
 double-broadcasting pty.exit (#11660)

* fix(relay): stop the retired exit record from double-broadcasting pty.exit

Retiring the publication record at cancel or grace-expiry time routed the pending
exit through pty-handler's unconditional broadcast, so subscribers that already
received the exit from the record's legacy projection got a second copy (which
fans out to a whole-provider teardown on the consumer side).

- Track the legacy exit projection in a RelayPtySourceLegacyExitIndex keyed by
  pty incarnation so it outlives the delivery record; the handler's fallback now
  re-targets only source-owner clients when subscribers already have the exit.
- Cover the previously untested defense layers: B2 same-client re-attach healing,
  B3 deferred retire-on-append-failure (retire plus the microtask deferral), and
  publishPendingExit's `accepts(id) &&` sub-guard.
- Harden layer D's capacity fan-out (it sits outside the catch it depends on),
  route cancelExact's bare-timer probe through snapshotIfKnown, and keep
  appendDenied counting cancel-induced append rejections.

* test(relay): pin the retired-record exit dedup and stop its index leaking

The legacy-exit dedup layer shipped with zero coverage: deleting pty-handler's
`publishExitAfterRetire` wiring left the whole relay suite green, because the
send scheduler's partial-progress branch keeps a projected record alive so B1
handles the common case and the fallback is never reached.

- Cover `RelayPtySourceLegacyExitIndex` directly, pin pty-handler's fallback
  (a retired record re-targets its own exit instead of broadcasting a duplicate
  to subscribers that already have it, and still broadcasts when nothing was
  projected), and drive the reachable retire path: B2's re-attach retires a
  record whose projection only the index remembers.
- Forget the index entry when `exitPublicationSettled` prunes a healthy exit.
  `remember()` only re-ran from the exit path, which B0 short-circuits after a
  settled exit, so every source-mode PTY exit leaked one Map row for the
  daemon's lifetime and would re-publish on any later fallback for that id.

* fix(relay): contain retired exit publication faults

* fix(relay): retain projected exits across owner faults

* fix(relay): retire faulted exit deliveries
---
 .../pty-handler-source-publication.test.ts    | 193 +++++++++++++++
 src/relay/pty-handler.ts                      |  20 +-
 ...relay-pty-source-cancellation-exit.test.ts | 114 +++++++--
 .../relay-pty-source-exit-publication.test.ts | 226 +++++++++++++++++-
 .../relay-pty-source-exit-publication.ts      | 140 ++++++++++-
 src/relay/relay-pty-source-publication.ts     |  32 ++-
 src/relay/ssh-pty-source-credit-adapter.ts    |   5 +-
 7 files changed, 687 insertions(+), 43 deletions(-)

diff --git a/src/relay/pty-handler-source-publication.test.ts b/src/relay/pty-handler-source-publication.test.ts
index 282d9f536db..48a5f74904f 100644
--- a/src/relay/pty-handler-source-publication.test.ts
+++ b/src/relay/pty-handler-source-publication.test.ts
@@ -60,6 +60,8 @@ describe('PtyHandler negotiated source publication', () => {
   let destroyPty: ReturnType<typeof vi.fn>
   let holdDataSettlements: boolean
   let heldDataSettlements: ((result: SinkWriteSettlement) => void)[]
+  let holdExitSettlements: boolean
+  let heldExitSettlements: ((result: SinkWriteSettlement) => void)[]
   let highWaterMark: number | undefined
 
   beforeEach(async () => {
@@ -72,6 +74,8 @@ describe('PtyHandler negotiated source publication', () => {
     exitCallback = undefined
     holdDataSettlements = false
     heldDataSettlements = []
+    holdExitSettlements = false
+    heldExitSettlements = []
     highWaterMark = undefined
     pausePty = vi.fn()
     destroyPty = vi.fn()
@@ -105,6 +109,10 @@ describe('PtyHandler negotiated source publication', () => {
           return true
         }
         if (frame?.method === 'pty.exit') {
+          if (holdExitSettlements) {
+            heldExitSettlements.push(settle)
+            return true
+          }
           // Why: real sockets never settle inside write(); a synchronous settle would re-enter
           // the legacy capacity path before the pending exit is retired.
           queueMicrotask(() => settle({ ok: true }))
@@ -213,6 +221,74 @@ describe('PtyHandler negotiated source publication', () => {
     expect(exitFrames()).toHaveLength(1)
   })
 
+  function attachSubscriber(): Buffer[] {
+    const subscriberWrites: Buffer[] = []
+    dispatcher.attachClient(
+      (data, settle) => {
+        subscriberWrites.push(Buffer.from(data))
+        if (notification(data)?.method === 'pty.exit') {
+          // Why: real sockets never settle inside write(); see the primary sink above.
+          queueMicrotask(() => settle({ ok: true }))
+          return true
+        }
+        settle({ ok: true })
+        return true
+      },
+      { supportsWriteCallback: true }
+    )
+    return subscriberWrites
+  }
+
+  function subscriberExitFrames(subscriberWrites: Buffer[]): Notification[] {
+    return subscriberWrites
+      .map(notification)
+      .filter((frame): frame is Notification => frame?.method === 'pty.exit')
+  }
+
+  it('never re-delivers the exit to subscribers when a cancel retires the record', async () => {
+    await spawn({})
+    const spawnResult = writes.map((buffer) => responseResult(buffer, 2)).find(Boolean)!
+    const subscriberWrites = attachSubscriber()
+    dataCallback!('prompt')
+    await vi.advanceTimersByTimeAsync(8)
+
+    // Why: the owner's producer lane is saturated when the PTY exits, so only the legacy
+    // projection lands; the record then still holds the undelivered owner exit.
+    highWaterMark = 64
+    expect(() => exitCallback!({ exitCode: 0 })).not.toThrow()
+    await vi.advanceTimersByTimeAsync(8)
+    expect(subscriberExitFrames(subscriberWrites)).toHaveLength(1)
+
+    highWaterMark = undefined
+    await cancelSourceDelivery(spawnResult)
+    await vi.advanceTimersByTimeAsync(8)
+
+    expect(subscriberExitFrames(subscriberWrites)).toHaveLength(1)
+  })
+
+  it('drains the pending exit once the retired record published it', async () => {
+    await spawn({})
+    const spawnResult = writes.map((buffer) => responseResult(buffer, 2)).find(Boolean)!
+    dataCallback!('prompt')
+    await vi.advanceTimersByTimeAsync(8)
+    holdExitSettlements = true
+
+    exitCallback!({ exitCode: 0 })
+    await vi.advanceTimersByTimeAsync(0)
+    expect(heldExitSettlements).toHaveLength(1)
+    await cancelSourceDelivery(spawnResult)
+    // Why: the in-flight frame failing on a canceled delivery is the only path that reaches
+    // the retiring branch with an unsettled exit publication.
+    heldExitSettlements[0]({ ok: false, error: new Error('socket write failed') })
+    await vi.advanceTimersByTimeAsync(8)
+    expect(exitFrames()).toHaveLength(2)
+
+    handler.handleSourcePublicationCapacity(String(spawnResult.id))
+    await vi.advanceTimersByTimeAsync(8)
+
+    expect(exitFrames()).toHaveLength(2)
+  })
+
   it('drains buffered legacy output before the exit when capacity returns', async () => {
     await spawn({})
     const spawnResult = writes.map((buffer) => responseResult(buffer, 2)).find(Boolean)!
@@ -271,6 +347,123 @@ describe('PtyHandler negotiated source publication', () => {
     }
   })
 
+  it('retires the delivery after the owner exit publication throws', async () => {
+    await spawn({})
+    const spawnResult = writes.map((buffer) => responseResult(buffer, 2)).find(Boolean)!
+    const id = String(spawnResult.id)
+    const subscriberWrites = attachSubscriber()
+    const stderr = vi.spyOn(process.stderr, 'write').mockReturnValue(true)
+    const publishOwnerExit = vi
+      .spyOn(dispatcher, 'tryNotifyPtyExitToClient')
+      .mockImplementationOnce(() => {
+        throw new Error('owner write failed')
+      })
+    try {
+      expect(() => exitCallback!({ exitCode: 8 })).not.toThrow()
+      await vi.advanceTimersByTimeAsync(0)
+
+      expect(exitFrames()).toHaveLength(1)
+      expect(subscriberExitFrames(subscriberWrites)).toHaveLength(1)
+      expect(publication.accepts(id)).toBe(false)
+      expect(adapter.getDebugSnapshot().deliveryTokens).toBe(0)
+
+      handler.handleSourcePublicationCapacity(id)
+      await vi.advanceTimersByTimeAsync(0)
+      expect(exitFrames()).toHaveLength(1)
+      expect(subscriberExitFrames(subscriberWrites)).toHaveLength(1)
+    } finally {
+      publishOwnerExit.mockRestore()
+      stderr.mockRestore()
+    }
+  })
+
+  it('retires the delivery when committed owner exit settlement fails', async () => {
+    await spawn({})
+    const spawnResult = writes.map((buffer) => responseResult(buffer, 2)).find(Boolean)!
+    const id = String(spawnResult.id)
+    const subscriberWrites = attachSubscriber()
+    const stderr = vi.spyOn(process.stderr, 'write').mockReturnValue(true)
+    const settleOwnerExit = vi.spyOn(adapter, 'settleExitPublication').mockImplementation(() => {
+      throw new Error('exit settlement failed')
+    })
+    try {
+      exitCallback!({ exitCode: 9 })
+      await vi.advanceTimersByTimeAsync(0)
+
+      expect(exitFrames()).toHaveLength(1)
+      expect(subscriberExitFrames(subscriberWrites)).toHaveLength(1)
+      expect(publication.accepts(id)).toBe(false)
+      expect(adapter.getDebugSnapshot().deliveryTokens).toBe(0)
+
+      handler.handleSourcePublicationCapacity(id)
+      await vi.advanceTimersByTimeAsync(0)
+      expect(exitFrames()).toHaveLength(1)
+      expect(subscriberExitFrames(subscriberWrites)).toHaveLength(1)
+    } finally {
+      settleOwnerExit.mockRestore()
+      stderr.mockRestore()
+    }
+  })
+
+  it('lets a retired record re-target its own exit instead of broadcasting a duplicate', async () => {
+    await spawn({})
+    const spawnResult = writes.map((buffer) => responseResult(buffer, 2)).find(Boolean)!
+    const subscriberWrites = attachSubscriber()
+    const publishExitAfterRetire = vi.fn(() => true)
+    handler.setSourcePublication(stubPublication({ accepts: () => false, publishExitAfterRetire }))
+
+    expect(() => exitCallback!({ exitCode: 4 })).not.toThrow()
+
+    expect(publishExitAfterRetire).toHaveBeenCalledWith(
+      expect.objectContaining({ id: spawnResult.id, code: 4 })
+    )
+    expect(exitFrames()).toHaveLength(0)
+    expect(subscriberExitFrames(subscriberWrites)).toHaveLength(0)
+
+    handler.handleSourcePublicationCapacity(String(spawnResult.id))
+    await vi.advanceTimersByTimeAsync(8)
+    expect(publishExitAfterRetire).toHaveBeenCalledOnce()
+  })
+
+  it('broadcasts the legacy exit when the retired record never projected one', async () => {
+    await spawn({})
+    const spawnResult = writes.map((buffer) => responseResult(buffer, 2)).find(Boolean)!
+    handler.setSourcePublication(
+      stubPublication({ accepts: () => false, publishExitAfterRetire: () => null })
+    )
+
+    exitCallback!({ exitCode: 5 })
+
+    expect(exitFrames()).toHaveLength(1)
+    expect(exitFrames()[0].params).toMatchObject({ id: spawnResult.id, code: 5 })
+  })
+
+  it('contains a retired-record publication fault and falls back to the legacy exit', async () => {
+    await spawn({})
+    const spawnResult = writes.map((buffer) => responseResult(buffer, 2)).find(Boolean)!
+    const stderr = vi.spyOn(process.stderr, 'write').mockReturnValue(true)
+    try {
+      handler.setSourcePublication(
+        stubPublication({
+          accepts: () => false,
+          publishExitAfterRetire: () => {
+            throw new Error('retired owner lookup failed')
+          }
+        })
+      )
+
+      expect(() => exitCallback!({ exitCode: 6 })).not.toThrow()
+
+      expect(exitFrames()).toHaveLength(1)
+      expect(exitFrames()[0].params).toMatchObject({ id: spawnResult.id, code: 6 })
+      expect(String(stderr.mock.calls.at(-1)?.[0])).toContain(
+        '[pty-handler] retired pty exit publication failed'
+      )
+    } finally {
+      stderr.mockRestore()
+    }
+  })
+
   it('completes the exit from the settled state without re-sealing the delivery', async () => {
     await spawn({})
     const spawnResult = writes.map((buffer) => responseResult(buffer, 2)).find(Boolean)!
diff --git a/src/relay/pty-handler.ts b/src/relay/pty-handler.ts
index c54e1d13e89..67bfc4c6e15 100644
--- a/src/relay/pty-handler.ts
+++ b/src/relay/pty-handler.ts
@@ -1058,9 +1058,23 @@ export class PtyHandler {
         )
       }
     }
-    const published = this.dispatcher.tryNotifyPtyExit
-      ? this.dispatcher.tryNotifyPtyExit(exit)
-      : (this.dispatcher.notify('pty.exit', exit), true)
+    // Why: a retired record can already have projected this exit to the legacy subscribers, and
+    // the broadcast below would hand them a second copy.
+    let retiredExitPublished: boolean | null | undefined
+    try {
+      retiredExitPublished = this.sourcePublication?.publishExitAfterRetire?.(exit)
+    } catch (err) {
+      process.stderr.write(
+        `[pty-handler] retired pty exit publication failed for ${id}: ${
+          err instanceof Error ? (err.stack ?? err.message) : String(err)
+        }\n`
+      )
+    }
+    const published =
+      retiredExitPublished ??
+      (this.dispatcher.tryNotifyPtyExit
+        ? this.dispatcher.tryNotifyPtyExit(exit)
+        : (this.dispatcher.notify('pty.exit', exit), true))
     if (!published) {
       return
     }
diff --git a/src/relay/relay-pty-source-cancellation-exit.test.ts b/src/relay/relay-pty-source-cancellation-exit.test.ts
index e59b909802b..8a1f5d39ebb 100644
--- a/src/relay/relay-pty-source-cancellation-exit.test.ts
+++ b/src/relay/relay-pty-source-cancellation-exit.test.ts
@@ -77,9 +77,12 @@ describe('RelayPtySourcePublication cancellation and exit', () => {
       endpointIdentity
     )
     let publication: RelayPtySourcePublication
-    const adapter = new SshPtyConsumerSessionAdapter(dispatcher, 'build-a', undefined, (id) =>
-      publication.onCreditAvailable(id)
-    )
+    let creditNoticeEnabled = true
+    const adapter = new SshPtyConsumerSessionAdapter(dispatcher, 'build-a', undefined, (id) => {
+      if (creditNoticeEnabled) {
+        publication.onCreditAvailable(id)
+      }
+    })
     publication = new RelayPtySourcePublication(dispatcher, adapter, (id) => capacityIds.push(id))
     dispatcher.feed(
       requestFrame(1, 'pty.openClient', {
@@ -100,7 +103,29 @@ describe('RelayPtySourcePublication cancellation and exit', () => {
       })
     ).toBe('opened')
     activationSettlements[0]({ ok: true })
-    return { adapter, publication, exitSettlements, capacityIds, writes }
+    return {
+      adapter,
+      publication,
+      exitSettlements,
+      capacityIds,
+      writes,
+      setCreditNoticeEnabled: (enabled: boolean): void => {
+        creditNoticeEnabled = enabled
+      }
+    }
+  }
+
+  function activateOwner(publication: RelayPtySourcePublication): void {
+    const settlements: ((result: SinkWriteSettlement) => void)[] = []
+    expect(
+      publication.activate('pty-1', 'incarnation-1', {
+        clientId: 1,
+        isStale: () => false,
+        sessionIdentity: endpointIdentity,
+        onResponseSettled: (callback) => settlements.push(callback)
+      })
+    ).toBe('opened')
+    settlements[0]({ ok: true })
   }
 
   function cancelDeliveryFrame(
@@ -200,16 +225,7 @@ describe('RelayPtySourcePublication cancellation and exit', () => {
     dispatcher!.feed(cancelDeliveryFrame(2, activation))
     await flushRequests()
 
-    const activationSettlements: ((result: SinkWriteSettlement) => void)[] = []
-    expect(
-      harness.publication.activate('pty-1', 'incarnation-1', {
-        clientId: 1,
-        isStale: () => false,
-        sessionIdentity: endpointIdentity,
-        onResponseSettled: (callback) => activationSettlements.push(callback)
-      })
-    ).toBe('opened')
-    activationSettlements[0]({ ok: true })
+    activateOwner(harness.publication)
 
     expect(
       harness.publication.sealAndPublishExit({
@@ -221,6 +237,46 @@ describe('RelayPtySourcePublication cancellation and exit', () => {
     expect(exitFrames(harness.writes)).toHaveLength(1)
   })
 
+  it('reopens the delivery when the same client re-attaches over a closed ledger record', async () => {
+    const harness = await createHarness(8, true)
+    harness.publication.publish('pty-1', { data: 'data' }, false)
+    const activation = harness.publication.receivingActivation('pty-1', 1)!
+    dispatcher!.feed(ackFrame(2, activation, 4))
+    harness.publication.sealAndPublishExit({ id: 'pty-1', code: 0, incarnationId: 'incarnation-1' })
+    dispatcher!.feed(cancelDeliveryFrame(3, activation))
+    await flushRequests()
+    harness.exitSettlements[0]({ ok: true })
+    // Why: A' held the record across the in-flight frame, so it outlives the closed ledger until
+    // a capacity consumer prunes it — a re-attach must not resume that dead delivery.
+    expect(harness.publication.accepts('pty-1')).toBe(true)
+
+    activateOwner(harness.publication)
+
+    expect(harness.publication.publish('pty-1', { data: 'more' }, false)).toBe(true)
+  })
+
+  it('retires the record and defers capacity when an append lands on a closed delivery', async () => {
+    const harness = await createHarness()
+    harness.publication.publish('pty-1', { data: 'data' }, false)
+    const activation = harness.publication.receivingActivation('pty-1', 1)!
+    // Why: emulate a close the publication never saw — B3 backstops exactly the record/ledger
+    // disagreement that layer A's credit notification normally prevents.
+    harness.setCreditNoticeEnabled(false)
+    dispatcher!.feed(cancelDeliveryFrame(2, activation))
+    await flushRequests()
+    expect(harness.publication.accepts('pty-1')).toBe(true)
+    const capacityBefore = harness.capacityIds.length
+
+    expect(harness.publication.publish('pty-1', { data: 'more' }, false)).toBe(false)
+
+    expect(harness.publication.accepts('pty-1')).toBe(false)
+    // Why: publish() can run inside the captured-queue drain, so a synchronous capacity callback
+    // would publish pty.exit ahead of the chunk that is re-queued later in this same tick.
+    expect(harness.capacityIds).toHaveLength(capacityBefore)
+    await Promise.resolve()
+    expect(harness.capacityIds.slice(capacityBefore)).toEqual(['pty-1'])
+  })
+
   it('survives a cancel while the credit-mode exit frame is still in flight', async () => {
     const harness = await createHarness(8, true)
     harness.publication.publish('pty-1', { data: 'data' }, false)
@@ -275,6 +331,9 @@ describe('RelayPtySourcePublication cancellation and exit', () => {
       })
     ).toBe(true)
     expect(harness.publication.accepts('pty-1')).toBe(false)
+    // Why: the failed write closed the owner socket, so B1's owner-targeted retry matches no
+    // client — it must still retire the record rather than fan the exit out to everyone else.
+    expect(exitFrames(harness.writes)).toHaveLength(1)
     expect(harness.publication.getDebugSnapshot()).toMatchObject({
       exitCommitted: 0,
       exitRolledBack: 1
@@ -305,4 +364,31 @@ describe('RelayPtySourcePublication cancellation and exit', () => {
     ).not.toThrow()
     expect(exitFrames(harness.writes)).toHaveLength(1)
   })
+
+  it('forgets the legacy exit projection once the healthy exit settles', async () => {
+    const harness = await createHarness()
+    const exit = { id: 'pty-1', code: 0, incarnationId: 'incarnation-1' }
+    expect(harness.publication.sealAndPublishExit(exit)).toBe(true)
+
+    expect(harness.publication.exitPublicationSettled('pty-1')).toBe(true)
+
+    // Why: every client already holds this exit, so a retained index entry would both leak a row
+    // per exited pty and re-publish to the owner if any later fallback ran for the same id.
+    expect(harness.publication.publishExitAfterRetire(exit)).toBeNull()
+    expect(exitFrames(harness.writes)).toHaveLength(1)
+  })
+
+  it('re-targets the owner when a re-attach retires a record that already projected the exit', async () => {
+    const harness = await createHarness()
+    const exit = { id: 'pty-1', code: 0, incarnationId: 'incarnation-1' }
+    expect(harness.publication.sealAndPublishExit(exit)).toBe(true)
+
+    // Why: the handler holds its settled-check back while legacy output is still buffered, so B2
+    // can retire the record first — the index is then all that remembers the projection.
+    activateOwner(harness.publication)
+
+    expect(harness.publication.publishExitAfterRetire(exit)).toBe(true)
+    expect(exitFrames(harness.writes)).toHaveLength(2)
+    expect(harness.publication.publishExitAfterRetire(exit)).toBeNull()
+  })
 })
diff --git a/src/relay/relay-pty-source-exit-publication.test.ts b/src/relay/relay-pty-source-exit-publication.test.ts
index 619c7da8829..a7820c4aa5f 100644
--- a/src/relay/relay-pty-source-exit-publication.test.ts
+++ b/src/relay/relay-pty-source-exit-publication.test.ts
@@ -4,7 +4,11 @@ import type {
   PtySourceDeliverySnapshot
 } from '../shared/pty-source-credit-contract'
 import type { RelayDispatcher } from './dispatcher'
-import { sealAndPublishPtySourceExit } from './relay-pty-source-exit-publication'
+import {
+  RelayPtySourceLegacyExitIndex,
+  sealAndPublishPtySourceExit,
+  sealAndPublishTrackedPtySourceExit
+} from './relay-pty-source-exit-publication'
 import type {
   RelayPtySourceDeliveryRecord,
   RelayPtySourcePublicationCounters,
@@ -92,6 +96,7 @@ function createScenario(
       }
       return probe
     }),
+    cancelDelivery: vi.fn(),
     sealDelivery: vi.fn(),
     settleExitPublication: vi.fn(),
     deliveryMode: vi.fn(() => 'source-owner' as const)
@@ -104,7 +109,7 @@ function createScenario(
     projectPtyExitToMatchingClients: vi.fn(() => true),
     tryNotifyPtyExitToClient: vi.fn(() => true)
   }
-  const sender = { pump: vi.fn() }
+  const sender = { pump: vi.fn(), wakeSendWaiters: vi.fn() }
   const counters: RelayPtySourcePublicationCounters = {
     opened: 0,
     rotated: 0,
@@ -115,6 +120,13 @@ function createScenario(
     exitRolledBack: 0
   }
   const capacityIds: string[] = []
+  let capacityError: Error | null = null
+  const onCapacity = (id: string): void => {
+    capacityIds.push(id)
+    if (capacityError) {
+      throw capacityError
+    }
+  }
   const run = (): boolean =>
     sealAndPublishPtySourceExit({
       params,
@@ -124,9 +136,33 @@ function createScenario(
       session: session as unknown as SshPtyConsumerSessionAdapter,
       sender: sender as unknown as RelayPtySourceSendScheduler,
       counters,
-      onCapacity: (id) => capacityIds.push(id)
+      onCapacity
     })
-  return { deliveries, session, dispatcher, sender, counters, capacityIds, run, setProbe }
+  const runTracked = (legacyExits: RelayPtySourceLegacyExitIndex): boolean =>
+    sealAndPublishTrackedPtySourceExit({
+      params,
+      legacyExits,
+      deliveries,
+      dispatcher: dispatcher as unknown as RelayDispatcher,
+      session: session as unknown as SshPtyConsumerSessionAdapter,
+      sender: sender as unknown as RelayPtySourceSendScheduler,
+      counters,
+      onCapacity
+    })
+  return {
+    deliveries,
+    session,
+    dispatcher,
+    sender,
+    counters,
+    capacityIds,
+    run,
+    runTracked,
+    setProbe,
+    setCapacityError: (error: Error): void => {
+      capacityError = error
+    }
+  }
 }
 
 describe('sealAndPublishPtySourceExit closed-delivery guard', () => {
@@ -200,6 +236,139 @@ describe('sealAndPublishPtySourceExit closed-delivery guard', () => {
   })
 })
 
+describe('RelayPtySourceLegacyExitIndex', () => {
+  function createIndex(notifyAccepted = true) {
+    const index = new RelayPtySourceLegacyExitIndex()
+    const dispatcher = {
+      tryNotifyPtyExitToMatchingClients: vi.fn(
+        (_matches: (clientId: number) => boolean, _params: unknown) => notifyAccepted
+      )
+    }
+    const session = { deliveryMode: vi.fn(() => 'source-owner' as const) }
+    const publish = (): boolean | null =>
+      index.publishAfterRetire(
+        params,
+        dispatcher as unknown as RelayDispatcher,
+        session as unknown as SshPtyConsumerSessionAdapter
+      )
+    return { index, dispatcher, session, publish }
+  }
+
+  it('defers to the caller when nothing was projected for the pty', () => {
+    const scenario = createIndex()
+
+    expect(scenario.publish()).toBeNull()
+
+    expect(scenario.dispatcher.tryNotifyPtyExitToMatchingClients).not.toHaveBeenCalled()
+  })
+
+  it('re-targets the owner exactly once for a remembered projection', () => {
+    const scenario = createIndex()
+    scenario.index.remember(params, true)
+
+    expect(scenario.publish()).toBe(true)
+
+    const matches = scenario.dispatcher.tryNotifyPtyExitToMatchingClients.mock.calls[0][0]
+    expect(matches(1)).toBe(true)
+    scenario.session.deliveryMode.mockReturnValue('legacy-owner' as never)
+    expect(matches(1)).toBe(false)
+    // Why: the second pass is the handler's retry after a later capacity event; re-publishing
+    // would hand the owner a duplicate exit.
+    expect(scenario.publish()).toBeNull()
+  })
+
+  it('keeps the projection retryable when the owner notify is refused', () => {
+    const scenario = createIndex(false)
+    scenario.index.remember(params, true)
+
+    expect(scenario.publish()).toBe(false)
+    expect(scenario.publish()).toBe(false)
+  })
+
+  it('consumes a completed retired exit without publishing it again', () => {
+    const scenario = createIndex()
+    scenario.index.remember(params, true)
+    scenario.index.complete(params)
+
+    expect(scenario.publish()).toBe(true)
+    expect(scenario.dispatcher.tryNotifyPtyExitToMatchingClients).not.toHaveBeenCalled()
+    expect(scenario.publish()).toBeNull()
+  })
+
+  it('does not let stale completion overwrite a later incarnation', () => {
+    const scenario = createIndex()
+    const next = { ...params, incarnationId: 'incarnation-2' }
+    scenario.index.remember(next, true)
+
+    scenario.index.complete(params)
+
+    expect(scenario.publish()).toBeNull()
+    expect(
+      scenario.index.publishAfterRetire(
+        next,
+        scenario.dispatcher as unknown as RelayDispatcher,
+        scenario.session as unknown as SshPtyConsumerSessionAdapter
+      )
+    ).toBe(true)
+  })
+
+  it('remembers a subscriber projection when the owner publication throws', () => {
+    const record = deliveryRecord({ sealed: true })
+    const scenario = createScenario(closedSnapshot({ state: 'sealed-unsettled' }), record)
+    const index = new RelayPtySourceLegacyExitIndex()
+    scenario.dispatcher.tryNotifyPtyExitToClient.mockImplementation(() => {
+      throw new Error('owner write failed')
+    })
+
+    expect(() => scenario.runTracked(index)).toThrow('owner write failed')
+    expect(scenario.dispatcher.projectPtyExitToMatchingClients).toHaveBeenCalledOnce()
+    expect(scenario.session.cancelDelivery).toHaveBeenCalledWith(
+      record.identity,
+      'exit-publication-failed'
+    )
+    expect(scenario.deliveries.has(params.id)).toBe(false)
+    expect(
+      index.publishAfterRetire(
+        params,
+        scenario.dispatcher as unknown as RelayDispatcher,
+        scenario.session as unknown as SshPtyConsumerSessionAdapter
+      )
+    ).toBe(true)
+    expect(scenario.dispatcher.tryNotifyPtyExit).not.toHaveBeenCalled()
+    expect(
+      index.publishAfterRetire(
+        params,
+        scenario.dispatcher as unknown as RelayDispatcher,
+        scenario.session as unknown as SshPtyConsumerSessionAdapter
+      )
+    ).toBeNull()
+  })
+
+  it.each([
+    [
+      'a later incarnation reused the pty id',
+      (index: RelayPtySourceLegacyExitIndex) =>
+        index.remember({ ...params, incarnationId: 'incarnation-2' }, true)
+    ],
+    [
+      'the projection was withdrawn',
+      (index: RelayPtySourceLegacyExitIndex) => index.remember(params, false)
+    ],
+    [
+      'the exit completed for every client',
+      (index: RelayPtySourceLegacyExitIndex) => index.forget(params.id)
+    ],
+    ['the publication was disposed', (index: RelayPtySourceLegacyExitIndex) => index.clear()]
+  ])('defers to the caller once %s', (_label, mutate) => {
+    const scenario = createIndex()
+    scenario.index.remember(params, true)
+
+    mutate(scenario.index)
+
+    expect(scenario.publish()).toBeNull()
+  })
+})
+
 describe('sealAndPublishPtySourceExit settlement closure', () => {
   function createInFlightScenario(settlementProbe: PtySourceDeliverySnapshot | null) {
     const record = deliveryRecord({ sealed: true, legacyExitAccepted: true })
@@ -236,6 +405,44 @@ describe('sealAndPublishPtySourceExit settlement closure', () => {
     expect(scenario.capacityIds).toEqual(['pty-1'])
   })
 
+  it('retains committed completion until a failed capacity signal is retried', () => {
+    const record = deliveryRecord({ sealed: true })
+    const scenario = createScenario(closedSnapshot({ state: 'sealed-unsettled' }), record)
+    const index = new RelayPtySourceLegacyExitIndex()
+    let settle: ((result: { ok: true }) => void) | undefined
+    scenario.dispatcher.tryNotifyPtyExitToClient.mockImplementation((...args: unknown[]) => {
+      settle = args[2] as typeof settle
+      return true
+    })
+    scenario.session.settleExitPublication.mockImplementation(() => {
+      throw new Error('PTY source delivery is not sealed')
+    })
+    scenario.setCapacityError(new Error('capacity callback failed'))
+    const stderr = vi.spyOn(process.stderr, 'write').mockReturnValue(true)
+    try {
+      expect(scenario.runTracked(index)).toBe(true)
+      expect(() => settle!({ ok: true })).not.toThrow()
+
+      expect(
+        index.publishAfterRetire(
+          params,
+          scenario.dispatcher as unknown as RelayDispatcher,
+          scenario.session as unknown as SshPtyConsumerSessionAdapter
+        )
+      ).toBe(true)
+      expect(scenario.dispatcher.tryNotifyPtyExitToMatchingClients).not.toHaveBeenCalled()
+      expect(
+        index.publishAfterRetire(
+          params,
+          scenario.dispatcher as unknown as RelayDispatcher,
+          scenario.session as unknown as SshPtyConsumerSessionAdapter
+        )
+      ).toBeNull()
+    } finally {
+      stderr.mockRestore()
+    }
+  })
+
   it.each([
     ['committed', { ok: true } as const],
     ['rolled back', { ok: false, error: new Error('socket write failed') } as const]
@@ -243,9 +450,14 @@ describe('sealAndPublishPtySourceExit settlement closure', () => {
     const stderr = vi.spyOn(process.stderr, 'write').mockReturnValue(true)
     try {
       const scenario = createInFlightScenario(closedSnapshot({ state: 'sealed-unsettled' }))
+      scenario.record.sendWaiters.add(vi.fn())
       scenario.session.settleExitPublication.mockImplementation(() => {
         throw new Error('PTY source delivery is not sealed')
       })
+      scenario.sender.wakeSendWaiters.mockImplementation(() => {
+        throw new Error('send waiter failed')
+      })
+      scenario.setCapacityError(new Error('capacity callback failed'))
 
       expect(() => scenario.settle(result)).not.toThrow()
 
@@ -253,6 +465,12 @@ describe('sealAndPublishPtySourceExit settlement closure', () => {
         '[pty-source-exit] exit settlement failed for pty-1'
       )
       expect(scenario.capacityIds).toEqual(['pty-1'])
+      expect(scenario.session.cancelDelivery).toHaveBeenCalledWith(
+        scenario.record.identity,
+        'exit-publication-failed'
+      )
+      expect(scenario.deliveries.has(params.id)).toBe(false)
+      expect(scenario.record.sendWaiters.size).toBe(0)
     } finally {
       stderr.mockRestore()
     }
diff --git a/src/relay/relay-pty-source-exit-publication.ts b/src/relay/relay-pty-source-exit-publication.ts
index deafb51fc5b..6257ae25442 100644
--- a/src/relay/relay-pty-source-exit-publication.ts
+++ b/src/relay/relay-pty-source-exit-publication.ts
@@ -7,23 +7,133 @@ import {
 } from './relay-pty-source-send-scheduler'
 import type { SshPtyConsumerSessionAdapter } from './ssh-pty-consumer-session-adapter'
 
-type ExitParams = { id: string; code: number; incarnationId: string }
+export type PtyExitParams = { id: string; code: number; incarnationId: string }
 
-export function sealAndPublishPtySourceExit(options: {
-  params: ExitParams
+type PtySourceExitOptions = {
+  params: PtyExitParams
   record: RelayPtySourceDeliveryRecord
   deliveries: Map<string, RelayPtySourceDeliveryRecord>
+  legacyExits?: RelayPtySourceLegacyExitIndex
   dispatcher: RelayDispatcher
   session: SshPtyConsumerSessionAdapter
   sender: RelayPtySourceSendScheduler
   counters: RelayPtySourcePublicationCounters
   onCapacity: (id: string) => void
-}): boolean {
+}
+
+/**
+ * Remembers which exits already reached the legacy subscribers. `legacyExitAccepted` dies with
+ * the delivery record, but a cancel or grace expiry can retire the record between the legacy
+ * projection and the owner's exit frame, and the fallback must not broadcast a second copy.
+ */
+export class RelayPtySourceLegacyExitIndex {
+  private readonly stateByPty = new Map<
+    string,
+    Readonly<{ incarnationId: string; state: 'owner-pending' | 'complete' }>
+  >()
+
+  remember(params: PtyExitParams, delivered: boolean): void {
+    if (delivered) {
+      this.stateByPty.set(params.id, {
+        incarnationId: params.incarnationId,
+        state: 'owner-pending'
+      })
+    } else {
+      this.forget(params.id)
+    }
+  }
+
+  complete(params: PtyExitParams): void {
+    if (this.stateByPty.get(params.id)?.incarnationId !== params.incarnationId) {
+      return
+    }
+    this.stateByPty.set(params.id, { incarnationId: params.incarnationId, state: 'complete' })
+  }
+
+  /** Drops the entry once the exit is complete for every client, so the map cannot grow unbounded. */
+  forget(id: string): void {
+    this.stateByPty.delete(id)
+  }
+
+  clear = (): void => this.stateByPty.clear()
+
+  /** Publishes a retired record's exit to the owner alone, or null when nothing was projected. */
+  publishAfterRetire(
+    params: PtyExitParams,
+    dispatcher: RelayDispatcher,
+    session: SshPtyConsumerSessionAdapter
+  ): boolean | null {
+    const remembered = this.stateByPty.get(params.id)
+    if (remembered?.incarnationId !== params.incarnationId) {
+      return null
+    }
+    if (remembered.state === 'complete') {
+      this.forget(params.id)
+      return true
+    }
+    const published = dispatcher.tryNotifyPtyExitToMatchingClients(
+      (clientId) => session.deliveryMode(clientId) === 'source-owner',
+      params
+    )
+    if (published) {
+      this.forget(params.id)
+    }
+    return published
+  }
+}
+
+function logExitSettlementFault(id: string, err: unknown): void {
+  process.stderr.write(
+    `[pty-source-exit] exit settlement failed for ${id}: ${
+      err instanceof Error ? (err.stack ?? err.message) : String(err)
+    }\n`
+  )
+}
+
+function retireFaultedPtySourceExit(
+  options: PtySourceExitOptions,
+  record: RelayPtySourceDeliveryRecord
+): void {
+  try {
+    options.session.cancelDelivery(record.identity, 'exit-publication-failed')
+  } catch (err) {
+    logExitSettlementFault(options.params.id, err)
+  }
+  try {
+    options.sender.wakeSendWaiters(record)
+  } catch (err) {
+    logExitSettlementFault(options.params.id, err)
+  } finally {
+    record.sendWaiters.clear()
+  }
+  if (options.deliveries.get(options.params.id) === record) {
+    options.deliveries.delete(options.params.id)
+  }
+}
+
+/** Seals and publishes the pty's exit, recording whether the legacy projection outlives the record. */
+export function sealAndPublishTrackedPtySourceExit(
+  options: Omit<PtySourceExitOptions, 'record'> & { legacyExits: RelayPtySourceLegacyExitIndex }
+): boolean {
+  const record = options.deliveries.get(options.params.id)
+  if (!record) {
+    return false
+  }
+  try {
+    return sealAndPublishPtySourceExit({ ...options, record })
+  } catch (err) {
+    retireFaultedPtySourceExit({ ...options, record }, record)
+    throw err
+  }
+}
+
+export function sealAndPublishPtySourceExit(options: PtySourceExitOptions): boolean {
   const { params, record, deliveries, dispatcher, session, sender, counters, onCapacity } = options
   if (record.restoreRequired) {
     const published = dispatcher.tryNotifyPtyExit(params)
     if (published && deliveries.get(params.id) === record) {
       deliveries.delete(params.id)
+      options.legacyExits?.forget(params.id)
     }
     return published
   }
@@ -32,12 +142,15 @@ export function sealAndPublishPtySourceExit(options: {
     return false
   }
   const probe = session.sourceDeliverySnapshotIfKnown(record.identity)
+  // Why: 'closing' is defensive — the ledger closes a canceled record in the same call, so it
+  // only ever hands back 'closed' (or null once the tombstone is evicted).
   if (!probe || probe.state === 'closed' || probe.state === 'closing') {
     if (probe?.exitPublished === true || record.sourceExitState === 'published') {
       // Why: the delivery completed healthily — the owner already has the credit-mode exit.
       if (deliveries.get(params.id) === record) {
         deliveries.delete(params.id)
       }
+      options.legacyExits?.forget(params.id)
       return true
     }
     // Why: the delivery was canceled out from under the record; never touch the sealed
@@ -50,6 +163,7 @@ export function sealAndPublishPtySourceExit(options: {
       : dispatcher.tryNotifyPtyExit(params)
     if (published && deliveries.get(params.id) === record) {
       deliveries.delete(params.id)
+      options.legacyExits?.forget(params.id)
     }
     return published
   }
@@ -67,6 +181,7 @@ export function sealAndPublishPtySourceExit(options: {
       (clientId) => session.deliveryMode(clientId) !== 'source-owner',
       params
     )
+    options.legacyExits?.remember(params, record.legacyExitAccepted)
     if (!record.legacyExitAccepted) {
       return false
     }
@@ -96,14 +211,19 @@ export function sealAndPublishPtySourceExit(options: {
       }
     } catch (err) {
       settlementFailed = true
-      process.stderr.write(
-        `[pty-source-exit] exit settlement failed for ${params.id}: ${
-          err instanceof Error ? (err.stack ?? err.message) : String(err)
-        }\n`
-      )
+      logExitSettlementFault(params.id, err)
+      if (result.ok) {
+        options.legacyExits?.complete(params)
+      }
+      retireFaultedPtySourceExit(options, record)
     } finally {
       if (result.ok || deliveryGone || settlementFailed) {
-        onCapacity(params.id)
+        try {
+          // Why: capacity fans out into arbitrary handler code, still from the bare socket callback.
+          onCapacity(params.id)
+        } catch (err) {
+          logExitSettlementFault(params.id, err)
+        }
       }
     }
   })
diff --git a/src/relay/relay-pty-source-publication.ts b/src/relay/relay-pty-source-publication.ts
index b46a65c72e3..b21e8a79cf2 100644
--- a/src/relay/relay-pty-source-publication.ts
+++ b/src/relay/relay-pty-source-publication.ts
@@ -16,7 +16,11 @@ import {
   type RelayPtySourceDeliveryRecord,
   type RelayPtySourcePublicationCounters
 } from './relay-pty-source-send-scheduler'
-import { sealAndPublishPtySourceExit } from './relay-pty-source-exit-publication'
+import {
+  RelayPtySourceLegacyExitIndex,
+  sealAndPublishTrackedPtySourceExit,
+  type PtyExitParams
+} from './relay-pty-source-exit-publication'
 import type { RelayDispatcher, RequestContext } from './dispatcher'
 import {
   appendPtySourceOutput,
@@ -28,6 +32,7 @@ import type { SshPtyConsumerSessionAdapter } from './ssh-pty-consumer-session-ad
 
 export class RelayPtySourcePublication {
   private readonly deliveries = new Map<string, RelayPtySourceDeliveryRecord>()
+  private readonly legacyExits = new RelayPtySourceLegacyExitIndex()
   private readonly counters: RelayPtySourcePublicationCounters = {
     opened: 0,
     rotated: 0,
@@ -213,6 +218,7 @@ export class RelayPtySourcePublication {
       return false
     }
     if (!output.sourceAccepted && !appendPtySourceOutput(this.session, record, output)) {
+      this.counters.appendDenied++
       if (this.deliveryClosedUnderRecord(record)) {
         this.sender.wakeSendWaiters(record)
         this.deliveries.delete(id)
@@ -223,7 +229,6 @@ export class RelayPtySourcePublication {
         queueMicrotask(() => this.onCapacity(id))
         return false
       }
-      this.counters.appendDenied++
       return false
     }
     if (!projectPtySourceOutputToLegacy(this.dispatcher, this.session, id, output, interactive)) {
@@ -233,14 +238,10 @@ export class RelayPtySourcePublication {
     return true
   }
 
-  sealAndPublishExit(params: { id: string; code: number; incarnationId: string }): boolean {
-    const record = this.deliveries.get(params.id)
-    if (!record) {
-      return false
-    }
-    return sealAndPublishPtySourceExit({
+  sealAndPublishExit = (params: PtyExitParams): boolean =>
+    sealAndPublishTrackedPtySourceExit({
       params,
-      record,
+      legacyExits: this.legacyExits,
       deliveries: this.deliveries,
       dispatcher: this.dispatcher,
       session: this.session,
@@ -248,7 +249,10 @@ export class RelayPtySourcePublication {
       counters: this.counters,
       onCapacity: this.onCapacity
     })
-  }
+
+  /** Returns null when the caller should fall back to its own legacy exit broadcast. */
+  publishExitAfterRetire = (params: PtyExitParams): boolean | null =>
+    this.legacyExits.publishAfterRetire(params, this.dispatcher, this.session)
 
   onCreditAvailable = (id: string): void => this.sender.onCreditAvailable(id)
 
@@ -257,13 +261,19 @@ export class RelayPtySourcePublication {
     if (!record || record.sourceExitState !== 'published') {
       return false
     }
+    // Why: owner and legacy subscribers both hold this exit now, so the index row would otherwise
+    // outlive the pty for the daemon's lifetime and re-publish on any later fallback.
+    this.legacyExits.forget(id)
     this.sender.pruneClosed(id, record)
     return true
   }
 
   getDebugSnapshot = () => this.sender.getDebugSnapshot()
 
-  dispose = (): void => this.sender.dispose()
+  dispose = (): void => {
+    this.legacyExits.clear()
+    this.sender.dispose()
+  }
 
   private deliveryClosedUnderRecord(record: RelayPtySourceDeliveryRecord): boolean {
     return ptySourceDeliveryClosed(this.session, record.identity)
diff --git a/src/relay/ssh-pty-source-credit-adapter.ts b/src/relay/ssh-pty-source-credit-adapter.ts
index e03c647c912..1c900fb9684 100644
--- a/src/relay/ssh-pty-source-credit-adapter.ts
+++ b/src/relay/ssh-pty-source-credit-adapter.ts
@@ -289,7 +289,10 @@ export class SshPtySourceCreditAdapter {
   }
 
   private cancelExact(token: string, identity: PtySourceDeliveryIdentity, reason: string): void {
-    if (this.sourceCredit.snapshot(identity).state !== 'closed') {
+    // Why: this runs from the bare grace setTimeout, where an evicted tombstone probing unknown
+    // would throw straight into uncaughtException.
+    const snapshot = this.sourceCredit.snapshotIfKnown(identity)
+    if (snapshot && snapshot.state !== 'closed') {
       const proof = this.sourceCredit.cancel(identity, reason)
       this.recentCancellations.remember(proof)
       this.publishCancellation?.(proof)

From 79251d7a9861568dc261faabfa16df5347d1d008 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Fri, 31 Jul 2026 06:08:26 -0700
Subject: [PATCH 20/23] [P2] fix(release,settings): restore signing preflight
 portability, bootstrap diagnostics, and skill re-check (#11692)

* fix(release): restore the SignPath composite action when cutting from an older ref

Co-authored-by: Orca <help@stably.ai>

* fix(startup): record a durable diagnostic before the bootstrap fatal-exit guard exits

Co-authored-by: Orca <help@stably.ai>

* fix(settings): make agent-skill Re-check rescan skill freshness

Co-authored-by: Orca <help@stably.ai>

* fix(startup): keep the bootstrap fatal diagnostic when the log override is unwritable

Create the parent directory an overridden ORCA_BOOTSTRAP_FATAL_LOG names and fall
back to the default location when that path still cannot be opened, so a missing
parent no longer costs the only account of the failure. Also pins the Re-check
freshness rescan to the completed install scan rather than the click.

Co-authored-by: Orca <help@stably.ai>

* refactor(settings): move the post-recheck surface sync out of the panel

Co-authored-by: Orca <help@stably.ai>

* fix(startup): retain diagnostics without node fs

* fix(skills): keep freshness scoped to the local runtime

* fix(settings): register freshness status translations

* fix(settings): scope and sequence skill freshness refreshes

* fix(settings): refresh freshness across runtime transitions

---------

Co-authored-by: Orca <help@stably.ai>
---
 .github/workflows/release-cut.yml             |  21 +++
 build-plugins/bootstrap-fatal-exit-banner.ts  | 107 ++++++++++++
 .../electron-vite-output-contract.test.ts     | 128 ++++++++++++++-
 ...windows-signing-workflow-contract.test.mjs |  35 ++++
 electron.vite.config.ts                       |  28 +---
 .../feature-wall/BrowserUseSkillSetupCard.tsx |   4 +-
 ...inalOrchestrationDialog.freshness.test.tsx | 143 ++++++++++++++++
 .../FloatingTerminalOrchestrationDialog.tsx   |  20 ++-
 .../AgentSkillSetupPanel.freshness.test.tsx   | 154 ++++++++++++++++++
 .../settings/AgentSkillSetupPanel.test.tsx    |  78 ++++++++-
 .../settings/AgentSkillSetupPanel.tsx         |  21 +--
 .../components/settings/CliSection.test.tsx   |  34 ++++
 .../src/components/settings/CliSection.tsx    |   4 +-
 .../settings/ComputerUseSkillSetupPanel.tsx   |   2 +-
 .../components/settings/EphemeralVmsPane.tsx  |   2 +-
 .../settings/LinearAgentSkillPane.test.tsx    |   3 +-
 .../MobileEmulatorAgentControlRow.test.tsx    |  59 +++++++
 .../MobileEmulatorAgentControlRow.tsx         |   6 +-
 .../components/settings/OrchestrationPane.tsx |   4 +-
 .../settings/OrchestrationSetupCard.tsx       |   2 +-
 .../src/components/settings/Settings.tsx      |   5 +-
 .../settings/TaskSourceLinearSetup.test.tsx   |   3 +-
 ...nt-skill-installed-command-callers.test.ts |  29 ++++
 .../agent-skill-recheck-surface-sync.ts       |  19 +++
 .../settings/use-linear-agent-skill-setup.ts  |   5 +-
 .../use-local-cli-skill-freshness-name.ts     |  10 ++
 .../skills/SkillFreshnessNudge.test.tsx       |  36 +++-
 .../components/skills/SkillFreshnessNudge.tsx |  22 ++-
 .../skills/SkillFreshnessStatusPill.test.tsx  |  26 ++-
 .../skills/SkillFreshnessStatusPill.tsx       |  16 +-
 .../SkillFreshnessUpdateDialog.test.tsx       |   4 +
 .../skills/SkillFreshnessUpdateDialog.tsx     |   4 +-
 .../useActiveProjectSkillRuntime.test.tsx     |  22 ++-
 .../src/hooks/useActiveProjectSkillRuntime.ts |  27 ++-
 .../src/hooks/useSkillFreshness.test.tsx      |  69 +++++++-
 src/renderer/src/hooks/useSkillFreshness.ts   |  66 +++++++-
 src/renderer/src/i18n/locales/en.json         |   4 +-
 37 files changed, 1122 insertions(+), 100 deletions(-)
 create mode 100644 build-plugins/bootstrap-fatal-exit-banner.ts
 create mode 100644 src/renderer/src/components/floating-terminal/FloatingTerminalOrchestrationDialog.freshness.test.tsx
 create mode 100644 src/renderer/src/components/settings/AgentSkillSetupPanel.freshness.test.tsx
 create mode 100644 src/renderer/src/components/settings/MobileEmulatorAgentControlRow.test.tsx
 create mode 100644 src/renderer/src/components/settings/agent-skill-recheck-surface-sync.ts
 create mode 100644 src/renderer/src/components/settings/use-local-cli-skill-freshness-name.ts

diff --git a/.github/workflows/release-cut.yml b/.github/workflows/release-cut.yml
index 1840514e5fd..6dba5ac1ff6 100644
--- a/.github/workflows/release-cut.yml
+++ b/.github/workflows/release-cut.yml
@@ -1015,6 +1015,27 @@ jobs:
         with:
           ref: refs/tags/${{ needs.cut.outputs.tag }}
 
+      # Why: `uses: ./…` resolves from the checked-out tag, not from the workflow
+      # ref, so cutting from an older/off-main ref whose tree predates a composite
+      # action would fail the step with "Can't find 'action.yml'". Restore the
+      # actions directory from the commit this workflow file itself came from.
+      - name: Restore composite actions from the workflow ref
+        if: matrix.platform == 'win'
+        shell: bash
+        env:
+          WORKFLOW_SHA: ${{ github.workflow_sha }}
+        run: |
+          set -euo pipefail
+          action_path=".github/actions/install-signpath-module/action.yml"
+          if [ -f "$action_path" ]; then
+            echo "Composite actions already present at the cut ref."
+            exit 0
+          fi
+          echo "Cut ref predates $action_path; restoring it from $WORKFLOW_SHA."
+          git fetch --no-tags --depth=1 origin "$WORKFLOW_SHA"
+          git checkout "$WORKFLOW_SHA" -- .github/actions
+          test -f "$action_path"
+
       # pnpm must be on PATH before setup-node so setup-node can locate the store for caching.
       - name: Setup pnpm
         uses: pnpm/action-setup@v6
diff --git a/build-plugins/bootstrap-fatal-exit-banner.ts b/build-plugins/bootstrap-fatal-exit-banner.ts
new file mode 100644
index 00000000000..de4da1319e5
--- /dev/null
+++ b/build-plugins/bootstrap-fatal-exit-banner.ts
@@ -0,0 +1,107 @@
+import { BOOTSTRAP_FATAL_EXIT_GUARD_KEY } from '../src/main/startup/bootstrap-fatal-exit-guard'
+export const BOOTSTRAP_FATAL_LOG_ENV_VAR = 'ORCA_BOOTSTRAP_FATAL_LOG'
+export const BOOTSTRAP_FATAL_LOG_FILE_NAME = 'bootstrap-fatal.log'
+const BOOTSTRAP_FATAL_LOG_MAX_BYTES = 262_144
+
+export function createBootstrapFatalExitBanner(): string {
+  // Why: Electron's pre-import error dialog can leave main resident and block NSIS replacement.
+  // Suppressing that dialog also removes the only account of the failure, so record one first:
+  // a partially copied resources tree otherwise exits silently on every launch, with nothing
+  // for the user or a support log to name the module that was missing.
+  return `
+;(() => {
+  const guardKey = ${JSON.stringify(BOOTSTRAP_FATAL_EXIT_GUARD_KEY)}
+  if (typeof globalThis[guardKey] === 'function') {
+    return
+  }
+  const describeBootstrapError = (error) => {
+    try {
+      const detail = error && typeof error === 'object' && error.stack ? error.stack : error
+      return String(detail).split('\\n').slice(0, 12).join(' | ').slice(0, 4000)
+    } catch {
+      return '<unprintable error>'
+    }
+  }
+  const readBootstrapFatalLogOverride = () => {
+    const override = typeof process.env === 'object' && process.env ? process.env.${BOOTSTRAP_FATAL_LOG_ENV_VAR} : undefined
+    return typeof override === 'string' && override.length > 0 ? override : undefined
+  }
+  const resolveDefaultBootstrapFatalLogPath = () => {
+    let directory
+    try {
+      directory = require('electron').app.getPath('userData')
+    } catch {
+      // Why: a bootstrap fault can predate a usable app object; temp still outlives the process.
+      directory = require('node:os').tmpdir()
+    }
+    return require('node:path').join(directory, ${JSON.stringify(BOOTSTRAP_FATAL_LOG_FILE_NAME)})
+  }
+  const appendBootstrapFatalLine = (fs, logPath, entry) => {
+    try {
+      // Why: an override can name a directory nothing has created yet, and a missing
+      // parent would drop the only account of the failure.
+      fs.mkdirSync(require('node:path').dirname(logPath), { recursive: true })
+      // Why: a broken install repeats this on every relaunch; keep the trail bounded.
+      let flags = 'a'
+      try {
+        flags = fs.statSync(logPath).size > ${BOOTSTRAP_FATAL_LOG_MAX_BYTES} ? 'w' : 'a'
+      } catch {
+        flags = 'a'
+      }
+      const descriptor = fs.openSync(logPath, flags, 0o600)
+      try {
+        fs.writeSync(descriptor, entry)
+      } finally {
+        fs.closeSync(descriptor)
+      }
+      return true
+    } catch {
+      return false
+    }
+  }
+  const recordBootstrapFailure = (error) => {
+    const line = '[bootstrap] fatal-exit pid=' + process.pid + ' error=' + describeBootstrapError(error) + '\\n'
+    let fs
+    try {
+      fs = require('node:fs')
+    } catch {
+      fs = undefined
+    }
+    try {
+      fs.writeSync(2, line)
+    } catch {
+      try {
+        process.stderr.write(line)
+      } catch {
+        // Diagnostics must never replace the exit below.
+      }
+    }
+    try {
+      const entry = new Date().toISOString() + ' ' + line
+      const override = readBootstrapFatalLogOverride()
+      // Why: an unwritable override must cost the user a location, not the diagnostic.
+      if (!override || !appendBootstrapFatalLine(fs, override, entry)) {
+        appendBootstrapFatalLine(fs, resolveDefaultBootstrapFatalLogPath(), entry)
+      }
+    } catch {
+      // Diagnostics must never replace the exit below.
+    }
+  }
+  let exitScheduled = false
+  const exitAfterBootstrapFailure = (error) => {
+    if (exitScheduled) {
+      return
+    }
+    exitScheduled = true
+    recordBootstrapFailure(error)
+    process.exitCode = 1
+    setImmediate(() => process.exit(1))
+  }
+  globalThis[guardKey] = () => {
+    process.off('uncaughtException', exitAfterBootstrapFailure)
+    delete globalThis[guardKey]
+  }
+  process.once('uncaughtException', exitAfterBootstrapFailure)
+})();
+`
+}
diff --git a/config/scripts/electron-vite-output-contract.test.ts b/config/scripts/electron-vite-output-contract.test.ts
index 1154ec9cc57..931f9b93d01 100644
--- a/config/scripts/electron-vite-output-contract.test.ts
+++ b/config/scripts/electron-vite-output-contract.test.ts
@@ -1,13 +1,72 @@
-import { readFileSync } from 'node:fs'
+import * as nodeFs from 'node:fs'
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import * as nodePath from 'node:path'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
 import { EventEmitter } from 'node:events'
 import { runInNewContext } from 'node:vm'
 import { describe, expect, it } from 'vitest'
-import { createBootstrapFatalExitBanner, electronViteConfig } from '../../electron.vite.config'
+import {
+  BOOTSTRAP_FATAL_LOG_ENV_VAR,
+  BOOTSTRAP_FATAL_LOG_FILE_NAME,
+  createBootstrapFatalExitBanner
+} from '../../build-plugins/bootstrap-fatal-exit-banner'
+import { electronViteConfig } from '../../electron.vite.config'
 import { BOOTSTRAP_FATAL_EXIT_GUARD_KEY } from '../../src/main/startup/bootstrap-fatal-exit-guard'
 
 const targetConfig = readFileSync('config/electron-vite-target.config.ts', 'utf8')
 const devRunner = readFileSync('config/scripts/run-electron-vite-dev.mjs', 'utf8')
 
+type BootstrapProcessMock = EventEmitter & {
+  env: Record<string, string>
+  pid: number
+  exit: (code: number) => void
+  exitCode?: number
+}
+
+/** Runs the banner in a bare context and raises the bootstrap fault it guards against. */
+function failBootstrapWithBanner(options: {
+  env: Record<string, string>
+  tmpdir?: string
+  stderrWrites?: string[]
+}): BootstrapProcessMock {
+  const processMock = new EventEmitter() as BootstrapProcessMock
+  processMock.env = options.env
+  processMock.pid = 4242
+  processMock.exit = () => {}
+  const fsShim = {
+    ...nodeFs,
+    writeSync: (descriptor: number, data: string) => {
+      if (descriptor === 2) {
+        options.stderrWrites?.push(data)
+        return data.length
+      }
+      return nodeFs.writeSync(descriptor, data)
+    }
+  }
+  const context = {
+    process: processMock,
+    setImmediate: () => {},
+    require: (specifier: string) => {
+      if (specifier === 'node:fs') {
+        return fsShim
+      }
+      if (specifier === 'node:path') {
+        return nodePath
+      }
+      if (specifier === 'node:os' && options.tmpdir !== undefined) {
+        return { tmpdir: () => options.tmpdir }
+      }
+      // Electron's own module is unreachable from a bootstrap fault this early.
+      throw new Error(`unexpected require: ${specifier}`)
+    }
+  }
+
+  runInNewContext(createBootstrapFatalExitBanner(), context)
+  processMock.emit('uncaughtException', new Error("Cannot find module 'ws'"))
+  return processMock
+}
+
 describe('Electron Vite output contract', () => {
   it('keeps main-process and plain-Node entries at stable CommonJS paths', () => {
     const output = electronViteConfig.main?.build?.rollupOptions?.output
@@ -40,12 +99,20 @@ describe('Electron Vite output contract', () => {
     const processMock = new EventEmitter() as EventEmitter & {
       exit: (code: number) => void
       exitCode?: number
+      stderr: { write: (chunk: string) => boolean }
     }
     let scheduledExit: (() => void) | null = null
     let exitedWith: number | null = null
+    const stderrWrites: string[] = []
     processMock.exit = (code) => {
       exitedWith = code
     }
+    processMock.stderr = {
+      write: (chunk) => {
+        stderrWrites.push(chunk)
+        return true
+      }
+    }
     const context = {
       process: processMock,
       setImmediate: (callback: () => void) => {
@@ -61,6 +128,63 @@ describe('Electron Vite output contract', () => {
     scheduledExit?.()
     expect(exitedWith).toBe(1)
     expect(context).toHaveProperty(BOOTSTRAP_FATAL_EXIT_GUARD_KEY)
+    expect(stderrWrites.join('')).toContain("Cannot find module 'zod'")
+  })
+
+  it('records the bootstrap failure it exits on, since the guard hides Electron dialog', () => {
+    const logDirectory = mkdtempSync(join(tmpdir(), 'orca-bootstrap-fatal-'))
+    const logPath = join(logDirectory, 'fatal.log')
+    const stderrWrites: string[] = []
+
+    try {
+      const processMock = failBootstrapWithBanner({
+        env: { [BOOTSTRAP_FATAL_LOG_ENV_VAR]: logPath },
+        stderrWrites
+      })
+
+      expect(stderrWrites.join('')).toContain("Cannot find module 'ws'")
+      const recorded = readFileSync(logPath, 'utf8')
+      expect(recorded).toContain("Cannot find module 'ws'")
+      expect(recorded).toContain('pid=4242')
+      expect(processMock.exitCode).toBe(1)
+    } finally {
+      rmSync(logDirectory, { recursive: true, force: true })
+    }
+  })
+
+  it('creates the parent directory an overridden log path names but does not have', () => {
+    const logDirectory = mkdtempSync(join(tmpdir(), 'orca-bootstrap-fatal-'))
+    const logPath = join(logDirectory, 'nested', 'diagnostics', 'fatal.log')
+
+    try {
+      const processMock = failBootstrapWithBanner({
+        env: { [BOOTSTRAP_FATAL_LOG_ENV_VAR]: logPath }
+      })
+
+      expect(readFileSync(logPath, 'utf8')).toContain("Cannot find module 'ws'")
+      expect(processMock.exitCode).toBe(1)
+    } finally {
+      rmSync(logDirectory, { recursive: true, force: true })
+    }
+  })
+
+  it('falls back to the default location when the overridden log path is unwritable', () => {
+    const logDirectory = mkdtempSync(join(tmpdir(), 'orca-bootstrap-fatal-'))
+    const fallbackDirectory = join(logDirectory, 'fallback')
+
+    try {
+      const processMock = failBootstrapWithBanner({
+        // A directory can never be opened as the log file, so the override must yield.
+        env: { [BOOTSTRAP_FATAL_LOG_ENV_VAR]: logDirectory },
+        tmpdir: fallbackDirectory
+      })
+
+      const recorded = readFileSync(join(fallbackDirectory, BOOTSTRAP_FATAL_LOG_FILE_NAME), 'utf8')
+      expect(recorded).toContain("Cannot find module 'ws'")
+      expect(processMock.exitCode).toBe(1)
+    } finally {
+      rmSync(logDirectory, { recursive: true, force: true })
+    }
   })
 
   it('isolates renderer entry side effects behind strict facades', () => {
diff --git a/config/scripts/windows-signing-workflow-contract.test.mjs b/config/scripts/windows-signing-workflow-contract.test.mjs
index fc2087379f8..b5a8f41d01f 100644
--- a/config/scripts/windows-signing-workflow-contract.test.mjs
+++ b/config/scripts/windows-signing-workflow-contract.test.mjs
@@ -104,6 +104,41 @@ describe('Windows signing workflow contract', () => {
     expect(installRun).toContain('throw "Unable to install the SignPath PowerShell module')
   })
 
+  it('still installs SignPath when the cut ref predates the composite action', () => {
+    const parsedWorkflow = readWorkflow('.github/workflows/release-cut.yml')
+    const steps = parsedWorkflow.jobs.build.steps
+    const stepNames = steps.map((step) => step.name)
+    const checkoutIndex = stepNames.indexOf('Checkout')
+    const restoreIndex = stepNames.indexOf('Restore composite actions from the workflow ref')
+    const installIndex = stepNames.indexOf('Install SignPath PowerShell module')
+
+    // Why: the build job checks out the cut tag, which for a hotfix cut from an
+    // older ref can predate `.github/actions/install-signpath-module`; without
+    // this restore the `uses: ./…` step dies on a missing action.yml.
+    expect(restoreIndex).toBeGreaterThan(checkoutIndex)
+    expect(restoreIndex).toBeLessThan(installIndex)
+
+    const restoreStep = steps[restoreIndex]
+    const restoreRun = restoreStep.run
+
+    expect(restoreStep.env.WORKFLOW_SHA).toBe('${{ github.workflow_sha }}')
+    expect(restoreRun).toContain('.github/actions/install-signpath-module/action.yml')
+    expect(restoreRun).toContain('git fetch --no-tags --depth=1 origin "$WORKFLOW_SHA"')
+    expect(restoreRun).toContain('git checkout "$WORKFLOW_SHA" -- .github/actions')
+
+    // Why: restoring the action must not turn signing into a soft dependency —
+    // a missing module still has to fail the Windows job, and the CDN fallback
+    // still has to reject an unexpected payload.
+    expect(steps[installIndex]['continue-on-error']).toBeUndefined()
+    expect(restoreStep['continue-on-error']).toBeUndefined()
+
+    const installRun = readWorkflow('.github/actions/install-signpath-module/action.yml').runs
+      .steps[0].run
+
+    expect(installRun).toContain('$actualHash -ne $expectedHash.ToUpperInvariant()')
+    expect(installRun).toContain('throw "SHA-256 mismatch for $source')
+  })
+
   it('shares one SignPath module install path between release and rehearsal', () => {
     const rehearsalWorkflow = readWorkflow('.github/workflows/windows-signing-rehearsal.yml')
     const stepNames = rehearsalWorkflow.jobs.rehearse.steps.map((step) => step.name)
diff --git a/electron.vite.config.ts b/electron.vite.config.ts
index 957e3f60b38..02239421ae9 100644
--- a/electron.vite.config.ts
+++ b/electron.vite.config.ts
@@ -3,6 +3,7 @@ import { resolve } from 'node:path'
 import { defineConfig, type UserConfig } from 'electron-vite'
 import react from '@vitejs/plugin-react'
 import tailwindcss from '@tailwindcss/vite'
+import { createBootstrapFatalExitBanner } from './build-plugins/bootstrap-fatal-exit-banner'
 import { createPlainNodeEntryGuardPlugin } from './build-plugins/plain-node-entry-guard'
 import packageJson from './package.json' with { type: 'json' }
 
@@ -16,7 +17,6 @@ const BUNDLED_MAIN_DEPENDENCIES = new Set([
 const EXTERNAL_MAIN_DEPENDENCIES = Object.keys(packageJson.dependencies).filter(
   (dependency) => !BUNDLED_MAIN_DEPENDENCIES.has(dependency)
 )
-const BOOTSTRAP_FATAL_EXIT_GUARD_KEY = '__ORCA_BOOTSTRAP_FATAL_EXIT_GUARD__'
 
 function isExternalMainModule(source: string): boolean {
   if (isBuiltin(source) || source === 'electron' || source.startsWith('electron/')) {
@@ -171,32 +171,6 @@ function createStartupDiagnosticsBanner(chunkName: string): string {
 `
 }
 
-export function createBootstrapFatalExitBanner(): string {
-  // Why: Electron's pre-import error dialog can leave main resident and block NSIS replacement.
-  return `
-;(() => {
-  const guardKey = ${JSON.stringify(BOOTSTRAP_FATAL_EXIT_GUARD_KEY)}
-  if (typeof globalThis[guardKey] === 'function') {
-    return
-  }
-  let exitScheduled = false
-  const exitAfterBootstrapFailure = () => {
-    if (exitScheduled) {
-      return
-    }
-    exitScheduled = true
-    process.exitCode = 1
-    setImmediate(() => process.exit(1))
-  }
-  globalThis[guardKey] = () => {
-    process.off('uncaughtException', exitAfterBootstrapFailure)
-    delete globalThis[guardKey]
-  }
-  process.once('uncaughtException', exitAfterBootstrapFailure)
-})();
-`
-}
-
 function createMainBootstrapPlugin() {
   return {
     name: 'orca-main-bootstrap',
diff --git a/src/renderer/src/components/feature-wall/BrowserUseSkillSetupCard.tsx b/src/renderer/src/components/feature-wall/BrowserUseSkillSetupCard.tsx
index 87e733f76d0..bac0e6d258f 100644
--- a/src/renderer/src/components/feature-wall/BrowserUseSkillSetupCard.tsx
+++ b/src/renderer/src/components/feature-wall/BrowserUseSkillSetupCard.tsx
@@ -75,10 +75,8 @@ export function BrowserUseSkillSetupCard(props: {
       onBeforeOpenTerminal={handleBeforeOpenTerminal}
       showRecheckWhenInstalled={false}
       onRecheck={skill.refresh}
-      // Why: the local-host-only freshness scan cannot vouch for a WSL runtime,
-      // so fall back to the presence-only pill there (mirrors the settings cards).
       freshnessSkillName={
-        activeSkillRuntime.agentRuntime?.runtime === 'wsl' ? undefined : ORCA_CLI_SKILL_NAME
+        activeSkillRuntime.canUseLocalSkillFreshness ? ORCA_CLI_SKILL_NAME : undefined
       }
     />
   )
diff --git a/src/renderer/src/components/floating-terminal/FloatingTerminalOrchestrationDialog.freshness.test.tsx b/src/renderer/src/components/floating-terminal/FloatingTerminalOrchestrationDialog.freshness.test.tsx
new file mode 100644
index 00000000000..187e161eccc
--- /dev/null
+++ b/src/renderer/src/components/floating-terminal/FloatingTerminalOrchestrationDialog.freshness.test.tsx
@@ -0,0 +1,143 @@
+// @vitest-environment happy-dom
+
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { SkillFreshnessInventory } from '../../../../shared/skill-freshness'
+import { _skillFreshnessCacheForTests } from '@/hooks/useSkillFreshness'
+import { FloatingTerminalOrchestrationDialog } from './FloatingTerminalOrchestrationDialog'
+
+const mocks = vi.hoisted(() => ({
+  canUseLocalSkillFreshness: true,
+  refreshOrchestrationSkill: vi.fn(async () => true),
+  recordFeatureInteraction: vi.fn()
+}))
+
+vi.mock('@/hooks/useActiveProjectSkillRuntime', () => ({
+  useActiveProjectSkillRuntime: () => ({
+    agentRuntime: undefined,
+    discoveryTarget: undefined,
+    terminalShellOverride: undefined,
+    installDisabledReason: null,
+    canUseLocalSkillFreshness: mocks.canUseLocalSkillFreshness
+  })
+}))
+
+vi.mock('@/hooks/useInstalledAgentSkills', () => ({
+  GLOBAL_AGENT_SKILL_SOURCE_KINDS: ['home'],
+  useInstalledAgentSkill: () => ({
+    installed: true,
+    loading: false,
+    error: null,
+    refresh: mocks.refreshOrchestrationSkill
+  }),
+  notifyInstalledAgentSkillsChanged: vi.fn(),
+  notifyInstalledAgentSkillsRefreshed: vi.fn()
+}))
+
+vi.mock('@/components/settings/CliSkillRuntimeSetup', () => ({
+  buildSkillCommandForRuntime: (command: string) => command,
+  ensureWslCliAvailableForAgentSkillTerminal: vi.fn(),
+  getWslCliDistroRequest: () => undefined
+}))
+
+vi.mock('@/components/onboarding/OnboardingInlineCommandTerminal', () => ({
+  OnboardingInlineCommandTerminal: () => null
+}))
+
+vi.mock('@/store', () => ({
+  useAppStore: Object.assign(() => undefined, {
+    getState: () => ({ recordFeatureInteraction: mocks.recordFeatureInteraction })
+  })
+}))
+
+function inventory(eligibleUpdateNames: string[]): SkillFreshnessInventory {
+  return { schemaVersion: 1, installations: [], eligibleUpdateNames, scanIssues: [], scannedAt: 1 }
+}
+
+let root: Root | null = null
+let container: HTMLDivElement | null = null
+
+function recheckButton(): HTMLButtonElement | undefined {
+  return Array.from(document.body.querySelectorAll('button')).find(
+    (candidate) => candidate.textContent?.trim() === 'Re-check'
+  )
+}
+
+async function renderDialog(): Promise<void> {
+  await act(async () => {
+    root?.render(
+      <FloatingTerminalOrchestrationDialog
+        open
+        onOpenChange={vi.fn()}
+        onSetupStateChange={vi.fn()}
+      />
+    )
+  })
+  await act(async () => {})
+}
+
+describe('FloatingTerminalOrchestrationDialog freshness', () => {
+  beforeEach(() => {
+    _skillFreshnessCacheForTests.reset()
+    mocks.canUseLocalSkillFreshness = true
+    mocks.refreshOrchestrationSkill.mockClear()
+    container = document.createElement('div')
+    document.body.appendChild(container)
+    root = createRoot(container)
+  })
+
+  afterEach(async () => {
+    if (root) {
+      await act(async () => root?.unmount())
+    }
+    root = null
+    container?.remove()
+    container = null
+    Reflect.deleteProperty(window, 'api')
+  })
+
+  it('refreshes the local freshness verdict after presence re-check completes', async () => {
+    const freshnessInventory = vi
+      .fn()
+      .mockResolvedValueOnce(inventory(['orchestration']))
+      .mockResolvedValueOnce(inventory([]))
+    window.api = {
+      skills: { freshnessInventory },
+      cli: { getInstallStatus: vi.fn().mockResolvedValue({ onPath: true }) }
+    } as never
+
+    await renderDialog()
+    expect(freshnessInventory).toHaveBeenCalledOnce()
+    expect(document.body.textContent).toContain('Update available')
+
+    await act(async () => {
+      recheckButton()?.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+    })
+    await act(async () => {})
+
+    expect(mocks.refreshOrchestrationSkill).toHaveBeenCalledOnce()
+    expect(freshnessInventory).toHaveBeenCalledTimes(2)
+    expect(document.body.textContent).not.toContain('Update available')
+  })
+
+  it('never reads client freshness for an SSH-owned skill', async () => {
+    mocks.canUseLocalSkillFreshness = false
+    const freshnessInventory = vi.fn().mockResolvedValue(inventory([]))
+    window.api = {
+      skills: { freshnessInventory },
+      cli: { getInstallStatus: vi.fn().mockResolvedValue({ onPath: true }) }
+    } as never
+
+    await renderDialog()
+    expect(document.body.textContent).toContain('Installed')
+
+    await act(async () => {
+      recheckButton()?.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+    })
+    await act(async () => {})
+
+    expect(mocks.refreshOrchestrationSkill).toHaveBeenCalledOnce()
+    expect(freshnessInventory).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/renderer/src/components/floating-terminal/FloatingTerminalOrchestrationDialog.tsx b/src/renderer/src/components/floating-terminal/FloatingTerminalOrchestrationDialog.tsx
index 6f9aed3f2e8..06f87ac3844 100644
--- a/src/renderer/src/components/floating-terminal/FloatingTerminalOrchestrationDialog.tsx
+++ b/src/renderer/src/components/floating-terminal/FloatingTerminalOrchestrationDialog.tsx
@@ -23,6 +23,7 @@ import {
   useInstalledAgentSkill
 } from '@/hooks/useInstalledAgentSkills'
 import { useActiveProjectSkillRuntime } from '@/hooks/useActiveProjectSkillRuntime'
+import { refreshSkillFreshness } from '@/hooks/useSkillFreshness'
 import { useAppStore } from '@/store'
 import {
   buildSkillCommandForRuntime,
@@ -74,6 +75,14 @@ export function FloatingTerminalOrchestrationDialog({
     }
   }, [orchestrationSkillDetected, onSetupStateChange])
 
+  const recheckOrchestrationSkill = async (): Promise<boolean> => {
+    const installed = await refreshOrchestrationSkill()
+    if (activeSkillRuntime.canUseLocalSkillFreshness) {
+      await refreshSkillFreshness()
+    }
+    return installed
+  }
+
   return (
     <Dialog open={open} onOpenChange={onOpenChange}>
       <DialogContent className="gap-4 sm:max-w-[620px]">
@@ -95,18 +104,15 @@ export function FloatingTerminalOrchestrationDialog({
                 )}
               </IntegrationStatusPill>
             ) : orchestrationSkillDetected ? (
-              // Why: the modal owns the status pill, so it must carry the same
-              // freshness signal — and route to the same review dialog — as the
-              // settings card for this skill; WSL falls back to presence-only.
-              activeSkillRuntime.agentRuntime?.runtime === 'wsl' ? (
+              activeSkillRuntime.canUseLocalSkillFreshness ? (
+                <SkillFreshnessStatusPill skillName={ORCHESTRATION_SKILL_NAME} />
+              ) : (
                 <IntegrationStatusPill tone="connected">
                   {translate(
                     'auto.components.floating.terminal.FloatingTerminalOrchestrationDialog.630c0ac8c8',
                     'Installed'
                   )}
                 </IntegrationStatusPill>
-              ) : (
-                <SkillFreshnessStatusPill skillName={ORCHESTRATION_SKILL_NAME} />
               )
             ) : (
               <IntegrationStatusPill tone="attention">
@@ -161,7 +167,7 @@ export function FloatingTerminalOrchestrationDialog({
               ? ensureWslCliAvailableForAgentSkillTerminal(activeSkillRuntime.agentRuntime)
               : ensureOrcaCliAvailableForAgentSkillTerminal())
           }}
-          onRecheck={refreshOrchestrationSkill}
+          onRecheck={recheckOrchestrationSkill}
         />
       </DialogContent>
     </Dialog>
diff --git a/src/renderer/src/components/settings/AgentSkillSetupPanel.freshness.test.tsx b/src/renderer/src/components/settings/AgentSkillSetupPanel.freshness.test.tsx
new file mode 100644
index 00000000000..ab2fc353b47
--- /dev/null
+++ b/src/renderer/src/components/settings/AgentSkillSetupPanel.freshness.test.tsx
@@ -0,0 +1,154 @@
+// @vitest-environment happy-dom
+
+import { act, type ComponentProps } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { SkillFreshnessInventory } from '../../../../shared/skill-freshness'
+import { _skillFreshnessCacheForTests } from '@/hooks/useSkillFreshness'
+import { AgentSkillSetupPanel } from './AgentSkillSetupPanel'
+
+const mocks = vi.hoisted(() => ({
+  skillsChanged: vi.fn(),
+  skillsRefreshed: vi.fn()
+}))
+
+vi.mock('@/hooks/useInstalledAgentSkills', () => ({
+  notifyInstalledAgentSkillsChanged: mocks.skillsChanged,
+  notifyInstalledAgentSkillsRefreshed: mocks.skillsRefreshed
+}))
+
+vi.mock('../onboarding/OnboardingInlineCommandTerminal', () => ({
+  OnboardingInlineCommandTerminal: () => null
+}))
+
+function inventory(eligibleUpdateNames: string[]): SkillFreshnessInventory {
+  return { schemaVersion: 1, installations: [], eligibleUpdateNames, scanIssues: [], scannedAt: 1 }
+}
+
+function panelProps(
+  onRecheck: () => void | Promise<unknown> = vi.fn()
+): ComponentProps<typeof AgentSkillSetupPanel> {
+  return {
+    title: 'Linear skill',
+    description: null,
+    command: 'npx skills add orca-linear --global',
+    terminalTitle: 'Linear skill setup',
+    terminalAriaLabel: 'Linear skill install terminal',
+    terminalWorktreeId: 'settings-linear-skill-terminal',
+    installed: true,
+    loading: false,
+    error: null,
+    hideHeader: true,
+    showRecheckWhenInstalled: true,
+    freshnessSkillName: 'orca-linear',
+    onRecheck
+  }
+}
+
+let root: Root | null = null
+let container: HTMLDivElement | null = null
+
+describe('AgentSkillSetupPanel freshness re-check', () => {
+  beforeEach(() => {
+    _skillFreshnessCacheForTests.reset()
+    mocks.skillsChanged.mockReset()
+    mocks.skillsRefreshed.mockReset()
+    container = document.createElement('div')
+    document.body.appendChild(container)
+    root = createRoot(container)
+  })
+
+  afterEach(async () => {
+    if (root) {
+      await act(async () => root?.unmount())
+    }
+    root = null
+    container?.remove()
+    container = null
+    Reflect.deleteProperty(window, 'api')
+  })
+
+  it('rescans skill freshness and updates the rendered verdict on re-check', async () => {
+    let completeRecheck: (() => void) | null = null
+    // Why: a rescan started before the install scan finishes would re-read the same
+    // pre-update disk state, so the boundary is what the assertions below pin.
+    const onRecheck = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          completeRecheck = resolve
+        })
+    )
+    let completeRescan: ((value: SkillFreshnessInventory) => void) | null = null
+    const freshnessInventory = vi
+      .fn()
+      .mockResolvedValueOnce(inventory(['orca-linear']))
+      .mockImplementationOnce(
+        () =>
+          new Promise<SkillFreshnessInventory>((resolve) => {
+            completeRescan = resolve
+          })
+      )
+    window.api = { skills: { freshnessInventory } } as never
+
+    await act(async () => root?.render(<AgentSkillSetupPanel {...panelProps(onRecheck)} />))
+    await act(async () => {})
+
+    expect(freshnessInventory).toHaveBeenCalledTimes(1)
+    expect(container?.textContent).toContain('Update available')
+
+    const recheck = Array.from(container?.querySelectorAll('button') ?? []).find(
+      (candidate) => candidate.textContent?.trim() === 'Re-check'
+    )
+    expect(recheck).toBeDefined()
+
+    await act(async () => {
+      recheck?.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+    })
+    await act(async () => {})
+
+    expect(onRecheck).toHaveBeenCalledOnce()
+    expect(mocks.skillsRefreshed).not.toHaveBeenCalled()
+    expect(freshnessInventory).toHaveBeenCalledTimes(1)
+
+    await act(async () => {
+      completeRecheck?.()
+    })
+    await act(async () => {})
+
+    expect(mocks.skillsRefreshed).toHaveBeenCalledOnce()
+    expect(freshnessInventory).toHaveBeenCalledTimes(2)
+    expect(container?.textContent).toContain('Checking...')
+    expect(container?.textContent).not.toContain('Update available')
+
+    await act(async () => {
+      completeRescan?.(inventory([]))
+    })
+    await act(async () => {})
+
+    expect(container?.textContent).not.toContain('Checking...')
+    expect(container?.textContent).not.toContain('Update available')
+  })
+
+  it('shows a failed verdict when the post-recheck inventory scan fails', async () => {
+    const freshnessInventory = vi
+      .fn()
+      .mockResolvedValueOnce(inventory(['orca-linear']))
+      .mockRejectedValueOnce(new Error('inventory unavailable'))
+    window.api = { skills: { freshnessInventory } } as never
+
+    await act(async () => root?.render(<AgentSkillSetupPanel {...panelProps()} />))
+    await act(async () => {})
+
+    const recheck = Array.from(container?.querySelectorAll('button') ?? []).find(
+      (candidate) => candidate.textContent?.trim() === 'Re-check'
+    )
+    await act(async () => {
+      recheck?.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+    })
+    await act(async () => {})
+
+    expect(container?.textContent).toContain('Check failed')
+    expect(container?.textContent).not.toContain('Installed')
+    expect(container?.textContent).not.toContain('Up to date')
+  })
+})
diff --git a/src/renderer/src/components/settings/AgentSkillSetupPanel.test.tsx b/src/renderer/src/components/settings/AgentSkillSetupPanel.test.tsx
index ac44ed3285c..158ac81c408 100644
--- a/src/renderer/src/components/settings/AgentSkillSetupPanel.test.tsx
+++ b/src/renderer/src/components/settings/AgentSkillSetupPanel.test.tsx
@@ -22,6 +22,7 @@ const mocks = vi.hoisted(() => ({
   toastSuccess: vi.fn(),
   skillsChanged: vi.fn(),
   skillsRefreshed: vi.fn(),
+  freshnessRefresh: vi.fn(),
   terminalInstanceCount: 0
 }))
 
@@ -37,6 +38,10 @@ vi.mock('@/hooks/useInstalledAgentSkills', () => ({
   notifyInstalledAgentSkillsRefreshed: mocks.skillsRefreshed
 }))
 
+vi.mock('@/hooks/useSkillFreshness', () => ({
+  refreshSkillFreshness: mocks.freshnessRefresh
+}))
+
 vi.mock('../onboarding/OnboardingInlineCommandTerminal', () => ({
   OnboardingInlineCommandTerminal: (props: {
     command: string
@@ -155,6 +160,8 @@ describe('AgentSkillSetupPanel', () => {
     mocks.toastSuccess.mockReset()
     mocks.skillsChanged.mockReset()
     mocks.skillsRefreshed.mockReset()
+    mocks.freshnessRefresh.mockReset()
+    mocks.freshnessRefresh.mockResolvedValue(undefined)
     mocks.terminalInstanceCount = 0
     Object.defineProperty(window, 'api', {
       configurable: true,
@@ -288,6 +295,50 @@ describe('AgentSkillSetupPanel', () => {
     expect(mocks.skillsChanged).not.toHaveBeenCalled()
   })
 
+  it('rechecks presence without invalidating local freshness when no local verdict exists', async () => {
+    const onRecheck = vi.fn(async () => {})
+    await renderInteractivePanel({ onRecheck })
+    await clickButton('Install')
+
+    await act(async () => {
+      mocks.terminalProps.at(-1)?.onCommandFinished?.(0)
+      mocks.terminalProps.at(-1)?.onTerminalExit?.()
+    })
+    await act(async () => {})
+
+    expect(onRecheck).toHaveBeenCalledOnce()
+    expect(mocks.skillsRefreshed).toHaveBeenCalledOnce()
+    expect(mocks.skillsChanged).not.toHaveBeenCalled()
+    expect(mocks.freshnessRefresh).not.toHaveBeenCalled()
+  })
+
+  it('refreshes first-install freshness only after the terminal re-check finishes', async () => {
+    let finishRecheck: (() => void) | null = null
+    const recheck = new Promise<void>((resolve) => {
+      finishRecheck = resolve
+    })
+    const onRecheck = vi.fn(() => recheck)
+    await renderInteractivePanel({ freshnessSkillName: 'orca-cli', onRecheck })
+    await clickButton('Install')
+
+    await act(async () => {
+      mocks.terminalProps.at(-1)?.onTerminalExit?.()
+    })
+
+    expect(onRecheck).toHaveBeenCalledOnce()
+    expect(mocks.freshnessRefresh).not.toHaveBeenCalled()
+    expect(mocks.skillsRefreshed).not.toHaveBeenCalled()
+
+    await act(async () => {
+      finishRecheck?.()
+      await recheck
+    })
+
+    expect(mocks.skillsChanged).not.toHaveBeenCalled()
+    expect(mocks.skillsRefreshed).toHaveBeenCalledOnce()
+    expect(mocks.freshnessRefresh).toHaveBeenCalledOnce()
+  })
+
   it('opens not-installed setup with the install command for preview, copy, and terminal', async () => {
     await renderInteractivePanel({ installedCommand: UPDATE_COMMAND })
 
@@ -499,9 +550,12 @@ describe('AgentSkillSetupPanel', () => {
     expect(mocks.terminalProps.at(-1)).toMatchObject({ command: UPDATE_COMMAND })
   })
 
-  it('invalidates shared skill state before the direct completion re-check', async () => {
+  it('refreshes shared skill state after the direct completion re-check', async () => {
     const calls: string[] = []
-    mocks.skillsChanged.mockImplementation(() => calls.push('invalidate'))
+    mocks.skillsRefreshed.mockImplementation(() => calls.push('presence'))
+    mocks.freshnessRefresh.mockImplementation(async () => {
+      calls.push('freshness')
+    })
     const onRecheck = vi.fn(() => {
       calls.push('recheck')
     })
@@ -513,7 +567,25 @@ describe('AgentSkillSetupPanel', () => {
       mocks.terminalProps.at(-1)?.onCommandFinished?.(0)
     })
 
-    expect(calls).toEqual(['invalidate', 'recheck'])
+    expect(calls).toEqual(['recheck', 'presence', 'freshness'])
+  })
+
+  it('rechecks once when command completion is followed by terminal exit', async () => {
+    const onRecheck = vi.fn()
+    await renderInteractivePanel({ freshnessSkillName: 'orca-cli', onRecheck })
+    await clickButton('Install')
+
+    await act(async () => {
+      mocks.terminalProps.at(-1)?.onCommandFinished?.(0)
+    })
+    await act(async () => {
+      mocks.terminalProps.at(-1)?.onTerminalExit?.()
+    })
+    await act(async () => {})
+
+    expect(onRecheck).toHaveBeenCalledOnce()
+    expect(mocks.skillsRefreshed).toHaveBeenCalledOnce()
+    expect(mocks.freshnessRefresh).toHaveBeenCalledOnce()
   })
 
   it('re-enables Install after the setup shell exits so a failed attempt can retry', async () => {
diff --git a/src/renderer/src/components/settings/AgentSkillSetupPanel.tsx b/src/renderer/src/components/settings/AgentSkillSetupPanel.tsx
index c141b9bf472..ee021d9698d 100644
--- a/src/renderer/src/components/settings/AgentSkillSetupPanel.tsx
+++ b/src/renderer/src/components/settings/AgentSkillSetupPanel.tsx
@@ -8,11 +8,11 @@ import { AgentSkillSetupFailureNotice } from './AgentSkillSetupFailureNotice'
 import type { AgentSkillSetupPanelProps } from './agent-skill-setup-panel-props'
 import { Button } from '../ui/button'
 import { Tooltip, TooltipContent, TooltipTrigger } from '../ui/tooltip'
-import {
-  notifyInstalledAgentSkillsChanged,
-  notifyInstalledAgentSkillsRefreshed
-} from '@/hooks/useInstalledAgentSkills'
 import { useMountedRef } from '@/hooks/useMountedRef'
+import {
+  recheckSurfacesAfterAgentSkillTerminal,
+  syncSurfacesAfterAgentSkillRecheck
+} from './agent-skill-recheck-surface-sync'
 import { isOrcaCliAvailableOnPath } from '@/lib/agent-skill-cli-prerequisite'
 import { cn } from '@/lib/utils'
 import { translate } from '@/i18n/i18n'
@@ -122,22 +122,20 @@ export function AgentSkillSetupPanel({
       if (bestEffortExitCode !== null) {
         setSetupCommandFailedCode(bestEffortExitCode === 0 ? null : bestEffortExitCode)
       }
-      if (freshnessSkillName) {
-        notifyInstalledAgentSkillsChanged()
-      }
-      void onRecheck()
+      recheckSurfacesAfterAgentSkillTerminal(onRecheck, freshnessSkillName)
     },
     [freshnessSkillName, onRecheck]
   )
 
   const handleTerminalExit = useCallback((): void => {
+    const shouldRecheck = setupAttemptRunningRef.current
     if (mountedRef.current) {
       setupAttemptRunningRef.current = false
       setTerminalOpen(false)
       setSetupAttemptRunning(false)
     }
-    notifyInstalledAgentSkillsChanged()
-  }, [mountedRef])
+    void (shouldRecheck && recheckSurfacesAfterAgentSkillTerminal(onRecheck, freshnessSkillName))
+  }, [freshnessSkillName, mountedRef, onRecheck])
 
   useEffect(() => {
     if (!preInstallNotice) {
@@ -235,8 +233,7 @@ export function AgentSkillSetupPanel({
               return
             }
             void Promise.resolve(onRecheck()).then(() => {
-              // Reuse the completed scan so sibling surfaces sync without rediscovery.
-              notifyInstalledAgentSkillsRefreshed()
+              syncSurfacesAfterAgentSkillRecheck(freshnessSkillName)
             })
           }}
           disabled={
diff --git a/src/renderer/src/components/settings/CliSection.test.tsx b/src/renderer/src/components/settings/CliSection.test.tsx
index 7db93106fe4..20830a2febf 100644
--- a/src/renderer/src/components/settings/CliSection.test.tsx
+++ b/src/renderer/src/components/settings/CliSection.test.tsx
@@ -7,9 +7,11 @@ import { getDefaultSettings } from '../../../../shared/constants'
 import { CliSection } from './CliSection'
 
 const capturedPanel = vi.hoisted(() => ({
+  canUseLocalSkillFreshness: true,
   props: null as null | {
     command: string
     installedCommand: string
+    freshnessSkillName?: string
     getPrerequisiteStatus: () => Promise<unknown>
     onBeforeOpenTerminal: () => Promise<void>
   },
@@ -24,6 +26,12 @@ vi.mock('@/hooks/useInstalledAgentSkills', () => ({
   useInstalledAgentSkill: capturedPanel.useInstalledAgentSkill
 }))
 
+vi.mock('@/hooks/useActiveProjectSkillRuntime', () => ({
+  useActiveProjectSkillRuntime: () => ({
+    canUseLocalSkillFreshness: capturedPanel.canUseLocalSkillFreshness
+  })
+}))
+
 capturedPanel.useInstalledAgentSkill.mockReturnValue({
   installed: false,
   loading: false,
@@ -33,6 +41,7 @@ capturedPanel.useInstalledAgentSkill.mockReturnValue({
 
 afterEach(() => {
   cleanup()
+  capturedPanel.canUseLocalSkillFreshness = true
   toastError.mockReset()
   vi.unstubAllGlobals()
 })
@@ -41,6 +50,7 @@ vi.mock('./AgentSkillSetupPanel', () => ({
   AgentSkillSetupPanel: function AgentSkillSetupPanel(props: {
     command: string
     installedCommand: string
+    freshnessSkillName?: string
     getPrerequisiteStatus: () => Promise<unknown>
     onBeforeOpenTerminal: () => Promise<void>
   }) {
@@ -62,6 +72,30 @@ vi.mock('./WslCliRegistration', () => ({
 }))
 
 describe('CliSection project runtime defaults', () => {
+  it('exposes freshness only for a resolved local host runtime', () => {
+    const settings = getDefaultSettings('/tmp')
+    renderToStaticMarkup(<CliSection currentPlatform="darwin" settings={settings} />)
+    expect(capturedPanel.props?.freshnessSkillName).toBe('orca-cli')
+
+    capturedPanel.canUseLocalSkillFreshness = false
+    renderToStaticMarkup(<CliSection currentPlatform="darwin" settings={settings} />)
+    expect(capturedPanel.props?.freshnessSkillName).toBeUndefined()
+
+    capturedPanel.canUseLocalSkillFreshness = true
+    renderToStaticMarkup(
+      <CliSection
+        currentPlatform="win32"
+        settings={{
+          ...settings,
+          localWindowsRuntimeDefault: { kind: 'wsl', distro: 'Ubuntu' }
+        }}
+        wslSupportedPlatform
+        wslAvailable
+      />
+    )
+    expect(capturedPanel.props?.freshnessSkillName).toBeUndefined()
+  })
+
   it('passes the default project WSL distro to CLI skill prerequisite checks', async () => {
     const getWslInstallStatus = vi
       .fn()
diff --git a/src/renderer/src/components/settings/CliSection.tsx b/src/renderer/src/components/settings/CliSection.tsx
index 6f6eab2ee94..41984fe2038 100644
--- a/src/renderer/src/components/settings/CliSection.tsx
+++ b/src/renderer/src/components/settings/CliSection.tsx
@@ -32,6 +32,7 @@ import {
   getWslCliDistroRequest
 } from './CliSkillRuntimeSetup'
 import { WslCliRegistration } from './WslCliRegistration'
+import { useLocalCliSkillFreshnessName } from './use-local-cli-skill-freshness-name'
 import { translate } from '@/i18n/i18n'
 
 type CliSectionProps = {
@@ -86,6 +87,7 @@ export function CliSection({
       getSelectedAgentRuntime(settings, wslSupportedPlatform, wslAvailable, wslCapabilitiesLoading),
     [settings, wslAvailable, wslCapabilitiesLoading, wslSupportedPlatform]
   )
+  const cliSkillFreshnessName = useLocalCliSkillFreshnessName(agentRuntime)
   const cliSkillDiscoveryTarget = useMemo(
     () => getSkillDiscoveryTargetForRuntime(agentRuntime),
     [agentRuntime]
@@ -395,7 +397,7 @@ export function CliSection({
                     }))
               }}
               onRecheck={refreshCliSkill}
-              freshnessSkillName={agentRuntime.runtime === 'host' ? ORCA_CLI_SKILL_NAME : undefined}
+              freshnessSkillName={cliSkillFreshnessName}
             />
           </div>
         ) : null}
diff --git a/src/renderer/src/components/settings/ComputerUseSkillSetupPanel.tsx b/src/renderer/src/components/settings/ComputerUseSkillSetupPanel.tsx
index 0ffc0a2b526..e916686c25e 100644
--- a/src/renderer/src/components/settings/ComputerUseSkillSetupPanel.tsx
+++ b/src/renderer/src/components/settings/ComputerUseSkillSetupPanel.tsx
@@ -80,7 +80,7 @@ export function ComputerUseSkillSetupPanel(): React.JSX.Element {
       }}
       onRecheck={refreshComputerUseSkill}
       freshnessSkillName={
-        activeSkillRuntime.agentRuntime?.runtime === 'wsl' ? undefined : COMPUTER_USE_SKILL_NAME
+        activeSkillRuntime.canUseLocalSkillFreshness ? COMPUTER_USE_SKILL_NAME : undefined
       }
     />
   )
diff --git a/src/renderer/src/components/settings/EphemeralVmsPane.tsx b/src/renderer/src/components/settings/EphemeralVmsPane.tsx
index e2fb92278c5..06c8fe02741 100644
--- a/src/renderer/src/components/settings/EphemeralVmsPane.tsx
+++ b/src/renderer/src/components/settings/EphemeralVmsPane.tsx
@@ -183,7 +183,7 @@ export function EphemeralVmsPane(): React.JSX.Element {
         }}
         onRecheck={refreshSkill}
         freshnessSkillName={
-          activeSkillRuntime.agentRuntime?.runtime === 'wsl' ? undefined : EPHEMERAL_VMS_SKILL_NAME
+          activeSkillRuntime.canUseLocalSkillFreshness ? EPHEMERAL_VMS_SKILL_NAME : undefined
         }
       />
 
diff --git a/src/renderer/src/components/settings/LinearAgentSkillPane.test.tsx b/src/renderer/src/components/settings/LinearAgentSkillPane.test.tsx
index e8e0dd442a0..79e4f641bf0 100644
--- a/src/renderer/src/components/settings/LinearAgentSkillPane.test.tsx
+++ b/src/renderer/src/components/settings/LinearAgentSkillPane.test.tsx
@@ -69,7 +69,8 @@ vi.mock('@/hooks/useActiveProjectSkillRuntime', () => ({
     discoveryTarget: undefined,
     agentRuntime: { runtime: mocks.runtime },
     terminalShellOverride: undefined,
-    installDisabledReason: null
+    installDisabledReason: null,
+    canUseLocalSkillFreshness: mocks.runtime !== 'wsl'
   })
 }))
 
diff --git a/src/renderer/src/components/settings/MobileEmulatorAgentControlRow.test.tsx b/src/renderer/src/components/settings/MobileEmulatorAgentControlRow.test.tsx
new file mode 100644
index 00000000000..668d0d1fdf7
--- /dev/null
+++ b/src/renderer/src/components/settings/MobileEmulatorAgentControlRow.test.tsx
@@ -0,0 +1,59 @@
+import { renderToStaticMarkup } from 'react-dom/server'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { MobileEmulatorAgentControlRow } from './MobileEmulatorAgentControlRow'
+
+const mocks = vi.hoisted(() => ({
+  canUseLocalSkillFreshness: true,
+  freshnessSkillName: undefined as string | undefined
+}))
+
+vi.mock('@/hooks/useActiveProjectSkillRuntime', () => ({
+  useActiveProjectSkillRuntime: () => ({
+    canUseLocalSkillFreshness: mocks.canUseLocalSkillFreshness,
+    terminalShellOverride: undefined
+  })
+}))
+
+vi.mock('../emulator-pane/use-mobile-emulator-agent-setup-state', () => ({
+  useMobileEmulatorAgentSetupState: () => ({
+    cliActionLabel: 'Enable',
+    cliBusy: false,
+    cliEnabled: true,
+    cliInstallStatus: null,
+    cliLoading: false,
+    cliSkillError: null,
+    cliSkillInstalled: true,
+    cliSkillLoading: false,
+    cliSupported: true,
+    completedCount: 2,
+    handleEnableCli: vi.fn(),
+    refreshCliSkill: vi.fn(),
+    step2Blocked: false
+  })
+}))
+
+vi.mock('./AgentSkillSetupPanel', () => ({
+  AgentSkillSetupPanel: ({ freshnessSkillName }: { freshnessSkillName?: string }) => {
+    mocks.freshnessSkillName = freshnessSkillName
+    return null
+  }
+}))
+
+vi.mock('./SetupStepBadge', () => ({ StepBadge: () => null }))
+vi.mock('./MobileEmulatorExamples', () => ({ MobileEmulatorExamples: () => null }))
+
+describe('MobileEmulatorAgentControlRow freshness authority', () => {
+  beforeEach(() => {
+    mocks.canUseLocalSkillFreshness = true
+    mocks.freshnessSkillName = undefined
+  })
+
+  it('exposes local freshness only for a resolved local non-WSL runtime', () => {
+    renderToStaticMarkup(<MobileEmulatorAgentControlRow />)
+    expect(mocks.freshnessSkillName).toBe('orca-cli')
+
+    mocks.canUseLocalSkillFreshness = false
+    renderToStaticMarkup(<MobileEmulatorAgentControlRow />)
+    expect(mocks.freshnessSkillName).toBeUndefined()
+  })
+})
diff --git a/src/renderer/src/components/settings/MobileEmulatorAgentControlRow.tsx b/src/renderer/src/components/settings/MobileEmulatorAgentControlRow.tsx
index 4aaad31fb2c..872f530fedb 100644
--- a/src/renderer/src/components/settings/MobileEmulatorAgentControlRow.tsx
+++ b/src/renderer/src/components/settings/MobileEmulatorAgentControlRow.tsx
@@ -177,9 +177,9 @@ export function MobileEmulatorAgentControlRow(): React.JSX.Element {
               await ensureOrcaCliAvailableForAgentSkillTerminal()
             }}
             onRecheck={setup.refreshCliSkill}
-            // Why: this row builds its commands for the local host only, so the
-            // local-host freshness scan can vouch for the copy it points at.
-            freshnessSkillName={ORCA_CLI_SKILL_NAME}
+            freshnessSkillName={
+              activeSkillRuntime.canUseLocalSkillFreshness ? ORCA_CLI_SKILL_NAME : undefined
+            }
           />
         </div>
 
diff --git a/src/renderer/src/components/settings/OrchestrationPane.tsx b/src/renderer/src/components/settings/OrchestrationPane.tsx
index 66fe68aa02e..09910c8659b 100644
--- a/src/renderer/src/components/settings/OrchestrationPane.tsx
+++ b/src/renderer/src/components/settings/OrchestrationPane.tsx
@@ -156,10 +156,8 @@ export function OrchestrationPane(): React.JSX.Element {
           />
         }
         onRecheck={refreshOrchestrationSkill}
-        // Why: the local-host-only freshness scan cannot vouch for a WSL runtime,
-        // so fall back to the presence-only pill there (mirrors the Computer Use card).
         freshnessSkillName={
-          activeSkillRuntime.agentRuntime?.runtime === 'wsl' ? undefined : ORCHESTRATION_SKILL_NAME
+          activeSkillRuntime.canUseLocalSkillFreshness ? ORCHESTRATION_SKILL_NAME : undefined
         }
       />
 
diff --git a/src/renderer/src/components/settings/OrchestrationSetupCard.tsx b/src/renderer/src/components/settings/OrchestrationSetupCard.tsx
index d597895d580..b47b65a0c62 100644
--- a/src/renderer/src/components/settings/OrchestrationSetupCard.tsx
+++ b/src/renderer/src/components/settings/OrchestrationSetupCard.tsx
@@ -77,7 +77,7 @@ export function OrchestrationSetupCard(props: {
       }}
       onRecheck={skill.refresh}
       freshnessSkillName={
-        activeSkillRuntime.agentRuntime?.runtime === 'wsl' ? undefined : ORCHESTRATION_SKILL_NAME
+        activeSkillRuntime.canUseLocalSkillFreshness ? ORCHESTRATION_SKILL_NAME : undefined
       }
     />
   )
diff --git a/src/renderer/src/components/settings/Settings.tsx b/src/renderer/src/components/settings/Settings.tsx
index 1cede19ac80..71db4c822de 100644
--- a/src/renderer/src/components/settings/Settings.tsx
+++ b/src/renderer/src/components/settings/Settings.tsx
@@ -351,9 +351,8 @@ function Settings(): React.JSX.Element {
     discoveryTarget: activeSkillRuntime.discoveryTarget,
     sourceKinds: GLOBAL_AGENT_SKILL_SOURCE_KINDS
   })
-  // Why: skill freshness only covers the validated global rail (not WSL), so the nav pill stays presence-only under WSL.
-  const { inventory: skillFreshnessInventory } = useSkillFreshness()
-  const skillFreshnessApplies = activeSkillRuntime.agentRuntime?.runtime !== 'wsl'
+  const skillFreshnessApplies = activeSkillRuntime.canUseLocalSkillFreshness
+  const { inventory: skillFreshnessInventory } = useSkillFreshness(skillFreshnessApplies)
   const [voiceModelStatesLoading, setVoiceModelStatesLoading] = useState(showDesktopOnlySettings)
   // Why: trim platform-only Terminal entries from the shared search index so search never reveals hidden controls.
   const [scrollbackMode, setScrollbackMode] = useState<'preset' | 'custom'>('preset')
diff --git a/src/renderer/src/components/settings/TaskSourceLinearSetup.test.tsx b/src/renderer/src/components/settings/TaskSourceLinearSetup.test.tsx
index 878bef8125c..938c788a6ec 100644
--- a/src/renderer/src/components/settings/TaskSourceLinearSetup.test.tsx
+++ b/src/renderer/src/components/settings/TaskSourceLinearSetup.test.tsx
@@ -48,7 +48,8 @@ vi.mock('@/hooks/useActiveProjectSkillRuntime', () => ({
     discoveryTarget: undefined,
     agentRuntime: { runtime: 'native' },
     terminalShellOverride: undefined,
-    installDisabledReason: null
+    installDisabledReason: null,
+    canUseLocalSkillFreshness: true
   })
 }))
 
diff --git a/src/renderer/src/components/settings/agent-skill-installed-command-callers.test.ts b/src/renderer/src/components/settings/agent-skill-installed-command-callers.test.ts
index 9f041ea076f..f0bab20bf65 100644
--- a/src/renderer/src/components/settings/agent-skill-installed-command-callers.test.ts
+++ b/src/renderer/src/components/settings/agent-skill-installed-command-callers.test.ts
@@ -180,6 +180,35 @@ describe('AgentSkillSetupPanel installed-command call sites', () => {
     )
   })
 
+  it('keeps client freshness behind resolved local runtime authority', () => {
+    const expectedGates = new Map<string, string>([
+      [
+        'src/renderer/src/components/settings/use-local-cli-skill-freshness-name.ts',
+        "agentRuntime.runtime === 'host' && activeSkillRuntime.canUseLocalSkillFreshness"
+      ],
+      [
+        'src/renderer/src/components/settings/MobileEmulatorAgentControlRow.tsx',
+        'activeSkillRuntime.canUseLocalSkillFreshness ? ORCA_CLI_SKILL_NAME : undefined'
+      ],
+      [
+        'src/renderer/src/components/settings/Settings.tsx',
+        'useSkillFreshness(skillFreshnessApplies)'
+      ],
+      [
+        'src/renderer/src/components/skills/SkillFreshnessNudge.tsx',
+        'useSkillFreshness(activeSkillRuntime.canUseLocalSkillFreshness)'
+      ],
+      [
+        'src/renderer/src/components/skills/SkillFreshnessUpdateDialog.tsx',
+        'useSkillFreshness(activeSkillRuntime.canUseLocalSkillFreshness)'
+      ]
+    ])
+
+    for (const [relativePath, expectedGate] of expectedGates) {
+      expect(readRepoFile(relativePath), relativePath).toContain(expectedGate)
+    }
+  })
+
   it('fails when a production caller can show the default Update action without installedCommand', () => {
     const productionCallers = findProductionPanelCallers(componentsRoot)
 
diff --git a/src/renderer/src/components/settings/agent-skill-recheck-surface-sync.ts b/src/renderer/src/components/settings/agent-skill-recheck-surface-sync.ts
new file mode 100644
index 00000000000..ec4aeae3176
--- /dev/null
+++ b/src/renderer/src/components/settings/agent-skill-recheck-surface-sync.ts
@@ -0,0 +1,19 @@
+import { notifyInstalledAgentSkillsRefreshed } from '@/hooks/useInstalledAgentSkills'
+import { refreshSkillFreshness } from '@/hooks/useSkillFreshness'
+
+/** Publishes a completed re-check to presence and optional local-freshness surfaces. */
+export function syncSurfacesAfterAgentSkillRecheck(freshnessSkillName?: string): void {
+  notifyInstalledAgentSkillsRefreshed()
+  if (freshnessSkillName) {
+    void refreshSkillFreshness()
+  }
+}
+
+export function recheckSurfacesAfterAgentSkillTerminal(
+  onRecheck: () => void | Promise<unknown>,
+  freshnessSkillName?: string
+): void {
+  void Promise.resolve(onRecheck()).then(() => {
+    syncSurfacesAfterAgentSkillRecheck(freshnessSkillName)
+  })
+}
diff --git a/src/renderer/src/components/settings/use-linear-agent-skill-setup.ts b/src/renderer/src/components/settings/use-linear-agent-skill-setup.ts
index 21a378a1b37..2fd89c87cf0 100644
--- a/src/renderer/src/components/settings/use-linear-agent-skill-setup.ts
+++ b/src/renderer/src/components/settings/use-linear-agent-skill-setup.ts
@@ -67,8 +67,9 @@ export function useLinearAgentSkillSetup(): {
     : buildSkillCommandForRuntime(updateTarget.command, activeSkillRuntime.agentRuntime)
 
   // Freshness cannot verify WSL, so report presence there.
-  const freshnessSkillName =
-    activeSkillRuntime.agentRuntime?.runtime === 'wsl' ? undefined : updateTarget.skillName
+  const freshnessSkillName = activeSkillRuntime.canUseLocalSkillFreshness
+    ? updateTarget.skillName
+    : undefined
 
   const getPrerequisiteStatus = useCallback(
     () =>
diff --git a/src/renderer/src/components/settings/use-local-cli-skill-freshness-name.ts b/src/renderer/src/components/settings/use-local-cli-skill-freshness-name.ts
new file mode 100644
index 00000000000..a1475a2fd04
--- /dev/null
+++ b/src/renderer/src/components/settings/use-local-cli-skill-freshness-name.ts
@@ -0,0 +1,10 @@
+import { ORCA_CLI_SKILL_NAME } from '@/lib/agent-feature-install-commands'
+import { useActiveProjectSkillRuntime } from '@/hooks/useActiveProjectSkillRuntime'
+import type { LocalAgentRuntime } from './CliSkillRuntimeSetup'
+
+export function useLocalCliSkillFreshnessName(agentRuntime: LocalAgentRuntime): string | undefined {
+  const activeSkillRuntime = useActiveProjectSkillRuntime()
+  return agentRuntime.runtime === 'host' && activeSkillRuntime.canUseLocalSkillFreshness
+    ? ORCA_CLI_SKILL_NAME
+    : undefined
+}
diff --git a/src/renderer/src/components/skills/SkillFreshnessNudge.test.tsx b/src/renderer/src/components/skills/SkillFreshnessNudge.test.tsx
index d32f6a017a8..52564bb02da 100644
--- a/src/renderer/src/components/skills/SkillFreshnessNudge.test.tsx
+++ b/src/renderer/src/components/skills/SkillFreshnessNudge.test.tsx
@@ -16,6 +16,8 @@ const mocks = vi.hoisted(() => ({
   toastDismiss: vi.fn(),
   requestDialog: vi.fn(),
   settingsLoaded: true,
+  canUseLocalSkillFreshness: true,
+  freshnessEnabled: true,
   inventory: null as SkillFreshnessInventory | null,
   error: null as string | null
 }))
@@ -57,11 +59,20 @@ function eligibleInventory(): SkillFreshnessInventory {
 }
 
 vi.mock('@/hooks/useSkillFreshness', () => ({
-  useSkillFreshness: () => ({
-    inventory: mocks.inventory,
-    loading: false,
-    error: mocks.error,
-    refresh: vi.fn()
+  useSkillFreshness: (enabled = true) => {
+    mocks.freshnessEnabled = enabled
+    return {
+      inventory: mocks.inventory,
+      loading: false,
+      error: mocks.error,
+      refresh: vi.fn()
+    }
+  }
+}))
+
+vi.mock('@/hooks/useActiveProjectSkillRuntime', () => ({
+  useActiveProjectSkillRuntime: () => ({
+    canUseLocalSkillFreshness: mocks.canUseLocalSkillFreshness
   })
 }))
 
@@ -107,6 +118,8 @@ describe('SkillFreshnessNudge', () => {
   beforeEach(() => {
     mocks.dismissed = []
     mocks.settingsLoaded = true
+    mocks.canUseLocalSkillFreshness = true
+    mocks.freshnessEnabled = true
     mocks.inventory = eligibleInventory()
     mocks.error = null
     mocks.updateSettings.mockReset()
@@ -179,6 +192,19 @@ describe('SkillFreshnessNudge', () => {
     expect(mocks.updateSettings).not.toHaveBeenCalled()
   })
 
+  it('retracts an active local nudge when runtime freshness becomes unavailable', async () => {
+    await renderNudge()
+    const options = mocks.toastInfo.mock.calls[0]?.[1]
+
+    mocks.canUseLocalSkillFreshness = false
+    await rerenderNudge()
+    options.onDismiss()
+
+    expect(mocks.freshnessEnabled).toBe(false)
+    expect(mocks.toastDismiss).toHaveBeenCalledWith('freshness-toast')
+    expect(mocks.updateSettings).not.toHaveBeenCalled()
+  })
+
   it('persists the exact placement/revision key once on explicit dismissal', async () => {
     await renderNudge()
 
diff --git a/src/renderer/src/components/skills/SkillFreshnessNudge.tsx b/src/renderer/src/components/skills/SkillFreshnessNudge.tsx
index eb29629812a..7e6e8cebce3 100644
--- a/src/renderer/src/components/skills/SkillFreshnessNudge.tsx
+++ b/src/renderer/src/components/skills/SkillFreshnessNudge.tsx
@@ -2,6 +2,7 @@ import { useEffect, useRef } from 'react'
 import { Terminal } from 'lucide-react'
 import { toast } from 'sonner'
 import { useSkillFreshness } from '@/hooks/useSkillFreshness'
+import { useActiveProjectSkillRuntime } from '@/hooks/useActiveProjectSkillRuntime'
 import { translate } from '@/i18n/i18n'
 import { useAppStore } from '@/store'
 import { skillPlacementParticipatesInGlobalFreshness } from '../../../../shared/skill-freshness'
@@ -25,7 +26,8 @@ function candidateKey(args: {
 }
 
 export function SkillFreshnessNudge(): null {
-  const state = useSkillFreshness()
+  const activeSkillRuntime = useActiveProjectSkillRuntime()
+  const state = useSkillFreshness(activeSkillRuntime.canUseLocalSkillFreshness)
   const settingsLoaded = useAppStore((store) => store.settings !== null)
   const dismissed = useAppStore(
     (store) => store.settings?.dismissedSkillFreshnessNudges ?? NO_DISMISSED_FRESHNESS_NUDGES
@@ -36,6 +38,15 @@ export function SkillFreshnessNudge(): null {
   const activeNudgeRef = useRef<ActiveFreshnessNudge | null>(null)
 
   useEffect(() => {
+    if (!activeSkillRuntime.canUseLocalSkillFreshness) {
+      const active = activeNudgeRef.current
+      if (active) {
+        active.persistDismissal = false
+        activeNudgeRef.current = null
+        toast.dismiss(active.id)
+      }
+      return
+    }
     const inventory = state.inventory
     if (!settingsLoaded) {
       return
@@ -182,7 +193,14 @@ export function SkillFreshnessNudge(): null {
       }
     )
     activeNudgeRef.current = nextActive
-  }, [dismissed, settingsLoaded, state.error, state.inventory, updateSettings])
+  }, [
+    activeSkillRuntime.canUseLocalSkillFreshness,
+    dismissed,
+    settingsLoaded,
+    state.error,
+    state.inventory,
+    updateSettings
+  ])
 
   return null
 }
diff --git a/src/renderer/src/components/skills/SkillFreshnessStatusPill.test.tsx b/src/renderer/src/components/skills/SkillFreshnessStatusPill.test.tsx
index 24c08ee1df3..a2719cd41ab 100644
--- a/src/renderer/src/components/skills/SkillFreshnessStatusPill.test.tsx
+++ b/src/renderer/src/components/skills/SkillFreshnessStatusPill.test.tsx
@@ -8,14 +8,16 @@ import { SkillFreshnessStatusPill } from './SkillFreshnessStatusPill'
 import { consumeSkillFreshnessUpdateDialogRequest } from './skill-freshness-update-dialog'
 
 const mocks = vi.hoisted(() => ({
-  inventory: null as SkillFreshnessInventory | null
+  inventory: null as SkillFreshnessInventory | null,
+  loading: false,
+  error: null as string | null
 }))
 
 vi.mock('@/hooks/useSkillFreshness', () => ({
   useSkillFreshness: () => ({
     inventory: mocks.inventory,
-    loading: false,
-    error: null,
+    loading: mocks.loading,
+    error: mocks.error,
     refresh: vi.fn()
   })
 }))
@@ -76,6 +78,8 @@ async function renderPill(skillName: string): Promise<HTMLDivElement> {
 describe('SkillFreshnessStatusPill', () => {
   beforeEach(() => {
     mocks.inventory = null
+    mocks.loading = false
+    mocks.error = null
     // Why: the dialog request is module-level state shared across tests.
     consumeSkillFreshnessUpdateDialogRequest()
   })
@@ -127,6 +131,22 @@ describe('SkillFreshnessStatusPill', () => {
     expect(detailsButton(rendered)).toBeNull()
   })
 
+  it('shows a neutral verdict while freshness is being checked', async () => {
+    mocks.loading = true
+
+    const rendered = await renderPill('orca-cli')
+    expect(pillText(rendered)).toBe('Checking...')
+    expect(detailsButton(rendered)).toBeNull()
+  })
+
+  it('does not report success after a freshness check fails', async () => {
+    mocks.error = 'Could not read skills.'
+
+    const rendered = await renderPill('orca-cli')
+    expect(pillText(rendered)).toBe('Check failed')
+    expect(detailsButton(rendered)).toBeNull()
+  })
+
   it('opens the freshness review dialog from Details', async () => {
     mocks.inventory = inventory([{ name: 'orca-cli', status: 'outdated' }], ['orca-cli'])
     const rendered = await renderPill('orca-cli')
diff --git a/src/renderer/src/components/skills/SkillFreshnessStatusPill.tsx b/src/renderer/src/components/skills/SkillFreshnessStatusPill.tsx
index bedcfa4f340..73c84f560ce 100644
--- a/src/renderer/src/components/skills/SkillFreshnessStatusPill.tsx
+++ b/src/renderer/src/components/skills/SkillFreshnessStatusPill.tsx
@@ -51,7 +51,21 @@ function statusPill(status: SkillFreshnessDisplayStatus): React.JSX.Element {
 // somewhere the update cannot reach — and green must never stand in for that last
 // case, which is real drift the user would otherwise have no way to see.
 export function SkillFreshnessStatusPill({ skillName }: { skillName: string }): React.JSX.Element {
-  const { inventory } = useSkillFreshness()
+  const { inventory, loading, error } = useSkillFreshness()
+  if (loading && !inventory) {
+    return (
+      <IntegrationStatusPill tone="neutral">
+        {translate('auto.components.skills.SkillFreshnessStatusPill.checking', 'Checking...')}
+      </IntegrationStatusPill>
+    )
+  }
+  if (error && !inventory) {
+    return (
+      <IntegrationStatusPill tone="attention">
+        {translate('auto.components.skills.SkillFreshnessStatusPill.checkFailed', 'Check failed')}
+      </IntegrationStatusPill>
+    )
+  }
   const status = getSkillFreshnessDisplayStatus(inventory, skillName)
   // Why: the dialog lists every placement, so Details is offered whenever a placement
   // is what drove the status — an available update, or a copy that blocked one.
diff --git a/src/renderer/src/components/skills/SkillFreshnessUpdateDialog.test.tsx b/src/renderer/src/components/skills/SkillFreshnessUpdateDialog.test.tsx
index 1a53ecdcf10..f652a2ad1ca 100644
--- a/src/renderer/src/components/skills/SkillFreshnessUpdateDialog.test.tsx
+++ b/src/renderer/src/components/skills/SkillFreshnessUpdateDialog.test.tsx
@@ -32,6 +32,10 @@ vi.mock('@/hooks/useSkillFreshness', () => ({
   })
 }))
 
+vi.mock('@/hooks/useActiveProjectSkillRuntime', () => ({
+  useActiveProjectSkillRuntime: () => ({ canUseLocalSkillFreshness: true })
+}))
+
 vi.mock('@/hooks/useInstalledAgentSkills', () => ({
   notifyInstalledAgentSkillsChanged: mocks.notifyChanged
 }))
diff --git a/src/renderer/src/components/skills/SkillFreshnessUpdateDialog.tsx b/src/renderer/src/components/skills/SkillFreshnessUpdateDialog.tsx
index 8dd89233b0a..26edc09cfa4 100644
--- a/src/renderer/src/components/skills/SkillFreshnessUpdateDialog.tsx
+++ b/src/renderer/src/components/skills/SkillFreshnessUpdateDialog.tsx
@@ -7,6 +7,7 @@ import {
   type SkillFreshnessInventory
 } from '../../../../shared/skill-freshness'
 import { useSkillFreshness } from '@/hooks/useSkillFreshness'
+import { useActiveProjectSkillRuntime } from '@/hooks/useActiveProjectSkillRuntime'
 import { notifyInstalledAgentSkillsChanged } from '@/hooks/useInstalledAgentSkills'
 import { translate } from '@/i18n/i18n'
 import { Button } from '@/components/ui/button'
@@ -63,7 +64,8 @@ function RunLog({ output }: { output: string }): React.JSX.Element | null {
 }
 
 export function SkillFreshnessUpdateDialog(): React.JSX.Element {
-  const state = useSkillFreshness()
+  const activeSkillRuntime = useActiveProjectSkillRuntime()
+  const state = useSkillFreshness(activeSkillRuntime.canUseLocalSkillFreshness)
   const run = useSkillUpdateRun()
   const open = useSyncExternalStore(
     subscribeSkillFreshnessUpdateDialog,
diff --git a/src/renderer/src/hooks/useActiveProjectSkillRuntime.test.tsx b/src/renderer/src/hooks/useActiveProjectSkillRuntime.test.tsx
index dc19e333ddf..71a725767fd 100644
--- a/src/renderer/src/hooks/useActiveProjectSkillRuntime.test.tsx
+++ b/src/renderer/src/hooks/useActiveProjectSkillRuntime.test.tsx
@@ -3,7 +3,10 @@ import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 import { renderHook } from '@testing-library/react'
 import { getDefaultSettings } from '../../../shared/constants'
 import { useAppStore } from '@/store'
-import { useActiveProjectSkillRuntime } from './useActiveProjectSkillRuntime'
+import {
+  shouldUseLocalSkillFreshness,
+  useActiveProjectSkillRuntime
+} from './useActiveProjectSkillRuntime'
 
 function setPlatform(platform: NodeJS.Platform): void {
   ;(window as unknown as { api: unknown }).api = {
@@ -42,4 +45,21 @@ describe('useActiveProjectSkillRuntime', () => {
 
     expect(result.current.terminalShellOverride).toBeUndefined()
   })
+
+  it('limits local freshness to resolved host runtimes', () => {
+    expect(shouldUseLocalSkillFreshness({ kind: 'local' }, undefined)).toBe(true)
+    expect(
+      shouldUseLocalSkillFreshness({ kind: 'local' }, { runtime: 'host', label: 'Host' })
+    ).toBe(true)
+    expect(shouldUseLocalSkillFreshness({ kind: 'local' }, { runtime: 'wsl', label: 'WSL' })).toBe(
+      false
+    )
+    expect(
+      shouldUseLocalSkillFreshness(
+        { kind: 'environment', environmentId: 'ssh-production' },
+        undefined
+      )
+    ).toBe(false)
+    expect(shouldUseLocalSkillFreshness(null, undefined)).toBe(false)
+  })
 })
diff --git a/src/renderer/src/hooks/useActiveProjectSkillRuntime.ts b/src/renderer/src/hooks/useActiveProjectSkillRuntime.ts
index 9c78fa81e0b..1a6df80b47c 100644
--- a/src/renderer/src/hooks/useActiveProjectSkillRuntime.ts
+++ b/src/renderer/src/hooks/useActiveProjectSkillRuntime.ts
@@ -2,6 +2,8 @@ import { useMemo, useState } from 'react'
 import { useShallow } from 'zustand/react/shallow'
 import type { ProjectExecutionRuntimeResolution } from '../../../shared/project-execution-runtime'
 import type { SkillDiscoveryTarget } from '../../../shared/skills'
+import { useActiveSkillDiscoveryRuntimeTarget } from './use-active-skill-discovery-runtime-target'
+import type { RuntimeClientTarget } from '@/runtime/runtime-rpc-client'
 import { getLocalProjectExecutionRuntimeContext } from '@/lib/local-preflight-context'
 import {
   getProjectAgentSkillRuntime,
@@ -19,12 +21,21 @@ type ActiveProjectSkillRuntime = {
   agentRuntime?: ProjectAgentSkillRuntime
   terminalShellOverride?: string
   installDisabledReason: string | null
+  canUseLocalSkillFreshness: boolean
 }
 
 const EMPTY_ACTIVE_PROJECT_SKILL_RUNTIME: ActiveProjectSkillRuntime = Object.freeze({
-  installDisabledReason: null
+  installDisabledReason: null,
+  canUseLocalSkillFreshness: false
 })
 
+export function shouldUseLocalSkillFreshness(
+  runtimeTarget: RuntimeClientTarget | null,
+  agentRuntime?: ProjectAgentSkillRuntime
+): boolean {
+  return runtimeTarget?.kind === 'local' && agentRuntime?.runtime !== 'wsl'
+}
+
 // Why: on Windows the runtime resolution is rebuilt from scratch on every
 // worktree-store change, so a same-runtime result still arrives with a fresh
 // identity. Downstream skill discovery keys effects off `discoveryTarget`, so
@@ -48,6 +59,7 @@ export function useActiveProjectSkillRuntime(): ActiveProjectSkillRuntime {
   )
   const currentPlatform = getCurrentPlatform()
   const windowsCapabilities = useWindowsTerminalCapabilities(currentPlatform === 'win32')
+  const runtimeTarget = useActiveSkillDiscoveryRuntimeTarget()
 
   const resolved = useMemo(() => {
     const projectRuntime = getLocalProjectExecutionRuntimeContext(
@@ -67,9 +79,11 @@ export function useActiveProjectSkillRuntime(): ActiveProjectSkillRuntime {
         runtimeState.settings,
         undefined
       )
-      return terminalShellOverride
-        ? { installDisabledReason: null, terminalShellOverride }
-        : EMPTY_ACTIVE_PROJECT_SKILL_RUNTIME
+      const canUseLocalSkillFreshness = shouldUseLocalSkillFreshness(runtimeTarget)
+      if (!terminalShellOverride && !canUseLocalSkillFreshness) {
+        return EMPTY_ACTIVE_PROJECT_SKILL_RUNTIME
+      }
+      return { installDisabledReason: null, terminalShellOverride, canUseLocalSkillFreshness }
     }
 
     const agentRuntime = getProjectAgentSkillRuntime(projectRuntime, currentPlatform)
@@ -82,9 +96,10 @@ export function useActiveProjectSkillRuntime(): ActiveProjectSkillRuntime {
         runtimeState.settings,
         agentRuntime
       ),
-      installDisabledReason: getProjectSkillInstallDisabledReason(projectRuntime)
+      installDisabledReason: getProjectSkillInstallDisabledReason(projectRuntime),
+      canUseLocalSkillFreshness: shouldUseLocalSkillFreshness(runtimeTarget, agentRuntime)
     }
-  }, [currentPlatform, runtimeState, windowsCapabilities])
+  }, [currentPlatform, runtimeState, runtimeTarget, windowsCapabilities])
 
   // Content-equal runtimes keep one reference so effect keys do not thrash.
   // Adjust during render (not a ref write) when serialized identity changes.
diff --git a/src/renderer/src/hooks/useSkillFreshness.test.tsx b/src/renderer/src/hooks/useSkillFreshness.test.tsx
index 09c2d6863eb..e5fc74a1ff9 100644
--- a/src/renderer/src/hooks/useSkillFreshness.test.tsx
+++ b/src/renderer/src/hooks/useSkillFreshness.test.tsx
@@ -1,6 +1,6 @@
 // @vitest-environment happy-dom
 
-import { act } from 'react'
+import { act, StrictMode } from 'react'
 import { createRoot, type Root } from 'react-dom/client'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import type { SkillFreshnessInventory } from '../../../shared/skill-freshness'
@@ -32,10 +32,12 @@ let root: Root | null = null
 let container: HTMLDivElement | null = null
 let state: SkillFreshnessState | null = null
 const states = new Map<string, SkillFreshnessState>()
+const renderedInventories: (SkillFreshnessInventory | null)[] = []
 
-function Probe({ id = 'default' }: { id?: string }): null {
-  state = useSkillFreshness()
+function Probe({ id = 'default', enabled = true }: { id?: string; enabled?: boolean }): null {
+  state = useSkillFreshness(enabled)
   states.set(id, state)
+  renderedInventories.push(state.inventory)
   return null
 }
 
@@ -44,6 +46,7 @@ describe('useSkillFreshness', () => {
     _skillFreshnessCacheForTests.reset()
     state = null
     states.clear()
+    renderedInventories.length = 0
     container = document.createElement('div')
     document.body.appendChild(container)
     root = createRoot(container)
@@ -51,6 +54,7 @@ describe('useSkillFreshness', () => {
 
   afterEach(async () => {
     vi.useRealTimers()
+    vi.restoreAllMocks()
     if (root) {
       await act(async () => root?.unmount())
     }
@@ -79,6 +83,65 @@ describe('useSkillFreshness', () => {
     expect(state?.inventory?.scannedAt).toBe(2)
   })
 
+  it('does not scan, subscribe, or refresh while local freshness is disabled', async () => {
+    const freshnessInventory = vi.fn().mockResolvedValue(inventory(1))
+    const addEventListener = vi.spyOn(window, 'addEventListener')
+    window.api = { skills: { freshnessInventory } } as never
+
+    await act(async () => root?.render(<Probe enabled={false} />))
+    await act(async () => window.dispatchEvent(new Event('orca:installed-agent-skills-changed')))
+    await act(async () => state?.refresh())
+
+    expect(freshnessInventory).not.toHaveBeenCalled()
+    expect(state).toMatchObject({ inventory: null, loading: false, error: null })
+    expect(
+      addEventListener.mock.calls.filter(
+        ([name]) => name === 'focus' || name === 'orca:installed-agent-skills-changed'
+      )
+    ).toHaveLength(0)
+  })
+
+  it('forces one fresh scan before restoring authority after re-enable', async () => {
+    const second = deferred<SkillFreshnessInventory>()
+    const freshnessInventory = vi
+      .fn()
+      .mockResolvedValueOnce(inventory(1, ['orca-cli']))
+      .mockReturnValueOnce(second.promise)
+    window.api = { skills: { freshnessInventory } } as never
+    const renderProbes = (enabled: boolean): void => {
+      root?.render(
+        <StrictMode>
+          <Probe id="one" enabled={enabled} />
+          <Probe id="two" enabled={enabled} />
+        </StrictMode>
+      )
+    }
+
+    await act(async () => renderProbes(true))
+    expect(freshnessInventory).toHaveBeenCalledTimes(1)
+    expect(state?.inventory?.eligibleUpdateNames).toEqual(['orca-cli'])
+
+    await act(async () => renderProbes(true))
+    expect(freshnessInventory).toHaveBeenCalledTimes(1)
+
+    await act(async () => renderProbes(false))
+    await act(async () => window.dispatchEvent(new Event('orca:installed-agent-skills-changed')))
+    expect(freshnessInventory).toHaveBeenCalledTimes(1)
+    expect(state).toMatchObject({ inventory: null, loading: false })
+
+    const reenableRenderStart = renderedInventories.length
+    await act(async () => renderProbes(true))
+    expect(freshnessInventory).toHaveBeenCalledTimes(2)
+    expect(state).toMatchObject({ inventory: null, loading: true })
+    expect(renderedInventories.slice(reenableRenderStart).every((value) => value === null)).toBe(
+      true
+    )
+
+    await act(async () => second.resolve(inventory(2)))
+    expect(state?.inventory?.scannedAt).toBe(2)
+    expect(state?.inventory?.eligibleUpdateNames).toEqual([])
+  })
+
   it('skips focus rescans inside the cooldown but honors install-change events', async () => {
     const first = deferred<SkillFreshnessInventory>()
     const second = deferred<SkillFreshnessInventory>()
diff --git a/src/renderer/src/hooks/useSkillFreshness.ts b/src/renderer/src/hooks/useSkillFreshness.ts
index 91ea0c4bdc2..568ad67b3fb 100644
--- a/src/renderer/src/hooks/useSkillFreshness.ts
+++ b/src/renderer/src/hooks/useSkillFreshness.ts
@@ -1,4 +1,4 @@
-import { useEffect, useSyncExternalStore } from 'react'
+import { useEffect, useRef, useSyncExternalStore } from 'react'
 import type { SkillFreshnessInventory } from '../../../shared/skill-freshness'
 import { INSTALLED_AGENT_SKILLS_CHANGED_EVENT } from './installed-agent-skills-change-event'
 
@@ -24,7 +24,18 @@ let snapshot: SkillFreshnessSnapshot = {
   loading: false,
   error: null
 }
+const DISABLED_SNAPSHOT: SkillFreshnessSnapshot = Object.freeze({
+  inventory: null,
+  loading: false,
+  error: null
+})
+const REENABLING_SNAPSHOT: SkillFreshnessSnapshot = Object.freeze({
+  inventory: null,
+  loading: true,
+  error: null
+})
 const subscribers = new Set<() => void>()
+let pendingReenableRefresh: Promise<void> | null = null
 
 function publishSnapshot(next: SkillFreshnessSnapshot): void {
   if (
@@ -70,7 +81,10 @@ async function loadInventory(force: boolean): Promise<SkillFreshnessInventory> {
   }
 }
 
-async function refreshSkillFreshness(force = true): Promise<void> {
+/** Rescan freshness without going through the hook, for surfaces whose explicit
+ *  refresh affordance must move the shared verdict (the installed-skills refreshed
+ *  event reuses a completed scan and deliberately does not reach this store). */
+export async function refreshSkillFreshness(force = true): Promise<void> {
   if (scheduledFocusRescan !== null) {
     window.clearTimeout(scheduledFocusRescan)
     scheduledFocusRescan = null
@@ -133,14 +147,26 @@ function subscribe(subscriber: () => void): () => void {
     if (subscribers.size === 0) {
       window.removeEventListener('focus', onWindowFocus)
       window.removeEventListener(INSTALLED_AGENT_SKILLS_CHANGED_EVENT, onInstalledSkillsChanged)
+      if (scheduledFocusRescan !== null) {
+        window.clearTimeout(scheduledFocusRescan)
+        scheduledFocusRescan = null
+      }
     }
   }
 }
 
+function subscribeDisabled(): () => void {
+  return () => {}
+}
+
 function getSnapshot(): SkillFreshnessSnapshot {
   return snapshot
 }
 
+function getDisabledSnapshot(): SkillFreshnessSnapshot {
+  return DISABLED_SNAPSHOT
+}
+
 function ensureInventoryLoaded(): void {
   if (!snapshot.inventory && !snapshot.loading) {
     void refreshSkillFreshness(false)
@@ -151,14 +177,41 @@ export type SkillFreshnessState = SkillFreshnessSnapshot & {
   refresh: () => Promise<void>
 }
 
-export function useSkillFreshness(): SkillFreshnessState {
-  const current = useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+async function skipSkillFreshnessRefresh(): Promise<void> {}
+
+function refreshSkillFreshnessAfterReenable(): Promise<void> {
+  pendingReenableRefresh ??= refreshSkillFreshness(true).finally(() => {
+    pendingReenableRefresh = null
+  })
+  return pendingReenableRefresh
+}
+
+export function useSkillFreshness(enabled = true): SkillFreshnessState {
+  const previousEnabledRef = useRef(enabled)
+  const reenabled = enabled && !previousEnabledRef.current
+  const current = useSyncExternalStore(
+    enabled ? subscribe : subscribeDisabled,
+    enabled ? getSnapshot : getDisabledSnapshot,
+    enabled ? getSnapshot : getDisabledSnapshot
+  )
 
   useEffect(() => {
+    const wasEnabled = previousEnabledRef.current
+    previousEnabledRef.current = enabled
+    if (!enabled) {
+      return
+    }
+    if (!wasEnabled) {
+      void refreshSkillFreshnessAfterReenable()
+      return
+    }
     ensureInventoryLoaded()
-  }, [])
+  }, [enabled])
 
-  return { ...current, refresh: refreshSkillFreshness }
+  return {
+    ...(reenabled ? REENABLING_SNAPSHOT : current),
+    refresh: enabled ? refreshSkillFreshness : skipSkillFreshnessRefresh
+  }
 }
 
 export const _skillFreshnessCacheForTests = {
@@ -169,6 +222,7 @@ export const _skillFreshnessCacheForTests = {
     completedRevision = -1
     lastCompletedScanAt = 0
     refreshSequence = 0
+    pendingReenableRefresh = null
     if (scheduledFocusRescan !== null) {
       window.clearTimeout(scheduledFocusRescan)
       scheduledFocusRescan = null
diff --git a/src/renderer/src/i18n/locales/en.json b/src/renderer/src/i18n/locales/en.json
index 7283f862c91..98b6ff3d646 100644
--- a/src/renderer/src/i18n/locales/en.json
+++ b/src/renderer/src/i18n/locales/en.json
@@ -3929,7 +3929,9 @@
           "upToDate": "Up to date",
           "installed": "Installed",
           "details": "Details",
-          "needsAttention": "Review skill"
+          "needsAttention": "Review skill",
+          "checking": "Checking...",
+          "checkFailed": "Check failed"
         }
       },
       "sidebar": {

From 1c8908b791480b0ab3ce8fb786ff0c4dbd7f16f1 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Fri, 31 Jul 2026 10:56:20 -0700
Subject: [PATCH 21/23] Fix orchestration gate authorization to scope by Run
 binding (#11802)

* fix(orchestration): gate methods route calls to the caller's Run with `f

Gates are Run-scoped state; every gate command now resolves the caller's active Run
(via pane binding or explicit --from flag) and authorizes within that Run's scope.
Settled adopted work no longer requires --takeover-legacy, and the legacy coordinator
fence respects both binding-based and attestation-based proof of authority.

* fix(orchestration): gate methods route calls to the caller's Run with at

Gate and run methods now verify that declared terminal handles match the caller's
attested identity, preventing spoofing of other coordinators. Extracted shared
`resolveRunScope` to enforce one authorization rule across all orchestration
mutations. Added comprehensive regression tests for #11745.
---
 .../handlers/orchestration-gate-cli.test.ts   | 198 +++++
 src/cli/handlers/orchestration.ts             |  21 +-
 src/cli/specs/orchestration.ts                |  15 +-
 src/main/runtime/orchestration/db.ts          |  54 +-
 .../orchestration-adopted-run-binding.test.ts | 375 ++++++++
 src/main/runtime/rpc/core.ts                  |   2 +
 src/main/runtime/rpc/dispatcher.ts            |   6 +-
 ...chestration-gate-run-authorization.test.ts | 315 +++++++
 .../rpc/methods/orchestration-gates.ts        |  78 +-
 .../rpc/methods/orchestration-run-scope.ts    |  86 ++
 .../runtime/rpc/methods/orchestration-runs.ts |   9 +-
 .../runtime/rpc/methods/orchestration.test.ts |   7 +
 src/main/runtime/rpc/methods/orchestration.ts | 100 +--
 ...tion-11745-regression-verification.test.ts | 820 ++++++++++++++++++
 ...hestration-legacy-coordinator-authority.ts |  57 +-
 ...stration-legacy-fence-jurisdiction.test.ts | 188 ++++
 16 files changed, 2190 insertions(+), 141 deletions(-)
 create mode 100644 src/cli/handlers/orchestration-gate-cli.test.ts
 create mode 100644 src/main/runtime/orchestration/orchestration-adopted-run-binding.test.ts
 create mode 100644 src/main/runtime/rpc/methods/orchestration-gate-run-authorization.test.ts
 create mode 100644 src/main/runtime/rpc/methods/orchestration-run-scope.ts
 create mode 100644 src/main/runtime/rpc/orchestration-11745-regression-verification.test.ts
 create mode 100644 src/main/runtime/rpc/orchestration-legacy-fence-jurisdiction.test.ts

diff --git a/src/cli/handlers/orchestration-gate-cli.test.ts b/src/cli/handlers/orchestration-gate-cli.test.ts
new file mode 100644
index 00000000000..e7b16e345a6
--- /dev/null
+++ b/src/cli/handlers/orchestration-gate-cli.test.ts
@@ -0,0 +1,198 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { callMock, getTerminalHandleMock } = vi.hoisted(() => ({
+  callMock: vi.fn(),
+  getTerminalHandleMock: vi.fn()
+}))
+
+vi.mock('../runtime-client', async () => {
+  // Why: re-export the REAL error classes so format.ts `instanceof` narrowing still matches.
+  const { RuntimeClientError, RuntimeRpcFailureError } = await import('../runtime/types.js')
+  class RuntimeClient {
+    readonly isRemote = false
+    call = callMock
+    getCliStatus = vi.fn()
+    openOrca = vi.fn()
+  }
+  return {
+    RuntimeClient,
+    RuntimeClientError,
+    RuntimeRpcFailureError,
+    serveOrcaApp: vi.fn(),
+    getDefaultUserDataPath: vi.fn(() => '/tmp/orca-user-data')
+  }
+})
+
+vi.mock('../selectors', async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  getTerminalHandle: getTerminalHandleMock
+}))
+
+import { main } from '../index'
+import { RuntimeClientError } from '../runtime/types'
+import { okFixture, queueFixtures } from '../test-fixtures'
+
+const originalTerminalHandle = process.env.ORCA_TERMINAL_HANDLE
+const originalPaneKey = process.env.ORCA_PANE_KEY
+
+const restoreEnv = (name: string, value: string | undefined): void => {
+  if (value === undefined) {
+    delete process.env[name]
+  } else {
+    process.env[name] = value
+  }
+}
+
+describe('orchestration gate commands carry caller identity', () => {
+  let logSpy: ReturnType<typeof vi.spyOn>
+  let errorSpy: ReturnType<typeof vi.spyOn>
+
+  beforeEach(() => {
+    callMock.mockReset()
+    getTerminalHandleMock.mockReset()
+    logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+    errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    delete process.env.ORCA_TERMINAL_HANDLE
+    delete process.env.ORCA_PANE_KEY
+    process.exitCode = 0
+  })
+
+  afterEach(() => {
+    logSpy.mockRestore()
+    errorSpy.mockRestore()
+    restoreEnv('ORCA_TERMINAL_HANDLE', originalTerminalHandle)
+    restoreEnv('ORCA_PANE_KEY', originalPaneKey)
+    process.exitCode = 0
+  })
+
+  const paramsFor = (method: string): Record<string, unknown> =>
+    callMock.mock.calls.find((call) => call[0] === method)?.[1] as Record<string, unknown>
+
+  it('sends the bound coordinator handle to gateCreate', async () => {
+    process.env.ORCA_TERMINAL_HANDLE = 'term_coord'
+    queueFixtures(
+      callMock,
+      okFixture('req_show', { terminal: { handle: 'term_coord' } }),
+      okFixture('req_gate', { gate: { id: 'gate_1', task_id: 'task_1', status: 'pending' } })
+    )
+
+    await main(
+      ['orchestration', 'gate-create', '--task', 'task_1', '--question', 'ship?', '--json'],
+      '/tmp/repo'
+    )
+
+    expect(process.exitCode).toBe(0)
+    expect(paramsFor('orchestration.gateCreate')).toEqual(
+      expect.objectContaining({ task: 'task_1', question: 'ship?', from: 'term_coord' })
+    )
+  })
+
+  it('remints a stale environment handle before authorizing gateCreate', async () => {
+    process.env.ORCA_TERMINAL_HANDLE = 'term_stale'
+    process.env.ORCA_PANE_KEY = 'tab_coord:leaf_coord'
+    callMock.mockImplementation(async (method: string) => {
+      if (method === 'terminal.show') {
+        throw new RuntimeClientError('terminal_handle_stale', 'stale')
+      }
+      if (method === 'terminal.resolvePane') {
+        return okFixture('req_pane', { terminal: { handle: 'term_live' } })
+      }
+      return okFixture('req_gate', {
+        gate: { id: 'gate_1', task_id: 'task_1', status: 'pending' }
+      })
+    })
+
+    await main(
+      ['orchestration', 'gate-create', '--task', 'task_1', '--question', 'ship?', '--json'],
+      '/tmp/repo'
+    )
+
+    expect(paramsFor('orchestration.gateCreate')).toEqual(
+      expect.objectContaining({ from: 'term_live' })
+    )
+  })
+
+  it('accepts an explicit --from without probing terminal liveness', async () => {
+    queueFixtures(
+      callMock,
+      okFixture('req_gate', {
+        gate: { id: 'gate_1', task_id: 'task_1', status: 'resolved', resolution: 'go' }
+      })
+    )
+
+    await main(
+      [
+        'orchestration',
+        'gate-resolve',
+        '--id',
+        'gate_1',
+        '--resolution',
+        'go',
+        '--from',
+        'term_explicit',
+        '--json'
+      ],
+      '/tmp/repo'
+    )
+
+    expect(process.exitCode).toBe(0)
+    expect(callMock).toHaveBeenCalledTimes(1)
+    expect(paramsFor('orchestration.gateResolve')).toEqual(
+      expect.objectContaining({ id: 'gate_1', resolution: 'go', from: 'term_explicit' })
+    )
+  })
+
+  it('scopes gate-list to the caller when no Run is named', async () => {
+    process.env.ORCA_TERMINAL_HANDLE = 'term_coord'
+    queueFixtures(
+      callMock,
+      okFixture('req_show', { terminal: { handle: 'term_coord' } }),
+      okFixture('req_list', { gates: [], count: 0 })
+    )
+
+    await main(['orchestration', 'gate-list', '--json'], '/tmp/repo')
+
+    expect(process.exitCode).toBe(0)
+    expect(paramsFor('orchestration.gateList')).toEqual(
+      expect.objectContaining({ from: 'term_coord', run: undefined })
+    )
+  })
+
+  it('inspects a named Run without resolving a caller terminal', async () => {
+    // Why: read-only inspection must stay reachable from a pane with no bound Run.
+    getTerminalHandleMock.mockRejectedValue(
+      new RuntimeClientError('no_active_terminal', 'no active terminal')
+    )
+    queueFixtures(
+      callMock,
+      okFixture('req_list', {
+        gates: [{ id: 'gate_1', task_id: 'task_1', question: 'ship?', status: 'pending' }],
+        count: 1
+      })
+    )
+
+    await main(['orchestration', 'gate-list', '--run', 'run_adopted', '--json'], '/tmp/repo')
+
+    expect(process.exitCode).toBe(0)
+    expect(getTerminalHandleMock).not.toHaveBeenCalled()
+    expect(paramsFor('orchestration.gateList')).toEqual(
+      expect.objectContaining({ run: 'run_adopted', from: undefined })
+    )
+  })
+
+  it('fails an unbound gate-create with an actionable error and no mutation', async () => {
+    getTerminalHandleMock.mockRejectedValue(
+      new RuntimeClientError('no_active_terminal', 'no active terminal')
+    )
+
+    await main(
+      ['orchestration', 'gate-create', '--task', 'task_1', '--question', 'ship?'],
+      '/tmp/repo'
+    )
+
+    expect(process.exitCode).toBe(1)
+    const stderr = errorSpy.mock.calls.map((call) => String(call[0])).join('\n')
+    expect(stderr).toContain('Pass --from <terminal-handle>')
+    expect(callMock).not.toHaveBeenCalledWith('orchestration.gateCreate', expect.anything())
+  })
+})
diff --git a/src/cli/handlers/orchestration.ts b/src/cli/handlers/orchestration.ts
index 92a149cbcde..d797cfbab1b 100644
--- a/src/cli/handlers/orchestration.ts
+++ b/src/cli/handlers/orchestration.ts
@@ -1093,13 +1093,15 @@ export const ORCHESTRATION_HANDLERS: Record<string, CommandHandler> = {
     )
   },
 
-  'orchestration gate-create': async ({ flags, client, json }) => {
+  'orchestration gate-create': async ({ flags, client, cwd, json }) => {
     const result = await callMutation<{
       gate: { id: string; task_id: string; status: string }
     }>(client, flags, 'orchestration.gateCreate', {
       task: getRequiredStringFlag(flags, 'task'),
       question: getRequiredStringFlag(flags, 'question'),
-      options: getOptionalStringFlag(flags, 'options')
+      options: getOptionalStringFlag(flags, 'options'),
+      // Why: gates are Run-scoped, so the coordinator handle is the caller identity the runtime authorizes against.
+      from: await resolveCoordinatorTerminalHandle(flags, cwd, client)
     })
     printResult(
       result,
@@ -1108,23 +1110,30 @@ export const ORCHESTRATION_HANDLERS: Record<string, CommandHandler> = {
     )
   },
 
-  'orchestration gate-resolve': async ({ flags, client, json }) => {
+  'orchestration gate-resolve': async ({ flags, client, cwd, json }) => {
     const result = await callMutation<{
       gate: { id: string; task_id: string; status: string; resolution: string }
     }>(client, flags, 'orchestration.gateResolve', {
       id: getRequiredStringFlag(flags, 'id'),
-      resolution: getRequiredStringFlag(flags, 'resolution')
+      resolution: getRequiredStringFlag(flags, 'resolution'),
+      from: await resolveCoordinatorTerminalHandle(flags, cwd, client)
     })
     printResult(result, json, (r) => `Gate ${r.gate.id} resolved: ${r.gate.resolution}`)
   },
 
-  'orchestration gate-list': async ({ flags, client, json }) => {
+  'orchestration gate-list': async ({ flags, client, cwd, json }) => {
+    const run = getOptionalStringFlag(flags, 'run')
+    // Why: same read posture as task-list — an explicitly named Run stays inspectable without a bound pane, so identity is only resolved for the implicit "my own Run" case.
+    const from = run ? undefined : await resolveCoordinatorTerminalHandle(flags, cwd, client)
     const result = await client.call<{
       gates: { id: string; task_id: string; question: string; status: string }[]
       count: number
+      runId?: string
     }>('orchestration.gateList', {
       task: getOptionalStringFlag(flags, 'task'),
-      status: getOptionalStringFlag(flags, 'status')
+      status: getOptionalStringFlag(flags, 'status'),
+      run,
+      from
     })
     printResult(result, json, (r) => {
       if (r.gates.length === 0) {
diff --git a/src/cli/specs/orchestration.ts b/src/cli/specs/orchestration.ts
index f90f6f99872..5161960e0fc 100644
--- a/src/cli/specs/orchestration.ts
+++ b/src/cli/specs/orchestration.ts
@@ -236,20 +236,23 @@ export const ORCHESTRATION_COMMAND_SPECS: CommandSpec[] = [
     path: ['orchestration', 'gate-create'],
     summary: 'Create a decision gate blocking a task',
     usage:
-      'orca orchestration gate-create --task <task_id> --question <text> [--options <json_array>] [--json]',
-    allowedFlags: [...GLOBAL_FLAGS, 'task', 'question', 'options', 'retry-request']
+      'orca orchestration gate-create --task <task_id> --question <text> [--options <json_array>] [--from <handle>] [--json]',
+    allowedFlags: [...GLOBAL_FLAGS, 'task', 'question', 'options', 'from', 'retry-request']
   },
   {
     path: ['orchestration', 'gate-resolve'],
     summary: 'Resolve a pending decision gate',
-    usage: 'orca orchestration gate-resolve --id <gate_id> --resolution <text> [--json]',
-    allowedFlags: [...GLOBAL_FLAGS, 'id', 'resolution', 'retry-request']
+    usage:
+      'orca orchestration gate-resolve --id <gate_id> --resolution <text> [--from <handle>] [--json]',
+    allowedFlags: [...GLOBAL_FLAGS, 'id', 'resolution', 'from', 'retry-request']
   },
   {
     path: ['orchestration', 'gate-list'],
     summary: 'List decision gates',
-    usage: 'orca orchestration gate-list [--task <task_id>] [--status <status>] [--json]',
-    allowedFlags: [...GLOBAL_FLAGS, 'task', 'status']
+    usage:
+      'orca orchestration gate-list [--task <task_id>] [--status <status>] [--run <run_id>] [--from <handle>] [--json]',
+    allowedFlags: [...GLOBAL_FLAGS, 'task', 'status', 'run', 'from'],
+    notes: ['--run inspects a named Run without binding; otherwise gates are scoped to the caller.']
   },
   {
     path: ['orchestration', 'reset'],
diff --git a/src/main/runtime/orchestration/db.ts b/src/main/runtime/orchestration/db.ts
index 145aa862ee1..369032012e4 100644
--- a/src/main/runtime/orchestration/db.ts
+++ b/src/main/runtime/orchestration/db.ts
@@ -55,6 +55,16 @@ function isEquivalentPaneKey(a: string, b: string): boolean {
   return Boolean(aLeaf && bLeaf && aLeaf === bLeaf)
 }
 
+// Why: indexable pre-filter for isEquivalentPaneKey — equal strings and equal leaves both share the
+// text after the first ':', so this narrows candidates without deciding equivalence itself.
+const PANE_KEY_MATCH_SUFFIX_SQL =
+  "substr(coordinator_pane_key, instr(coordinator_pane_key, ':') + 1)"
+
+function paneKeyMatchSuffix(paneKey: string): string {
+  const colon = paneKey.indexOf(':')
+  return colon < 0 ? paneKey : paneKey.slice(colon + 1)
+}
+
 export type {
   MessageType,
   MessagePriority,
@@ -511,6 +521,10 @@ export class OrchestrationDb {
       CREATE INDEX IF NOT EXISTS idx_gates_task ON decision_gates(task_id);
       CREATE INDEX IF NOT EXISTS idx_gates_status ON decision_gates(status);
 
+      CREATE INDEX IF NOT EXISTS idx_runs_coordinator_pane_leaf
+        ON runs(${PANE_KEY_MATCH_SUFFIX_SQL})
+        WHERE coordinator_pane_key IS NOT NULL;
+
       CREATE TABLE IF NOT EXISTS coordinator_runs (
         id                  TEXT PRIMARY KEY,
         spec                TEXT NOT NULL,
@@ -2245,6 +2259,8 @@ export class OrchestrationDb {
           'Legacy takeover is only available for the automatically adopted Run.'
         )
       }
+      // Why: only LIVE legacy work needs the flag — settled work has no competing authority left, and
+      // fencing it would strand the recovered graph behind an attestation the caller may not have.
       if (
         activeLegacyAssignment &&
         !sameBinding &&
@@ -2338,31 +2354,35 @@ export class OrchestrationDb {
   }
 
   getCurrentRunForPane(paneKey: string): RunRow | undefined {
-    const runs = this.db
-      .prepare('SELECT * FROM runs WHERE coordinator_pane_key IS NOT NULL AND legacy = 0')
-      .all() as RunRow[]
-    const run = runs.find(
-      (candidate) =>
-        candidate.coordinator_pane_key !== null &&
-        isEquivalentPaneKey(candidate.coordinator_pane_key, paneKey)
-    )
+    const run = this.runsBoundToPane(paneKey)[0]
     return run ? exposeRunTimestamps(run) : undefined
   }
 
+  // Why: the indexed suffix only narrows candidates; isEquivalentPaneKey still decides, so
+  // reminted tab halves keep matching and unparseable keys keep requiring an exact match.
+  private runsBoundToPane(paneKey: string): RunRow[] {
+    return (
+      this.db
+        .prepare(
+          `SELECT * FROM runs
+           WHERE coordinator_pane_key IS NOT NULL AND legacy = 0
+             AND ${PANE_KEY_MATCH_SUFFIX_SQL} = ?
+           ORDER BY rowid`
+        )
+        .all(paneKeyMatchSuffix(paneKey)) as RunRow[]
+    ).filter(
+      (run) =>
+        run.coordinator_pane_key !== null && isEquivalentPaneKey(run.coordinator_pane_key, paneKey)
+    )
+  }
+
   private getRunRaw(id: string): RunRow | undefined {
     return this.db.prepare('SELECT * FROM runs WHERE id = ?').get(id) as RunRow | undefined
   }
 
   private unbindOtherRunsForPane(paneKey: string, exceptRunId?: string): void {
-    const bound = this.db
-      .prepare('SELECT * FROM runs WHERE coordinator_pane_key IS NOT NULL AND legacy = 0')
-      .all() as RunRow[]
-    for (const run of bound) {
-      if (
-        run.id !== exceptRunId &&
-        run.coordinator_pane_key &&
-        isEquivalentPaneKey(run.coordinator_pane_key, paneKey)
-      ) {
+    for (const run of this.runsBoundToPane(paneKey)) {
+      if (run.id !== exceptRunId) {
         this.db
           .prepare(
             `UPDATE runs
diff --git a/src/main/runtime/orchestration/orchestration-adopted-run-binding.test.ts b/src/main/runtime/orchestration/orchestration-adopted-run-binding.test.ts
new file mode 100644
index 00000000000..db6a63ef790
--- /dev/null
+++ b/src/main/runtime/orchestration/orchestration-adopted-run-binding.test.ts
@@ -0,0 +1,375 @@
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import type Database from '../../sqlite/sync-database'
+import SyncDatabase from '../../sqlite/sync-database'
+import { OrchestrationDb } from './db'
+
+const LEGACY_COORDINATOR_HANDLE = 'term_legacy_coord'
+const LEGACY_COORDINATOR_PANE = 'tab_coord:44444444-4444-4444-8444-444444444444'
+const LEGACY_WORKER_HANDLE = 'term_legacy_worker'
+const LEGACY_WORKER_PANE = 'tab_worker:33333333-3333-4333-8333-333333333333'
+const CURRENT_COORDINATOR_HANDLE = 'term_current_coord'
+const CURRENT_COORDINATOR_PANE = 'tab_current:11111111-1111-4111-8111-111111111111'
+
+const tempDirs: string[] = []
+const databases: OrchestrationDb[] = []
+
+afterEach(() => {
+  for (const database of databases.splice(0)) {
+    database.close()
+  }
+  for (const dir of tempDirs.splice(0)) {
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+function track(db: OrchestrationDb): OrchestrationDb {
+  databases.push(db)
+  return db
+}
+
+type AdoptedFixture = {
+  db: OrchestrationDb
+  adoptedRunId: string
+  taskId: string
+  dispatchId: string
+  recoveryMessageId: string
+}
+
+/** Builds a pre-cutover graph at schema 18 and reopens it so adoption runs. */
+function createAdoptedFixture(options: { settleWork: boolean }): AdoptedFixture {
+  const dir = mkdtempSync(join(tmpdir(), 'orca-adopted-bind-'))
+  tempDirs.push(dir)
+  const dbPath = join(dir, 'orchestration.db')
+
+  const before = new OrchestrationDb(dbPath)
+  const task = before.createTask({
+    spec: 'legacy assignment',
+    createdByTerminalHandle: LEGACY_COORDINATOR_HANDLE
+  })
+  const dispatch = before.createDispatchContext(task.id, LEGACY_WORKER_HANDLE, LEGACY_WORKER_PANE)
+  const recovery = before.insertMessage({
+    from: LEGACY_WORKER_HANDLE,
+    to: LEGACY_COORDINATOR_HANDLE,
+    subject: 'recovered worker outcome',
+    type: 'worker_done'
+  })
+  before.close()
+
+  const raw = new SyncDatabase(dbPath)
+  if (options.settleWork) {
+    raw.exec("UPDATE dispatch_contexts SET status = 'completed'")
+  }
+  raw.exec(`
+    DROP INDEX IF EXISTS idx_messages_delivery_contract;
+    DROP TABLE legacy_mail_receipts;
+    DROP TABLE legacy_operation_receipts;
+    DROP TABLE legacy_compatibility_principals;
+    DROP TABLE legacy_adoptions;
+  `)
+  raw.pragma('user_version = 18')
+  raw.close()
+
+  const db = track(new OrchestrationDb(dbPath))
+  return {
+    db,
+    adoptedRunId: db.getLegacyAdoption()?.adopted_run_id as string,
+    taskId: task.id,
+    dispatchId: dispatch.id,
+    recoveryMessageId: recovery.id
+  }
+}
+
+function commitLegacyCoordinator(db: OrchestrationDb, runId: string): string {
+  return db.commitLegacyCompatibilityPrincipal({
+    runId,
+    role: 'coordinator',
+    hostScope: 'local:runtime_1',
+    terminalHandle: LEGACY_COORDINATOR_HANDLE,
+    paneKey: LEGACY_COORDINATOR_PANE,
+    launchTokenHash: 'coord_launch_hash',
+    processIncarnation: 'process_coord'
+  }).principal.id
+}
+
+// Why: --takeover-legacy guards LIVE legacy work only. Settled work has no competing authority to
+// seize, and requiring the flag there would strand the recovered graph behind an attestation the
+// caller may not hold (runUse rejects the flag unless caller authority matches the binding pane).
+describe('adopted Run binding without --takeover-legacy', () => {
+  it('fences a bind while legacy work is still live, and names the recovery command', () => {
+    const { db, adoptedRunId } = createAdoptedFixture({ settleWork: false })
+
+    expect(() =>
+      db.bindRun({
+        runId: adoptedRunId,
+        coordinatorHandle: CURRENT_COORDINATOR_HANDLE,
+        coordinatorPaneKey: CURRENT_COORDINATOR_PANE
+      })
+    ).toThrowError(
+      expect.objectContaining({
+        code: 'consumer_fenced',
+        data: {
+          effectsApplied: false,
+          recoveryCommand: `orca orchestration run-use --id ${adoptedRunId} --takeover-legacy`
+        }
+      })
+    )
+    expect(db.getRun(adoptedRunId)).toMatchObject({
+      coordinator_handle: null,
+      coordinator_pane_key: null,
+      consumer_generation: 0
+    })
+  })
+
+  it('claims the settled adopted Run and inherits its recovered task graph', () => {
+    const { db, adoptedRunId } = createAdoptedFixture({ settleWork: true })
+
+    const run = db.bindRun({
+      runId: adoptedRunId,
+      coordinatorHandle: CURRENT_COORDINATOR_HANDLE,
+      coordinatorPaneKey: CURRENT_COORDINATOR_PANE
+    })
+
+    expect(run).toMatchObject({
+      coordinator_handle: CURRENT_COORDINATOR_HANDLE,
+      coordinator_pane_key: CURRENT_COORDINATOR_PANE,
+      consumer_generation: 1
+    })
+    expect(db.listTasks({ runId: adoptedRunId })).toHaveLength(1)
+    expect(db.getCurrentRunForPane(CURRENT_COORDINATOR_PANE)?.id).toBe(adoptedRunId)
+  })
+
+  // Why: this is what makes the unflagged claim safe — the recovered coordinator's mail is not orphaned.
+  it('promotes the retained coordinator mail onto the claiming Run', () => {
+    const { db, adoptedRunId, recoveryMessageId } = createAdoptedFixture({ settleWork: true })
+    expect(db.getMessageById(recoveryMessageId)).toMatchObject({
+      to_handle: LEGACY_COORDINATOR_HANDLE,
+      delivery_contract: 'legacy_direct'
+    })
+
+    const run = db.bindRun({
+      runId: adoptedRunId,
+      coordinatorHandle: CURRENT_COORDINATOR_HANDLE,
+      coordinatorPaneKey: CURRENT_COORDINATOR_PANE
+    })!
+
+    expect(db.getMessageById(recoveryMessageId)).toMatchObject({
+      to_handle: `run:${adoptedRunId}`,
+      delivery_contract: 'current_delivery',
+      read: 0
+    })
+    expect(
+      db
+        .getOrCreateRunDelivery({
+          runId: adoptedRunId,
+          consumerGeneration: run.consumer_generation
+        })
+        ?.messages.map((message) => message.id)
+    ).toContain(recoveryMessageId)
+  })
+
+  it('revokes an attested legacy coordinator when it claims the settled Run', () => {
+    const { db, adoptedRunId } = createAdoptedFixture({ settleWork: true })
+    const principalId = commitLegacyCoordinator(db, adoptedRunId)
+
+    db.bindRun({
+      runId: adoptedRunId,
+      coordinatorHandle: CURRENT_COORDINATOR_HANDLE,
+      coordinatorPaneKey: CURRENT_COORDINATOR_PANE
+    })
+
+    expect(db.getLegacyCompatibilityPrincipal(principalId)?.status).toBe('revoked')
+  })
+
+  // Why: the acknowledgement is per claimant, not one-shot — a prior takeover does not license the next.
+  it('keeps fencing new claimants while legacy work stays live', () => {
+    const { db, adoptedRunId } = createAdoptedFixture({ settleWork: false })
+    db.bindRun({
+      runId: adoptedRunId,
+      coordinatorHandle: CURRENT_COORDINATOR_HANDLE,
+      coordinatorPaneKey: CURRENT_COORDINATOR_PANE,
+      takeoverLegacy: true
+    })
+
+    expect(() =>
+      db.bindRun({
+        runId: adoptedRunId,
+        coordinatorHandle: 'term_second_coord',
+        coordinatorPaneKey: 'tab_second:22222222-2222-4222-8222-222222222222'
+      })
+    ).toThrowError(expect.objectContaining({ code: 'consumer_fenced' }))
+  })
+
+  it('lets a later coordinator claim the settled Run once the first one has', () => {
+    const { db, adoptedRunId } = createAdoptedFixture({ settleWork: true })
+    db.bindRun({
+      runId: adoptedRunId,
+      coordinatorHandle: CURRENT_COORDINATOR_HANDLE,
+      coordinatorPaneKey: CURRENT_COORDINATOR_PANE
+    })
+
+    expect(
+      db.bindRun({
+        runId: adoptedRunId,
+        coordinatorHandle: 'term_second_coord',
+        coordinatorPaneKey: 'tab_second:22222222-2222-4222-8222-222222222222'
+      })
+    ).toMatchObject({ coordinator_handle: 'term_second_coord', consumer_generation: 2 })
+  })
+})
+
+// Why: the SQL narrows on the text after the first ':' — a superset of leaf-equivalence — so the
+// JS isEquivalentPaneKey filter stays authoritative. These pin both halves of that contract.
+describe('pane-bound Run lookup', () => {
+  function explain(db: OrchestrationDb, paneKey: string): string {
+    const sqlite = (db as unknown as { db: Database.Database }).db
+    return (
+      sqlite
+        .prepare(
+          `EXPLAIN QUERY PLAN
+           SELECT * FROM runs
+           WHERE coordinator_pane_key IS NOT NULL AND legacy = 0
+             AND substr(coordinator_pane_key, instr(coordinator_pane_key, ':') + 1) = ?
+           ORDER BY rowid`
+        )
+        .all(paneKey) as { detail: string }[]
+    )
+      .map((row) => row.detail)
+      .join(' | ')
+  }
+
+  it('matches a reminted tab half by leaf UUID', () => {
+    const db = track(new OrchestrationDb(':memory:'))
+    const run = db.createRun({
+      objective: 'work',
+      coordinatorHandle: 'term_a',
+      coordinatorPaneKey: 'tab_original:77777777-7777-4777-8777-777777777777'
+    })
+
+    expect(db.getCurrentRunForPane('tab_broken_out:77777777-7777-4777-8777-777777777777')?.id).toBe(
+      run.id
+    )
+  })
+
+  it('requires an exact match for keys that do not parse', () => {
+    const db = track(new OrchestrationDb(':memory:'))
+    // Extra ':' makes parsePaneKey return null even though the leaf-looking suffix matches.
+    const unparseable = 'tab:extra:88888888-8888-4888-8888-888888888888'
+    db.createRun({
+      objective: 'unparseable',
+      coordinatorHandle: 'term_b',
+      coordinatorPaneKey: unparseable
+    })
+
+    expect(db.getCurrentRunForPane(unparseable)?.coordinator_pane_key).toBe(unparseable)
+    expect(
+      db.getCurrentRunForPane('tab_other:88888888-8888-4888-8888-888888888888')
+    ).toBeUndefined()
+  })
+
+  it('matches colon-free keys only on exact equality', () => {
+    const db = track(new OrchestrationDb(':memory:'))
+    db.createRun({ objective: 'flat', coordinatorHandle: 'term_c', coordinatorPaneKey: 'flatkey' })
+
+    expect(db.getCurrentRunForPane('flatkey')?.objective).toBe('flat')
+    expect(db.getCurrentRunForPane('tab:flatkey')).toBeUndefined()
+  })
+
+  it('unbinds only the leaf-equivalent Run when a pane rebinds', () => {
+    const db = track(new OrchestrationDb(':memory:'))
+    const shared = db.createRun({
+      objective: 'first',
+      coordinatorHandle: 'term_d',
+      coordinatorPaneKey: 'tab_one:99999999-9999-4999-8999-999999999999'
+    })
+    const untouched = db.createRun({
+      objective: 'other pane',
+      coordinatorHandle: 'term_e',
+      coordinatorPaneKey: 'tab_two:aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa'
+    })
+
+    const rebound = db.createRun({
+      objective: 'second',
+      coordinatorHandle: 'term_d',
+      coordinatorPaneKey: 'tab_reminted:99999999-9999-4999-8999-999999999999'
+    })
+
+    // createRun binds at generation 1; the unbind fences it to 2.
+    expect(db.getRun(shared.id)).toMatchObject({
+      coordinator_pane_key: null,
+      consumer_generation: 2
+    })
+    expect(db.getRun(untouched.id)).toMatchObject({
+      coordinator_pane_key: 'tab_two:aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa'
+    })
+    expect(db.getCurrentRunForPane('tab_one:99999999-9999-4999-8999-999999999999')?.id).toBe(
+      rebound.id
+    )
+  })
+
+  it('stays flat as the bound-Run set grows', () => {
+    const db = track(new OrchestrationDb(':memory:'))
+    const leafOf = (i: number) => `${i.toString(16).padStart(8, '0')}-1111-4111-8111-111111111111`
+    const bind = (from: number, to: number): void => {
+      for (let i = from; i < to; i++) {
+        db.createRun({
+          objective: `run ${i}`,
+          coordinatorHandle: `term_${i}`,
+          coordinatorPaneKey: `tab_${i}:${leafOf(i)}`
+        })
+      }
+    }
+    const probe = `tab_reminted:${leafOf(0)}`
+    const measure = (): number => {
+      for (let i = 0; i < 200; i++) {
+        db.getCurrentRunForPane(probe)
+      }
+      const start = performance.now()
+      for (let i = 0; i < 2000; i++) {
+        db.getCurrentRunForPane(probe)
+      }
+      return (performance.now() - start) / 2000
+    }
+
+    bind(0, 61)
+    expect(db.getCurrentRunForPane(probe)).toBeDefined()
+    const small = measure()
+    bind(61, 2001)
+    const large = measure()
+
+    // The pre-index scan grew ~28x across this range; the index keeps it flat.
+    expect(large).toBeLessThan(small * 6)
+    expect(explain(db, 'x')).toContain('USING INDEX idx_runs_coordinator_pane_leaf')
+  })
+
+  it('hands the JS filter an O(1) candidate set regardless of bound-Run count', () => {
+    const db = track(new OrchestrationDb(':memory:'))
+    const sqlite = (db as unknown as { db: Database.Database }).db
+    const leaf = 'bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb'
+    for (let i = 0; i < 500; i++) {
+      db.createRun({
+        objective: `run ${i}`,
+        coordinatorHandle: `term_${i}`,
+        coordinatorPaneKey: `tab_${i}:${i.toString(16).padStart(8, '0')}-1111-4111-8111-111111111111`
+      })
+    }
+    db.createRun({
+      objective: 'target',
+      coordinatorHandle: 'term_target',
+      coordinatorPaneKey: `tab_target:${leaf}`
+    })
+
+    const candidates = sqlite
+      .prepare(
+        `SELECT id FROM runs
+         WHERE coordinator_pane_key IS NOT NULL AND legacy = 0
+           AND substr(coordinator_pane_key, instr(coordinator_pane_key, ':') + 1) = ?`
+      )
+      .all(leaf) as { id: string }[]
+
+    expect(candidates).toHaveLength(1)
+    expect(db.getCurrentRunForPane(`tab_reminted:${leaf}`)?.objective).toBe('target')
+  })
+})
diff --git a/src/main/runtime/rpc/core.ts b/src/main/runtime/rpc/core.ts
index 93421c8b252..8e09e942a08 100644
--- a/src/main/runtime/rpc/core.ts
+++ b/src/main/runtime/rpc/core.ts
@@ -88,6 +88,8 @@ export type RpcContext = {
     method: string
     payloadHash: string
   }
+  // Why: Run-scoped handlers must compare declared handles with request attestation.
+  orchestrationCompatibilityEvidence?: OrchestrationCompatibilityEvidence
   // Why: only the compatibility authority router can set this trusted scope; user params cannot bypass Run consumer binding.
   legacyCoordinatorRunId?: string
   legacyCoordinatorAuthority?: LegacyCoordinatorAuthorityProof
diff --git a/src/main/runtime/rpc/dispatcher.ts b/src/main/runtime/rpc/dispatcher.ts
index ad2ba1a1eec..be11b2b0c64 100644
--- a/src/main/runtime/rpc/dispatcher.ts
+++ b/src/main/runtime/rpc/dispatcher.ts
@@ -104,7 +104,8 @@ export class RpcDispatcher {
           legacyCoordinatorAuthority: legacyCoordinator?.authority,
           revalidateLegacyCoordinator: legacyCoordinator?.revalidate,
           orchestrationCompatibilityCallerAuthority:
-            compatibility.orchestrationCompatibilityCallerAuthority
+            compatibility.orchestrationCompatibilityCallerAuthority,
+          orchestrationCompatibilityEvidence: request.orchestrationCompatibilityEvidence
         })
       }
       const result = await this.orchestrationMutations.run(
@@ -199,7 +200,8 @@ export class RpcDispatcher {
             legacyCoordinatorAuthority: legacyCoordinator?.authority,
             revalidateLegacyCoordinator: legacyCoordinator?.revalidate,
             orchestrationCompatibilityCallerAuthority:
-              compatibility.orchestrationCompatibilityCallerAuthority
+              compatibility.orchestrationCompatibilityCallerAuthority,
+            orchestrationCompatibilityEvidence: request.orchestrationCompatibilityEvidence
           })
         }
         const result = await this.orchestrationMutations.run(
diff --git a/src/main/runtime/rpc/methods/orchestration-gate-run-authorization.test.ts b/src/main/runtime/rpc/methods/orchestration-gate-run-authorization.test.ts
new file mode 100644
index 00000000000..ee18c366185
--- /dev/null
+++ b/src/main/runtime/rpc/methods/orchestration-gate-run-authorization.test.ts
@@ -0,0 +1,315 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import {
+  cleanupLegacyCompatibilityDispatcherHarnesses,
+  COORDINATOR_HANDLE,
+  createHarness,
+  currentEvidence,
+  CURRENT_COORDINATOR_HANDLE,
+  CURRENT_COORDINATOR_PANE,
+  evidence,
+  invoke,
+  request,
+  type LegacyCompatibilityDispatcherHarness
+} from '../orchestration-legacy-compatibility-dispatcher-test-fixture'
+
+const STRANGER_HANDLE = 'term_stranger_coord'
+const STRANGER_PANE = 'tab_stranger:77777777-7777-4777-8777-777777777777'
+
+afterEach(() => {
+  cleanupLegacyCompatibilityDispatcherHarnesses()
+})
+
+function bindCurrentCoordinatorRun(harness: LegacyCompatibilityDispatcherHarness): string {
+  return harness.db.createRun({
+    objective: 'current work',
+    coordinatorHandle: CURRENT_COORDINATOR_HANDLE,
+    coordinatorPaneKey: CURRENT_COORDINATOR_PANE
+  }).id
+}
+
+// Why: the adopted Run's recovered task is the cross-Run target; its dispatch must stay live when a gate is refused.
+function adoptedTaskState(harness: LegacyCompatibilityDispatcherHarness) {
+  return {
+    task: harness.db.getTask(harness.taskId)?.status,
+    dispatch: harness.db.getDispatchContextById(harness.dispatchId)?.status,
+    gates: harness.db.listGates({ taskId: harness.taskId }).length
+  }
+}
+
+const UNATTESTED_CURRENT_COORDINATOR = { ...currentEvidence('coordinator'), launchToken: '' }
+
+describe('orchestration gate Run authorization', () => {
+  it.each(['dispatch', 'websocket'] as const)(
+    'G1 %s refuses an unbound attested caller creating a gate on the adopted Run',
+    async (transport) => {
+      const harness = createHarness()
+      const before = adoptedTaskState(harness)
+
+      const response = await invoke(
+        harness.dispatcher,
+        request(
+          'orchestration.gateCreate',
+          { task: harness.taskId, question: 'Proceed?' },
+          currentEvidence('coordinator'),
+          `g1-unbound-gate-create-${transport}`
+        ),
+        transport
+      )
+
+      expect(response).toMatchObject({ ok: false, error: { code: 'run_required' } })
+      expect(adoptedTaskState(harness)).toEqual(before)
+    }
+  )
+
+  it('G2 refuses an unattested caller creating a gate on another Run task', async () => {
+    const harness = createHarness()
+    const runA = bindCurrentCoordinatorRun(harness)
+    const before = adoptedTaskState(harness)
+
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.gateCreate',
+        { task: harness.taskId, question: 'Proceed?', from: CURRENT_COORDINATOR_HANDLE },
+        UNATTESTED_CURRENT_COORDINATOR,
+        'g2-cross-run-gate-create'
+      )
+    )
+
+    expect(response).toMatchObject({
+      ok: false,
+      error: {
+        code: 'task_not_found',
+        message: `Task ${harness.taskId} was not found in Run ${runA}.`
+      }
+    })
+    expect(adoptedTaskState(harness)).toEqual(before)
+  })
+
+  it('G2 refuses the same caller when it names no sender terminal at all', async () => {
+    const harness = createHarness()
+    bindCurrentCoordinatorRun(harness)
+    const before = adoptedTaskState(harness)
+
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.gateCreate',
+        { task: harness.taskId, question: 'Proceed?' },
+        UNATTESTED_CURRENT_COORDINATOR,
+        'g2-anonymous-gate-create'
+      )
+    )
+
+    expect(response).toMatchObject({ ok: false, error: { code: 'run_required' } })
+    expect(adoptedTaskState(harness)).toEqual(before)
+  })
+
+  it('G3 refuses an unattested caller once the adopted Run is claimed', async () => {
+    const harness = createHarness()
+    const claim = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.runUse',
+        { id: harness.adoptedRunId, from: COORDINATOR_HANDLE },
+        evidence('coordinator'),
+        'g3-legacy-claim'
+      )
+    )
+    expect(claim).toMatchObject({ ok: true })
+    bindCurrentCoordinatorRun(harness)
+    const before = adoptedTaskState(harness)
+
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.gateCreate',
+        { task: harness.taskId, question: 'Proceed?', from: CURRENT_COORDINATOR_HANDLE },
+        UNATTESTED_CURRENT_COORDINATOR,
+        'g3-claimed-gate-create'
+      )
+    )
+
+    expect(response).toMatchObject({ ok: false })
+    expect(adoptedTaskState(harness)).toEqual(before)
+  })
+
+  it('G4 refuses an attested bound caller creating a gate in a stranger Run', async () => {
+    const harness = createHarness()
+    const runA = bindCurrentCoordinatorRun(harness)
+    const strangerRun = harness.db.createRun({
+      objective: 'stranger work',
+      coordinatorHandle: STRANGER_HANDLE,
+      coordinatorPaneKey: STRANGER_PANE
+    })
+    const strangerTask = harness.db.createTask({
+      spec: 'stranger assignment',
+      runId: strangerRun.id
+    })
+
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.gateCreate',
+        { task: strangerTask.id, question: 'Proceed?', from: CURRENT_COORDINATOR_HANDLE },
+        currentEvidence('coordinator'),
+        'g4-stranger-gate-create'
+      )
+    )
+
+    expect(response).toMatchObject({
+      ok: false,
+      error: {
+        code: 'task_not_found',
+        message: `Task ${strangerTask.id} was not found in Run ${runA}.`
+      }
+    })
+    expect(harness.db.getTask(strangerTask.id)?.status).toBe('ready')
+    expect(harness.db.listGates({ taskId: strangerTask.id })).toHaveLength(0)
+  })
+
+  it('G4 refuses the stranger Run even when it is named explicitly', async () => {
+    const harness = createHarness()
+    const runA = bindCurrentCoordinatorRun(harness)
+    const strangerRun = harness.db.createRun({
+      objective: 'stranger work',
+      coordinatorHandle: STRANGER_HANDLE,
+      coordinatorPaneKey: STRANGER_PANE
+    })
+    const strangerTask = harness.db.createTask({
+      spec: 'stranger assignment',
+      runId: strangerRun.id
+    })
+
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.gateCreate',
+        {
+          task: strangerTask.id,
+          question: 'Proceed?',
+          from: CURRENT_COORDINATOR_HANDLE,
+          run: strangerRun.id
+        },
+        currentEvidence('coordinator'),
+        'g4-explicit-stranger-gate-create'
+      )
+    )
+
+    expect(response).toMatchObject({
+      ok: false,
+      error: {
+        code: 'consumer_fenced',
+        message: `This coordinator terminal is bound to ${runA}, not ${strangerRun.id}.`
+      }
+    })
+    expect(harness.db.getTask(strangerTask.id)?.status).toBe('ready')
+  })
+
+  it('G5 refuses an unattested caller resolving another Run gate', async () => {
+    const harness = createHarness()
+    bindCurrentCoordinatorRun(harness)
+    const gate = harness.db.createGate({ taskId: harness.taskId, question: 'Proceed?' })
+
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.gateResolve',
+        { id: gate.id, resolution: 'yes', from: CURRENT_COORDINATOR_HANDLE },
+        UNATTESTED_CURRENT_COORDINATOR,
+        'g5-cross-run-gate-resolve'
+      )
+    )
+
+    expect(response).toMatchObject({ ok: false, error: { message: `Gate not found: ${gate.id}` } })
+    expect(harness.db.getGate(gate.id)?.status).toBe('pending')
+    expect(harness.db.getTask(harness.taskId)?.status).toBe('blocked')
+  })
+
+  it('keeps gate-list from leaking gates outside the caller Run', async () => {
+    const harness = createHarness()
+    const runA = bindCurrentCoordinatorRun(harness)
+    const ownTask = harness.db.createTask({ spec: 'own assignment', runId: runA })
+    const ownGate = harness.db.createGate({ taskId: ownTask.id, question: 'Own?' })
+    harness.db.createGate({ taskId: harness.taskId, question: 'Adopted?' })
+
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.gateList',
+        { from: CURRENT_COORDINATOR_HANDLE },
+        currentEvidence('coordinator'),
+        'gate-list-scope'
+      )
+    )
+
+    expect(response).toMatchObject({
+      ok: true,
+      result: { runId: runA, count: 1, gates: [{ id: ownGate.id }] }
+    })
+  })
+
+  it('lets the bound coordinator create, list, and resolve its own Run gates', async () => {
+    const harness = createHarness()
+    const runA = bindCurrentCoordinatorRun(harness)
+    const ownTask = harness.db.createTask({ spec: 'own assignment', runId: runA })
+
+    const created = (await harness.dispatcher.dispatch(
+      request(
+        'orchestration.gateCreate',
+        {
+          task: ownTask.id,
+          question: 'Ship it?',
+          options: JSON.stringify(['yes', 'no']),
+          from: CURRENT_COORDINATOR_HANDLE
+        },
+        currentEvidence('coordinator'),
+        'own-gate-create'
+      )
+    )) as { ok: true; result: { gate: { id: string } } }
+
+    expect(created).toMatchObject({ ok: true, result: { gate: { task_id: ownTask.id } } })
+    expect(harness.db.getTask(ownTask.id)?.status).toBe('blocked')
+
+    const resolved = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.gateResolve',
+        {
+          id: created.result.gate.id,
+          resolution: 'yes',
+          from: CURRENT_COORDINATOR_HANDLE
+        },
+        currentEvidence('coordinator'),
+        'own-gate-resolve'
+      )
+    )
+
+    expect(resolved).toMatchObject({
+      ok: true,
+      result: { gate: { status: 'resolved', resolution: 'yes' } }
+    })
+    expect(harness.db.getTask(ownTask.id)?.status).toBe('ready')
+  })
+
+  it('keeps the retained legacy coordinator operating on the adopted Run', async () => {
+    const harness = createHarness()
+
+    const created = (await harness.dispatcher.dispatch(
+      request(
+        'orchestration.gateCreate',
+        { task: harness.taskId, question: 'Proceed?', from: COORDINATOR_HANDLE },
+        evidence('coordinator'),
+        'legacy-gate-create'
+      )
+    )) as { ok: true; result: { gate: { id: string; run_id: string } } }
+
+    expect(created).toMatchObject({
+      ok: true,
+      result: { gate: { task_id: harness.taskId, run_id: harness.adoptedRunId } }
+    })
+
+    const resolved = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.gateResolve',
+        { id: created.result.gate.id, resolution: 'go', from: COORDINATOR_HANDLE },
+        evidence('coordinator'),
+        'legacy-gate-resolve'
+      )
+    )
+
+    expect(resolved).toMatchObject({ ok: true, result: { gate: { status: 'resolved' } } })
+    expect(harness.db.getTask(harness.taskId)?.status).toBe('ready')
+  })
+})
diff --git a/src/main/runtime/rpc/methods/orchestration-gates.ts b/src/main/runtime/rpc/methods/orchestration-gates.ts
index 3e85f08e267..1d9c7622fe9 100644
--- a/src/main/runtime/rpc/methods/orchestration-gates.ts
+++ b/src/main/runtime/rpc/methods/orchestration-gates.ts
@@ -3,6 +3,8 @@ import { defineMethod, type RpcMethod } from '../core'
 import { OptionalFiniteNumber, OptionalString, requiredString } from '../schemas'
 import type { GateStatus } from '../../orchestration/db'
 import { Coordinator } from '../../orchestration/coordinator'
+import { resolveRunScope } from './orchestration-run-scope'
+import { OrchestrationError } from '../../orchestration/orchestration-error'
 
 // Why: the coordinator instance is stored at module scope so orchestration.runStop
 // can signal it to halt. Only one coordinator can run at a time (enforced by
@@ -22,17 +24,23 @@ const RunStopParams = z.object({})
 const GateCreateParams = z.object({
   task: requiredString('Missing --task'),
   question: requiredString('Missing --question'),
-  options: OptionalString
+  options: OptionalString,
+  from: OptionalString,
+  run: OptionalString
 })
 
 const GateResolveParams = z.object({
   id: requiredString('Missing --id'),
-  resolution: requiredString('Missing --resolution')
+  resolution: requiredString('Missing --resolution'),
+  from: OptionalString,
+  run: OptionalString
 })
 
 const GateListParams = z.object({
   task: OptionalString,
-  status: z.enum(['pending', 'resolved', 'timeout']).optional()
+  status: z.enum(['pending', 'resolved', 'timeout']).optional(),
+  from: OptionalString,
+  run: OptionalString
 })
 
 export const ORCHESTRATION_GATE_METHODS: RpcMethod[] = [
@@ -103,12 +111,8 @@ export const ORCHESTRATION_GATE_METHODS: RpcMethod[] = [
   defineMethod({
     name: 'orchestration.gateCreate',
     params: GateCreateParams,
-    handler: (params, { runtime, legacyCoordinatorRunId }) => {
+    handler: (params, { orchestrationCompatibilityEvidence, runtime, legacyCoordinatorRunId }) => {
       const db = runtime.getOrchestrationDb()
-      const task = db.getTask(params.task)
-      if (legacyCoordinatorRunId && task?.run_id !== legacyCoordinatorRunId) {
-        throw new Error(`Task not found: ${params.task}`)
-      }
       let options: string[] | undefined
       if (params.options) {
         try {
@@ -121,6 +125,23 @@ export const ORCHESTRATION_GATE_METHODS: RpcMethod[] = [
           throw new Error('Invalid --options: must be a JSON array of strings')
         }
       }
+      const task = db.getTask(params.task)
+      if (!task) {
+        throw new Error(`Task not found: ${params.task}`)
+      }
+      const run = resolveRunScope(runtime, {
+        runId: params.run,
+        callerTerminalHandle: params.from,
+        requireCurrentConsumer: true,
+        legacyCoordinatorRunId,
+        callerEvidence: orchestrationCompatibilityEvidence
+      })
+      if (task.run_id !== run.id) {
+        throw new OrchestrationError(
+          'task_not_found',
+          `Task ${params.task} was not found in Run ${run.id}.`
+        )
+      }
       const gate = db.createGate({
         taskId: params.task,
         question: params.question,
@@ -133,10 +154,21 @@ export const ORCHESTRATION_GATE_METHODS: RpcMethod[] = [
   defineMethod({
     name: 'orchestration.gateResolve',
     params: GateResolveParams,
-    handler: (params, { runtime, legacyCoordinatorRunId }) => {
+    handler: (params, { orchestrationCompatibilityEvidence, runtime, legacyCoordinatorRunId }) => {
       const db = runtime.getOrchestrationDb()
       const existing = db.getGate(params.id)
-      if (legacyCoordinatorRunId && existing?.run_id !== legacyCoordinatorRunId) {
+      if (!existing) {
+        throw new Error(`Gate not found: ${params.id}`)
+      }
+      const run = resolveRunScope(runtime, {
+        runId: params.run,
+        callerTerminalHandle: params.from,
+        requireCurrentConsumer: true,
+        legacyCoordinatorRunId,
+        callerEvidence: orchestrationCompatibilityEvidence
+      })
+      // Why: a gate outside the caller's Run is indistinguishable from a missing one, so probing cannot map foreign Runs.
+      if (existing.run_id !== run.id) {
         throw new Error(`Gate not found: ${params.id}`)
       }
       const gate = db.resolveGate(params.id, params.resolution)
@@ -150,13 +182,27 @@ export const ORCHESTRATION_GATE_METHODS: RpcMethod[] = [
   defineMethod({
     name: 'orchestration.gateList',
     params: GateListParams,
-    handler: (params, { runtime }) => {
+    handler: (params, { orchestrationCompatibilityEvidence, runtime, legacyCoordinatorRunId }) => {
       const db = runtime.getOrchestrationDb()
-      const gates = db.listGates({
-        taskId: params.task,
-        status: params.status as GateStatus
-      })
-      return { gates, count: gates.length }
+      const explicitRun = params.run ? db.getRun(params.run) : undefined
+      // Why: same read posture as taskList — an explicitly named Run is inspectable, an unnamed one means the caller's own.
+      const run =
+        explicitRun?.legacy === 1
+          ? explicitRun
+          : resolveRunScope(runtime, {
+              runId: params.run,
+              callerTerminalHandle: params.from,
+              requireCurrentConsumer: params.run === undefined,
+              legacyCoordinatorRunId,
+              callerEvidence: orchestrationCompatibilityEvidence
+            })
+      const gates = db
+        .listGates({
+          taskId: params.task,
+          status: params.status as GateStatus
+        })
+        .filter((gate) => gate.run_id === run.id)
+      return { runId: run.id, gates, count: gates.length }
     }
   })
 ]
diff --git a/src/main/runtime/rpc/methods/orchestration-run-scope.ts b/src/main/runtime/rpc/methods/orchestration-run-scope.ts
new file mode 100644
index 00000000000..113c135c153
--- /dev/null
+++ b/src/main/runtime/rpc/methods/orchestration-run-scope.ts
@@ -0,0 +1,86 @@
+import type { OrchestrationCompatibilityEvidence } from '../../../../shared/orchestration-compatibility-evidence'
+import { orchestrationSkillRecoveryData } from '../../../../shared/orchestration-rpc-contract'
+import { OrchestrationError } from '../../orchestration/orchestration-error'
+import type { RunRow } from '../../orchestration/types'
+import type { OrcaRuntimeService } from '../../orca-runtime'
+
+export type RunScopeParams = {
+  runId?: string
+  callerTerminalHandle?: string
+  callerPaneKey?: string
+  requireCurrentConsumer: boolean
+  legacyCoordinatorRunId?: string
+  // Why: the caller's declared handle is a user param; this is the attested one to check it against.
+  callerEvidence?: OrchestrationCompatibilityEvidence
+}
+
+// Why: declared handles select mutable Run bindings, so attested callers may only name themselves.
+export function assertCallerHandleMatchesEvidence(
+  runtime: OrcaRuntimeService,
+  callerTerminalHandle: string,
+  callerEvidence?: OrchestrationCompatibilityEvidence
+): void {
+  if (!callerEvidence) {
+    return
+  }
+  const attested = runtime.verifyOrchestrationCompatibilityCaller(callerEvidence)
+  if (attested && attested.terminalHandle !== callerTerminalHandle) {
+    throw new OrchestrationError(
+      'consumer_fenced',
+      `This terminal is attested as ${attested.terminalHandle} and cannot act as ${callerTerminalHandle}.`,
+      { effectsApplied: false }
+    )
+  }
+}
+
+// Why: task and gate mutations must share one Run-binding rule.
+export function resolveRunScope(runtime: OrcaRuntimeService, params: RunScopeParams): RunRow {
+  const db = runtime.getOrchestrationDb()
+  const explicit = params.runId ? db.getRun(params.runId) : undefined
+  if (params.runId && (!explicit || explicit.legacy === 1)) {
+    throw new OrchestrationError('run_not_found', `Run ${params.runId} was not found.`)
+  }
+
+  if (!params.requireCurrentConsumer && explicit) {
+    return explicit
+  }
+  if (!params.callerTerminalHandle) {
+    throw new OrchestrationError(
+      'run_required',
+      'No Run is bound. Use orchestration run-create or run-use first. No effects were applied.',
+      orchestrationSkillRecoveryData()
+    )
+  }
+  assertCallerHandleMatchesEvidence(runtime, params.callerTerminalHandle, params.callerEvidence)
+  if (explicit && params.legacyCoordinatorRunId === explicit.id) {
+    return explicit
+  }
+  const paneKey = params.callerPaneKey ?? runtime.getTerminalPaneKey(params.callerTerminalHandle)
+  if (!paneKey) {
+    throw new OrchestrationError(
+      'stable_pane_required',
+      'The coordinator terminal has no stable pane identity.'
+    )
+  }
+  const current = db.getCurrentRunForPane(paneKey)
+  if (!current) {
+    if (explicit) {
+      throw new OrchestrationError(
+        'consumer_fenced',
+        `This coordinator terminal is no longer bound to Run ${explicit.id}.`
+      )
+    }
+    throw new OrchestrationError(
+      'run_required',
+      'No Run is bound. Use orchestration run-create or run-use first. No effects were applied.',
+      orchestrationSkillRecoveryData()
+    )
+  }
+  if (explicit && current.id !== explicit.id) {
+    throw new OrchestrationError(
+      'consumer_fenced',
+      `This coordinator terminal is bound to ${current.id}, not ${explicit.id}.`
+    )
+  }
+  return current
+}
diff --git a/src/main/runtime/rpc/methods/orchestration-runs.ts b/src/main/runtime/rpc/methods/orchestration-runs.ts
index b246cf80e60..29ec45b3656 100644
--- a/src/main/runtime/rpc/methods/orchestration-runs.ts
+++ b/src/main/runtime/rpc/methods/orchestration-runs.ts
@@ -4,6 +4,7 @@ import { OptionalBoolean, OptionalString, requiredString } from '../schemas'
 import { ORCHESTRATION_RUN_PAGE_LIMIT } from '../../../../shared/orchestration-run-pagination'
 import type { OrcaRuntimeService } from '../../orca-runtime'
 import { OrchestrationError } from '../../orchestration/orchestration-error'
+import { assertCallerHandleMatchesEvidence } from './orchestration-run-scope'
 
 const RunCreateParams = z.object({
   objective: requiredString('Missing --objective'),
@@ -38,7 +39,8 @@ export const ORCHESTRATION_RUN_METHODS: RpcMethod[] = [
   defineMethod({
     name: 'orchestration.runCreate',
     params: RunCreateParams,
-    handler: (params, { runtime }) => {
+    handler: (params, { orchestrationCompatibilityEvidence, runtime }) => {
+      assertCallerHandleMatchesEvidence(runtime, params.from, orchestrationCompatibilityEvidence)
       const paneKey = requireCallerPane(runtime, params.from)
       const db = runtime.getOrchestrationDb()
       const priorRun = db.getCurrentRunForPane(paneKey)
@@ -61,6 +63,7 @@ export const ORCHESTRATION_RUN_METHODS: RpcMethod[] = [
       {
         runtime,
         legacyCoordinatorAuthority,
+        orchestrationCompatibilityEvidence,
         orchestrationCompatibilityCallerAuthority: callerAuthority
       }
     ) => {
@@ -75,6 +78,7 @@ export const ORCHESTRATION_RUN_METHODS: RpcMethod[] = [
           { effectsApplied: false }
         )
       }
+      assertCallerHandleMatchesEvidence(runtime, params.from, orchestrationCompatibilityEvidence)
       const db = runtime.getOrchestrationDb()
       const priorRun = db.getCurrentRunForPane(paneKey)
       const run = db.bindRun({
@@ -100,7 +104,8 @@ export const ORCHESTRATION_RUN_METHODS: RpcMethod[] = [
   defineMethod({
     name: 'orchestration.runCurrent',
     params: RunCurrentParams,
-    handler: (params, { runtime }) => {
+    handler: (params, { orchestrationCompatibilityEvidence, runtime }) => {
+      assertCallerHandleMatchesEvidence(runtime, params.from, orchestrationCompatibilityEvidence)
       const paneKey = requireCallerPane(runtime, params.from)
       return { run: runtime.getOrchestrationDb().getCurrentRunForPane(paneKey) ?? null }
     }
diff --git a/src/main/runtime/rpc/methods/orchestration.test.ts b/src/main/runtime/rpc/methods/orchestration.test.ts
index 51adc620901..cb79b823255 100644
--- a/src/main/runtime/rpc/methods/orchestration.test.ts
+++ b/src/main/runtime/rpc/methods/orchestration.test.ts
@@ -83,6 +83,13 @@ describe('orchestration RPC methods', () => {
       } else if (name === 'orchestration.dispatch') {
         scopedParams.run ??= activeRunId
         scopedParams.from ??= 'term_coord'
+      } else if (
+        name === 'orchestration.gateCreate' ||
+        name === 'orchestration.gateResolve' ||
+        name === 'orchestration.gateList'
+      ) {
+        // Why: gates resolve their Run from the sender's pane binding, so naming the run would skip that check.
+        scopedParams.from ??= 'term_coord'
       }
     }
     const parsed = method.params ? method.params.parse(scopedParams) : undefined
diff --git a/src/main/runtime/rpc/methods/orchestration.ts b/src/main/runtime/rpc/methods/orchestration.ts
index ee6e95e1cf1..4e200e1470f 100644
--- a/src/main/runtime/rpc/methods/orchestration.ts
+++ b/src/main/runtime/rpc/methods/orchestration.ts
@@ -20,6 +20,7 @@ import {
 } from '../../../../shared/orchestration-rpc-contract'
 import { clampOrchestrationAskTimeoutMs } from '../../../../shared/orchestration-ask-timeout'
 import { ORCHESTRATION_GATE_METHODS } from './orchestration-gates'
+import { resolveRunScope } from './orchestration-run-scope'
 import { ORCHESTRATION_RUN_METHODS } from './orchestration-runs'
 import { ORCHESTRATION_WORKER_METHODS } from './orchestration-worker-methods'
 import { ORCHESTRATION_FEDERATION_METHODS } from './orchestration-federation-methods'
@@ -248,65 +249,6 @@ const ResetParams = z
     }
   })
 
-function resolveRunScope(
-  runtime: OrcaRuntimeService,
-  params: {
-    runId?: string
-    callerTerminalHandle?: string
-    callerPaneKey?: string
-    requireCurrentConsumer: boolean
-    legacyCoordinatorRunId?: string
-  }
-): RunRow {
-  const db = runtime.getOrchestrationDb()
-  const explicit = params.runId ? db.getRun(params.runId) : undefined
-  if (params.runId && (!explicit || explicit.legacy === 1)) {
-    throw new OrchestrationError('run_not_found', `Run ${params.runId} was not found.`)
-  }
-
-  if (!params.requireCurrentConsumer && explicit) {
-    return explicit
-  }
-  if (explicit && params.legacyCoordinatorRunId === explicit.id) {
-    return explicit
-  }
-  if (!params.callerTerminalHandle) {
-    throw new OrchestrationError(
-      'run_required',
-      'No Run is bound. Use orchestration run-create or run-use first. No effects were applied.',
-      orchestrationSkillRecoveryData()
-    )
-  }
-  const paneKey = params.callerPaneKey ?? runtime.getTerminalPaneKey(params.callerTerminalHandle)
-  if (!paneKey) {
-    throw new OrchestrationError(
-      'stable_pane_required',
-      'The coordinator terminal has no stable pane identity.'
-    )
-  }
-  const current = db.getCurrentRunForPane(paneKey)
-  if (!current) {
-    if (explicit) {
-      throw new OrchestrationError(
-        'consumer_fenced',
-        `This coordinator terminal is no longer bound to Run ${explicit.id}.`
-      )
-    }
-    throw new OrchestrationError(
-      'run_required',
-      'No Run is bound. Use orchestration run-create or run-use first. No effects were applied.',
-      orchestrationSkillRecoveryData()
-    )
-  }
-  if (explicit && current.id !== explicit.id) {
-    throw new OrchestrationError(
-      'consumer_fenced',
-      `This coordinator terminal is bound to ${current.id}, not ${explicit.id}.`
-    )
-  }
-  return current
-}
-
 function parseMessageTypes(rawTypes: string | undefined): MessageType[] | undefined {
   const types = rawTypes
     ?.split(',')
@@ -722,6 +664,7 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
     handler: async (
       params,
       {
+        orchestrationCompatibilityEvidence,
         runtime,
         signal,
         legacyCoordinatorRunId,
@@ -742,7 +685,8 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
           callerTerminalHandle: handle,
           callerPaneKey: paneKey ?? undefined,
           requireCurrentConsumer: true,
-          legacyCoordinatorRunId
+          legacyCoordinatorRunId,
+          callerEvidence: orchestrationCompatibilityEvidence
         })
         const generation = run.consumer_generation
         const address = `run:${run.id}`
@@ -1026,7 +970,10 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
   defineMethod({
     name: 'orchestration.reply',
     params: ReplyParams,
-    handler: async (params, { runtime, legacyCoordinatorRunId }) => {
+    handler: async (
+      params,
+      { orchestrationCompatibilityEvidence, runtime, legacyCoordinatorRunId }
+    ) => {
       const db = runtime.getOrchestrationDb()
       const original = db.getMessageById(params.id)
       if (!original) {
@@ -1061,7 +1008,8 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
           runId: params.run ?? question.run_id,
           callerTerminalHandle: params.from,
           requireCurrentConsumer: true,
-          legacyCoordinatorRunId
+          legacyCoordinatorRunId,
+          callerEvidence: orchestrationCompatibilityEvidence
         })
         const answered = db.answerQuestion({
           messageId: question.message_id,
@@ -1124,7 +1072,7 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
   defineMethod({
     name: 'orchestration.taskCreate',
     params: TaskCreateParams,
-    handler: (params, { runtime, legacyCoordinatorRunId }) => {
+    handler: (params, { orchestrationCompatibilityEvidence, runtime, legacyCoordinatorRunId }) => {
       const db = runtime.getOrchestrationDb()
       let deps: string[] | undefined
       if (params.deps) {
@@ -1149,7 +1097,8 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
           runId: params.run,
           callerTerminalHandle: params.callerTerminalHandle,
           requireCurrentConsumer: true,
-          legacyCoordinatorRunId
+          legacyCoordinatorRunId,
+          callerEvidence: orchestrationCompatibilityEvidence
         }).id
       })
       return { task }
@@ -1159,7 +1108,7 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
   defineMethod({
     name: 'orchestration.taskList',
     params: TaskListParams,
-    handler: (params, { runtime, legacyCoordinatorRunId }) => {
+    handler: (params, { orchestrationCompatibilityEvidence, runtime, legacyCoordinatorRunId }) => {
       const db = runtime.getOrchestrationDb()
       const explicitRun = params.run ? db.getRun(params.run) : undefined
       const run =
@@ -1169,7 +1118,8 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
               runId: params.run,
               callerTerminalHandle: params.callerTerminalHandle,
               requireCurrentConsumer: params.run === undefined,
-              legacyCoordinatorRunId
+              legacyCoordinatorRunId,
+              callerEvidence: orchestrationCompatibilityEvidence
             })
       // Why: listTasksWithDispatch adds assignee_handle + dispatch_id (NULL for non-dispatched), so legacy-shape consumers are unaffected.
       const joined = db.listTasksWithDispatch({
@@ -1196,13 +1146,14 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
   defineMethod({
     name: 'orchestration.taskUpdate',
     params: TaskUpdateParams,
-    handler: (params, { runtime, legacyCoordinatorRunId }) => {
+    handler: (params, { orchestrationCompatibilityEvidence, runtime, legacyCoordinatorRunId }) => {
       const db = runtime.getOrchestrationDb()
       const run = resolveRunScope(runtime, {
         runId: params.run,
         callerTerminalHandle: params.callerTerminalHandle,
         requireCurrentConsumer: true,
-        legacyCoordinatorRunId
+        legacyCoordinatorRunId,
+        callerEvidence: orchestrationCompatibilityEvidence
       })
       const existing = db.getTask(params.id)
       if (!existing || existing.run_id !== run.id) {
@@ -1222,7 +1173,15 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
   defineMethod({
     name: 'orchestration.dispatch',
     params: DispatchParams,
-    handler: async (params, { runtime, legacyCoordinatorRunId, revalidateLegacyCoordinator }) => {
+    handler: async (
+      params,
+      {
+        orchestrationCompatibilityEvidence,
+        runtime,
+        legacyCoordinatorRunId,
+        revalidateLegacyCoordinator
+      }
+    ) => {
       const db = runtime.getOrchestrationDb()
       const task = db.getTask(params.task)
       if (!task) {
@@ -1232,7 +1191,8 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
         runId: params.run,
         callerTerminalHandle: params.from,
         requireCurrentConsumer: true,
-        legacyCoordinatorRunId
+        legacyCoordinatorRunId,
+        callerEvidence: orchestrationCompatibilityEvidence
       })
       if (task.run_id !== run.id) {
         throw new OrchestrationError(
diff --git a/src/main/runtime/rpc/orchestration-11745-regression-verification.test.ts b/src/main/runtime/rpc/orchestration-11745-regression-verification.test.ts
new file mode 100644
index 00000000000..73f201a91a2
--- /dev/null
+++ b/src/main/runtime/rpc/orchestration-11745-regression-verification.test.ts
@@ -0,0 +1,820 @@
+// Why: independent adversarial verification of every #11745 fix. Each case reproduces the ORIGINAL
+// defect and asserts it is closed by observing state, not just the response envelope — a refusal
+// that still mutated the graph is a failure, and so is a fix that fences a legitimate coordinator.
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import type { OrchestrationCompatibilityEvidence } from '../../../shared/orchestration-compatibility-evidence'
+import SyncDatabase from '../../sqlite/sync-database'
+import { OrchestrationDb } from '../orchestration/db'
+import {
+  cleanupLegacyCompatibilityDispatcherHarnesses,
+  COORDINATOR_HANDLE,
+  counts,
+  createHarness,
+  currentEvidence,
+  CURRENT_COORDINATOR_HANDLE,
+  CURRENT_COORDINATOR_PANE,
+  CURRENT_WORKER_HANDLE,
+  CURRENT_WORKER_PANE,
+  evidence,
+  invoke,
+  request,
+  type LegacyCompatibilityDispatcherHarness
+} from './orchestration-legacy-compatibility-dispatcher-test-fixture'
+
+// Why: an unrelated caller the runtime CAN resolve to a pane — otherwise the refusal would be
+// stable_pane_required and would prove nothing about Run authorization.
+const OUTSIDER_HANDLE = CURRENT_WORKER_HANDLE
+const OUTSIDER_PANE = CURRENT_WORKER_PANE
+
+const tempDirs: string[] = []
+const databases: OrchestrationDb[] = []
+
+afterEach(() => {
+  cleanupLegacyCompatibilityDispatcherHarnesses()
+  for (const database of databases.splice(0)) {
+    database.close()
+  }
+  for (const dir of tempDirs.splice(0)) {
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+function unattested(proof: OrchestrationCompatibilityEvidence): OrchestrationCompatibilityEvidence {
+  return { ...proof, launchToken: '' }
+}
+
+/** Every observable the adopted Run's recovered graph exposes; a refusal must leave all of it equal. */
+function adoptedGraph(harness: LegacyCompatibilityDispatcherHarness) {
+  return {
+    task: harness.db.getTask(harness.taskId)?.status,
+    dispatch: harness.db.getDispatchContextById(harness.dispatchId)?.status,
+    gates: harness.db.listGates({ taskId: harness.taskId }).length,
+    tasksInRun: harness.db.listTasks({ runId: harness.adoptedRunId }).length,
+    run: harness.db.getRun(harness.adoptedRunId)?.coordinator_handle ?? null,
+    tables: counts(harness.db)
+  }
+}
+
+function bindRunA(harness: LegacyCompatibilityDispatcherHarness): string {
+  return harness.db.createRun({
+    objective: 'run A work',
+    coordinatorHandle: CURRENT_COORDINATOR_HANDLE,
+    coordinatorPaneKey: CURRENT_COORDINATOR_PANE
+  }).id
+}
+
+async function legacyClaimsAdoptedRun(
+  harness: LegacyCompatibilityDispatcherHarness,
+  id: string
+): Promise<void> {
+  const response = await harness.dispatcher.dispatch(
+    request(
+      'orchestration.runUse',
+      { id: harness.adoptedRunId, from: COORDINATOR_HANDLE },
+      evidence('coordinator'),
+      `${id}-legacy-claim`
+    )
+  )
+  expect(response).toMatchObject({ ok: true })
+}
+
+async function currentCoordinatorTakesOver(
+  harness: LegacyCompatibilityDispatcherHarness,
+  id: string
+): Promise<void> {
+  const response = await harness.dispatcher.dispatch(
+    request(
+      'orchestration.runUse',
+      { id: harness.adoptedRunId, from: CURRENT_COORDINATOR_HANDLE, takeoverLegacy: true },
+      currentEvidence('coordinator'),
+      `${id}-takeover`
+    )
+  )
+  expect(response).toMatchObject({ ok: true })
+}
+
+describe('#11745 H1 — gate methods authorize the caller Run', () => {
+  it.each(['dispatch', 'websocket'] as const)(
+    'G1 %s leaves the recovered task and its dispatch untouched for an unbound attested caller',
+    async (transport) => {
+      const harness = createHarness()
+      const before = adoptedGraph(harness)
+
+      const response = await invoke(
+        harness.dispatcher,
+        request(
+          'orchestration.gateCreate',
+          { task: harness.taskId, question: 'Proceed?' },
+          currentEvidence('coordinator'),
+          `v-g1-${transport}`
+        ),
+        transport
+      )
+
+      expect(response).toMatchObject({ ok: false, error: { code: 'run_required' } })
+      expect(adoptedGraph(harness)).toEqual(before)
+      // The recovered graph really is live work, so "unchanged" is a meaningful assertion.
+      expect(before.task).toBe('dispatched')
+      expect(before.gates).toBe(0)
+    }
+  )
+
+  it('G2 leaves the adopted Run untouched for an unattested caller bound to Run A', async () => {
+    const harness = createHarness()
+    bindRunA(harness)
+    const before = adoptedGraph(harness)
+
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.gateCreate',
+        { task: harness.taskId, question: 'Proceed?', from: CURRENT_COORDINATOR_HANDLE },
+        unattested(currentEvidence('coordinator')),
+        'v-g2'
+      )
+    )
+
+    expect(response).toMatchObject({ ok: false, error: { code: 'task_not_found' } })
+    expect(adoptedGraph(harness)).toEqual(before)
+  })
+
+  it('G3 leaves the adopted Run untouched once the legacy coordinator has claimed it', async () => {
+    const harness = createHarness()
+    await legacyClaimsAdoptedRun(harness, 'v-g3')
+    bindRunA(harness)
+    const before = adoptedGraph(harness)
+
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.gateCreate',
+        { task: harness.taskId, question: 'Proceed?', from: CURRENT_COORDINATOR_HANDLE },
+        unattested(currentEvidence('coordinator')),
+        'v-g3-gate'
+      )
+    )
+
+    expect(response).toMatchObject({ ok: false })
+    expect(adoptedGraph(harness)).toEqual(before)
+  })
+
+  it('G5 leaves a foreign gate pending and its task blocked', async () => {
+    const harness = createHarness()
+    bindRunA(harness)
+    const gate = harness.db.createGate({ taskId: harness.taskId, question: 'Proceed?' })
+    const before = adoptedGraph(harness)
+
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.gateResolve',
+        { id: gate.id, resolution: 'yes', from: CURRENT_COORDINATOR_HANDLE },
+        unattested(currentEvidence('coordinator')),
+        'v-g5'
+      )
+    )
+
+    expect(response).toMatchObject({ ok: false, error: { message: `Gate not found: ${gate.id}` } })
+    expect(harness.db.getGate(gate.id)).toMatchObject({ status: 'pending', resolution: null })
+    expect(adoptedGraph(harness)).toEqual(before)
+    expect(before.task).toBe('blocked')
+  })
+
+  it('G4 refuses a stranger Run with NO legacy adoption in play', () => {
+    // Why: G4 must hold on a plain runtime, so the fix cannot be an artifact of adoption state.
+    const dir = mkdtempSync(join(tmpdir(), 'orca-11745-g4-'))
+    tempDirs.push(dir)
+    const db = new OrchestrationDb(join(dir, 'orchestration.db'))
+    databases.push(db)
+    expect(db.getLegacyAdoption()).toBeUndefined()
+
+    const runA = db.createRun({
+      objective: 'run A',
+      coordinatorHandle: CURRENT_COORDINATOR_HANDLE,
+      coordinatorPaneKey: CURRENT_COORDINATOR_PANE
+    })
+    const runC = db.createRun({
+      objective: 'run C',
+      coordinatorHandle: OUTSIDER_HANDLE,
+      coordinatorPaneKey: OUTSIDER_PANE
+    })
+    const strangerTask = db.createTask({ spec: 'stranger work', runId: runC.id })
+
+    // The Run-scope decision the gate handler makes: A's pane resolves to A, never to C.
+    expect(db.getCurrentRunForPane(CURRENT_COORDINATOR_PANE)?.id).toBe(runA.id)
+    expect(strangerTask.run_id).toBe(runC.id)
+    expect(db.listGates({ taskId: strangerTask.id })).toHaveLength(0)
+    expect(db.getTask(strangerTask.id)?.status).toBe('ready')
+  })
+
+  it('POSITIVE: a legitimately bound coordinator still gates its own Run end to end', async () => {
+    const harness = createHarness()
+    const runA = bindRunA(harness)
+    const ownTask = harness.db.createTask({ spec: 'own work', runId: runA })
+
+    const created = (await harness.dispatcher.dispatch(
+      request(
+        'orchestration.gateCreate',
+        {
+          task: ownTask.id,
+          question: 'Ship?',
+          options: JSON.stringify(['yes', 'no']),
+          from: CURRENT_COORDINATOR_HANDLE
+        },
+        currentEvidence('coordinator'),
+        'v-positive-create'
+      )
+    )) as { ok: true; result: { gate: { id: string; run_id: string } } }
+
+    expect(created).toMatchObject({ ok: true, result: { gate: { run_id: runA } } })
+    expect(harness.db.getTask(ownTask.id)?.status).toBe('blocked')
+
+    const listed = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.gateList',
+        { from: CURRENT_COORDINATOR_HANDLE },
+        currentEvidence('coordinator'),
+        'v-positive-list'
+      )
+    )
+    expect(listed).toMatchObject({ ok: true, result: { runId: runA, count: 1 } })
+
+    const resolved = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.gateResolve',
+        { id: created.result.gate.id, resolution: 'yes', from: CURRENT_COORDINATOR_HANDLE },
+        currentEvidence('coordinator'),
+        'v-positive-resolve'
+      )
+    )
+    expect(resolved).toMatchObject({ ok: true, result: { gate: { status: 'resolved' } } })
+    expect(harness.db.getTask(ownTask.id)?.status).toBe('ready')
+  })
+
+  it('POSITIVE: the proven legacy coordinator still gates the adopted Run task', async () => {
+    const harness = createHarness()
+
+    const created = (await harness.dispatcher.dispatch(
+      request(
+        'orchestration.gateCreate',
+        { task: harness.taskId, question: 'Proceed?', from: COORDINATOR_HANDLE },
+        evidence('coordinator'),
+        'v-legacy-create'
+      )
+    )) as { ok: true; result: { gate: { id: string; run_id: string } } }
+
+    expect(created).toMatchObject({
+      ok: true,
+      result: { gate: { run_id: harness.adoptedRunId, task_id: harness.taskId } }
+    })
+    expect(harness.db.getTask(harness.taskId)?.status).toBe('blocked')
+
+    const resolved = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.gateResolve',
+        { id: created.result.gate.id, resolution: 'go', from: COORDINATOR_HANDLE },
+        evidence('coordinator'),
+        'v-legacy-resolve'
+      )
+    )
+    expect(resolved).toMatchObject({ ok: true, result: { gate: { status: 'resolved' } } })
+    expect(harness.db.getTask(harness.taskId)?.status).toBe('ready')
+  })
+})
+
+describe('#11745 H1 — is --from an authenticated identity?', () => {
+  // Why: Run scoping authorizes on a declared handle, so an attested caller naming someone else's
+  // handle must be refused. Both cases run through the shared resolveRunScope, so they also pin
+  // that the gate path and the older task path cannot diverge again.
+  it('refuses an attested caller naming ANOTHER coordinator handle in --from', async () => {
+    const harness = createHarness()
+    const runA = bindRunA(harness)
+    const victimTask = harness.db.createTask({ spec: 'victim work', runId: runA })
+
+    // Caller is the current WORKER — attested as itself, bound to no Run — but names the
+    // coordinator's handle. Nothing on this request proves it may speak for that handle.
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.gateCreate',
+        { task: victimTask.id, question: 'spoofed?', from: CURRENT_COORDINATOR_HANDLE },
+        currentEvidence('worker'),
+        'v-spoof-gate-create'
+      )
+    )
+
+    expect(response).toMatchObject({ ok: false, error: { code: 'consumer_fenced' } })
+    expect(harness.db.getTask(victimTask.id)?.status).not.toBe('blocked')
+    expect(harness.db.listGates({ taskId: victimTask.id })).toHaveLength(0)
+  })
+
+  it('refuses the same spoof against taskCreate, which predates this change', async () => {
+    const harness = createHarness()
+    const runA = bindRunA(harness)
+
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.taskCreate',
+        { spec: 'spoofed assignment', callerTerminalHandle: CURRENT_COORDINATOR_HANDLE },
+        currentEvidence('worker'),
+        'v-spoof-task-create'
+      )
+    )
+
+    // Why: the weakness was inherited from this older path, so the fix has to cover it too.
+    expect(response).toMatchObject({ ok: false, error: { code: 'consumer_fenced' } })
+    expect(harness.db.listTasks({ runId: runA })).toHaveLength(0)
+  })
+
+  it('refuses an attested caller creating a Run for another terminal', async () => {
+    const harness = createHarness()
+    const runA = bindRunA(harness)
+    const before = harness.db.listRuns().runs
+
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.runCreate',
+        { objective: 'spoofed Run', from: CURRENT_COORDINATOR_HANDLE },
+        currentEvidence('worker'),
+        'v-spoof-run-create'
+      )
+    )
+
+    expect(response).toMatchObject({ ok: false, error: { code: 'consumer_fenced' } })
+    expect(harness.db.listRuns().runs).toEqual(before)
+    expect(harness.db.getCurrentRunForPane(CURRENT_COORDINATOR_PANE)?.id).toBe(runA)
+  })
+
+  it('refuses an attested caller rebinding another terminal with runUse', async () => {
+    const harness = createHarness()
+    const runA = bindRunA(harness)
+    const workerRun = harness.db.createRun({
+      objective: 'worker Run',
+      coordinatorHandle: CURRENT_WORKER_HANDLE,
+      coordinatorPaneKey: CURRENT_WORKER_PANE
+    })
+    const beforeA = harness.db.getRun(runA)
+    const beforeWorker = harness.db.getRun(workerRun.id)
+
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.runUse',
+        { id: workerRun.id, from: CURRENT_COORDINATOR_HANDLE },
+        currentEvidence('worker'),
+        'v-spoof-run-use'
+      )
+    )
+
+    expect(response).toMatchObject({ ok: false, error: { code: 'consumer_fenced' } })
+    expect(harness.db.getRun(runA)).toEqual(beforeA)
+    expect(harness.db.getRun(workerRun.id)).toEqual(beforeWorker)
+  })
+
+  it('refuses an attested caller querying another terminal with runCurrent', async () => {
+    const harness = createHarness()
+    bindRunA(harness)
+
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.runCurrent',
+        { from: CURRENT_COORDINATOR_HANDLE },
+        currentEvidence('worker'),
+        'v-spoof-run-current'
+      )
+    )
+
+    expect(response).toMatchObject({ ok: false, error: { code: 'consumer_fenced' } })
+  })
+
+  it('does not let legacy authority bypass a mismatched declared handle', async () => {
+    const harness = createHarness()
+    const before = adoptedGraph(harness)
+
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.taskCreate',
+        {
+          spec: 'spoofed legacy assignment',
+          callerTerminalHandle: CURRENT_COORDINATOR_HANDLE
+        },
+        evidence('coordinator'),
+        'v-spoof-legacy-shortcut'
+      )
+    )
+
+    expect(response).toMatchObject({ ok: false, error: { code: 'consumer_fenced' } })
+    expect(adoptedGraph(harness)).toEqual(before)
+  })
+})
+
+describe('#11745 H1 — gateList read posture', () => {
+  it('DOCUMENTS: naming a Run makes its gates readable with no caller identity at all', async () => {
+    // Why: gateList mirrors taskList (requireCurrentConsumer: params.run === undefined), so an
+    // explicitly named Run is inspectable by anyone. Reads only — gateCreate/gateResolve always
+    // require the binding. Pinned here so any future narrowing is a deliberate decision.
+    const harness = createHarness()
+    const runA = bindRunA(harness)
+    const ownTask = harness.db.createTask({ spec: 'own work', runId: runA })
+    const ownGate = harness.db.createGate({ taskId: ownTask.id, question: 'Own?' })
+
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.gateList',
+        { run: runA },
+        currentEvidence('worker'),
+        'v-gate-list-named-run'
+      )
+    )
+
+    expect(response).toMatchObject({
+      ok: true,
+      result: { runId: runA, count: 1, gates: [{ id: ownGate.id }] }
+    })
+  })
+})
+
+describe('#11745 H2 — revoked principal on an unclaimed adopted Run', () => {
+  it('answers an unbound caller with run_required, not legacy_read_only', async () => {
+    const harness = createHarness()
+    await legacyClaimsAdoptedRun(harness, 'v-h2')
+    await currentCoordinatorTakesOver(harness, 'v-h2')
+    // The new owner's pane rebinds elsewhere, leaving the adopted Run unclaimed + principal revoked.
+    harness.db.createRun({
+      objective: 'elsewhere',
+      coordinatorHandle: CURRENT_COORDINATOR_HANDLE,
+      coordinatorPaneKey: CURRENT_COORDINATOR_PANE
+    })
+    expect(harness.db.getRun(harness.adoptedRunId)?.coordinator_pane_key).toBeNull()
+    expect(harness.db.getLegacyCoordinatorPrincipal(harness.adoptedRunId)?.status).toBe('revoked')
+    const before = adoptedGraph(harness)
+
+    const response = (await harness.dispatcher.dispatch(
+      request(
+        'orchestration.taskCreate',
+        { spec: 'unbound assignment', callerTerminalHandle: OUTSIDER_HANDLE },
+        currentEvidence('worker'),
+        'v-h2-unbound'
+      )
+    )) as { ok: false; error: { code: string } }
+
+    expect(response.ok).toBe(false)
+    expect(response.error.code).not.toBe('legacy_read_only')
+    expect(response.error.code).toBe('run_required')
+    expect(adoptedGraph(harness)).toEqual(before)
+  })
+
+  it('gives the SAME honest code through the gate path', async () => {
+    const harness = createHarness()
+    await legacyClaimsAdoptedRun(harness, 'v-h2b')
+    await currentCoordinatorTakesOver(harness, 'v-h2b')
+    harness.db.createRun({
+      objective: 'elsewhere',
+      coordinatorHandle: CURRENT_COORDINATOR_HANDLE,
+      coordinatorPaneKey: CURRENT_COORDINATOR_PANE
+    })
+    const before = adoptedGraph(harness)
+
+    const response = (await harness.dispatcher.dispatch(
+      request(
+        'orchestration.gateCreate',
+        { task: harness.taskId, question: 'Proceed?', from: OUTSIDER_HANDLE },
+        currentEvidence('worker'),
+        'v-h2b-gate'
+      )
+    )) as { ok: false; error: { code: string } }
+
+    expect(response.ok).toBe(false)
+    expect(response.error.code).not.toBe('legacy_read_only')
+    expect(adoptedGraph(harness)).toEqual(before)
+  })
+})
+
+describe('#11745 H3 — adopted Run claimed by the legacy coordinator', () => {
+  it('answers an unrelated unbound caller with run_required, not legacy_read_only', async () => {
+    const harness = createHarness()
+    await legacyClaimsAdoptedRun(harness, 'v-h3')
+    expect(harness.db.getLegacyCoordinatorPrincipal(harness.adoptedRunId)?.status).toBe('committed')
+    const before = adoptedGraph(harness)
+
+    const response = (await harness.dispatcher.dispatch(
+      request(
+        'orchestration.taskCreate',
+        { spec: 'fresh assignment', callerTerminalHandle: OUTSIDER_HANDLE },
+        currentEvidence('worker'),
+        'v-h3-unbound'
+      )
+    )) as { ok: false; error: { code: string } }
+
+    expect(response.ok).toBe(false)
+    expect(response.error.code).not.toBe('legacy_read_only')
+    expect(response.error.code).toBe('run_required')
+    expect(adoptedGraph(harness)).toEqual(before)
+  })
+
+  it('still fences the genuinely stale legacy coordinator with legacy_read_only and zero effects', async () => {
+    const harness = createHarness()
+    await legacyClaimsAdoptedRun(harness, 'v-h3b')
+    await currentCoordinatorTakesOver(harness, 'v-h3b')
+    const before = adoptedGraph(harness)
+
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.taskCreate',
+        {
+          spec: 'stale assignment',
+          run: harness.adoptedRunId,
+          callerTerminalHandle: COORDINATOR_HANDLE
+        },
+        evidence('coordinator'),
+        'v-h3b-stale'
+      )
+    )
+
+    expect(response).toMatchObject({
+      ok: false,
+      error: { code: 'legacy_read_only', data: { effectsApplied: false } }
+    })
+    expect(adoptedGraph(harness)).toEqual(before)
+  })
+
+  it('fences the stale legacy coordinator on the gate path too', async () => {
+    const harness = createHarness()
+    await legacyClaimsAdoptedRun(harness, 'v-h3c')
+    await currentCoordinatorTakesOver(harness, 'v-h3c')
+    const before = adoptedGraph(harness)
+
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.gateCreate',
+        { task: harness.taskId, question: 'Proceed?', from: COORDINATOR_HANDLE },
+        evidence('coordinator'),
+        'v-h3c-gate'
+      )
+    )
+
+    expect(response).toMatchObject({ ok: false })
+    expect(adoptedGraph(harness)).toEqual(before)
+  })
+})
+
+describe('#11745 H4 — unattested caller on a taken-over adopted Run', () => {
+  it('DOCUMENTS the accepted behaviour: the binding alone grants authority', async () => {
+    const harness = createHarness()
+    await legacyClaimsAdoptedRun(harness, 'v-h4')
+    await currentCoordinatorTakesOver(harness, 'v-h4')
+
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.taskCreate',
+        {
+          spec: 'owner assignment',
+          run: harness.adoptedRunId,
+          callerTerminalHandle: CURRENT_COORDINATOR_HANDLE
+        },
+        unattested(currentEvidence('coordinator')),
+        'v-h4-owner'
+      )
+    )
+
+    expect(response).toMatchObject({
+      ok: true,
+      result: { task: { run_id: harness.adoptedRunId } }
+    })
+  })
+
+  it('refuses the same authority WITHOUT matching the run binding in evidence', async () => {
+    const harness = createHarness()
+    await legacyClaimsAdoptedRun(harness, 'v-h4b')
+    await currentCoordinatorTakesOver(harness, 'v-h4b')
+
+    // Why: evidence names a different terminal, so this is an impostor rather than the owner
+    // ownsRunBinding is meant to admit. The attested handle must win over the declared one.
+    const before = adoptedGraph(harness)
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.taskCreate',
+        {
+          spec: 'impostor assignment',
+          run: harness.adoptedRunId,
+          callerTerminalHandle: CURRENT_COORDINATOR_HANDLE
+        },
+        currentEvidence('worker'),
+        'v-h4b-impostor'
+      )
+    )
+
+    expect(response).toMatchObject({ ok: false, error: { code: 'consumer_fenced' } })
+    expect(adoptedGraph(harness)).toEqual(before)
+  })
+
+  it('an unattested caller that is NOT the owner is still refused', async () => {
+    const harness = createHarness()
+    await legacyClaimsAdoptedRun(harness, 'v-h4c')
+    await currentCoordinatorTakesOver(harness, 'v-h4c')
+    const before = adoptedGraph(harness)
+
+    const response = (await harness.dispatcher.dispatch(
+      request(
+        'orchestration.taskCreate',
+        {
+          spec: 'outsider assignment',
+          run: harness.adoptedRunId,
+          callerTerminalHandle: OUTSIDER_HANDLE
+        },
+        unattested(currentEvidence('worker')),
+        'v-h4c-outsider'
+      )
+    )) as { ok: false; error: { code: string } }
+
+    expect(response.ok).toBe(false)
+    expect(adoptedGraph(harness)).toEqual(before)
+  })
+})
+
+/** Builds a pre-cutover graph at schema 18 and reopens it so adoption runs. */
+function createAdoptedDb(options: { settleWork: boolean }): {
+  db: OrchestrationDb
+  adoptedRunId: string
+  recoveryMessageId: string
+} {
+  const dir = mkdtempSync(join(tmpdir(), 'orca-11745-m5-'))
+  tempDirs.push(dir)
+  const dbPath = join(dir, 'orchestration.db')
+
+  const before = new OrchestrationDb(dbPath)
+  const task = before.createTask({ spec: 'legacy assignment', createdByTerminalHandle: 'term_old' })
+  before.createDispatchContext(
+    task.id,
+    'term_old_worker',
+    'tab_old:33333333-3333-4333-8333-333333333333'
+  )
+  const recovery = before.insertMessage({
+    from: 'term_old_worker',
+    to: 'term_old',
+    subject: 'recovered worker outcome',
+    type: 'worker_done'
+  })
+  before.close()
+
+  const raw = new SyncDatabase(dbPath)
+  if (options.settleWork) {
+    raw.exec("UPDATE dispatch_contexts SET status = 'completed'")
+  }
+  raw.exec(`
+    DROP INDEX IF EXISTS idx_messages_delivery_contract;
+    DROP TABLE legacy_mail_receipts;
+    DROP TABLE legacy_operation_receipts;
+    DROP TABLE legacy_compatibility_principals;
+    DROP TABLE legacy_adoptions;
+  `)
+  raw.pragma('user_version = 18')
+  raw.close()
+
+  const db = new OrchestrationDb(dbPath)
+  databases.push(db)
+  return {
+    db,
+    adoptedRunId: db.getLegacyAdoption()?.adopted_run_id as string,
+    recoveryMessageId: recovery.id
+  }
+}
+
+describe('#11745 M5 — binding an unclaimed adopted Run', () => {
+  it('binds without --takeover-legacy when no legacy work is live, and keeps legacy mail promoted', () => {
+    const { db, adoptedRunId, recoveryMessageId } = createAdoptedDb({ settleWork: true })
+    expect(db.getMessageById(recoveryMessageId)?.run_id).toBe(adoptedRunId)
+
+    const run = db.bindRun({
+      runId: adoptedRunId,
+      coordinatorHandle: CURRENT_COORDINATOR_HANDLE,
+      coordinatorPaneKey: CURRENT_COORDINATOR_PANE
+    })
+
+    expect(run?.id).toBe(adoptedRunId)
+    expect(db.getRun(adoptedRunId)).toMatchObject({
+      coordinator_handle: CURRENT_COORDINATOR_HANDLE
+    })
+    // The recovered mail must still belong to the adopted Run, not be orphaned by the bind.
+    expect(db.getMessageById(recoveryMessageId)?.run_id).toBe(adoptedRunId)
+    expect(db.getCurrentRunForPane(CURRENT_COORDINATOR_PANE)?.id).toBe(adoptedRunId)
+  })
+
+  it('still fences the bind while legacy work IS live, with a usable recovery command', () => {
+    const { db, adoptedRunId, recoveryMessageId } = createAdoptedDb({ settleWork: false })
+
+    expect(() =>
+      db.bindRun({
+        runId: adoptedRunId,
+        coordinatorHandle: CURRENT_COORDINATOR_HANDLE,
+        coordinatorPaneKey: CURRENT_COORDINATOR_PANE
+      })
+    ).toThrowError(
+      expect.objectContaining({
+        code: 'consumer_fenced',
+        data: {
+          effectsApplied: false,
+          recoveryCommand: `orca orchestration run-use --id ${adoptedRunId} --takeover-legacy`
+        }
+      })
+    )
+    expect(db.getRun(adoptedRunId)?.coordinator_handle).toBeNull()
+    expect(db.getMessageById(recoveryMessageId)?.run_id).toBe(adoptedRunId)
+  })
+})
+
+describe('#11745 L6 — indexed getCurrentRunForPane keeps pane equivalence', () => {
+  function paneDb(): OrchestrationDb {
+    const dir = mkdtempSync(join(tmpdir(), 'orca-11745-l6-'))
+    tempDirs.push(dir)
+    const db = new OrchestrationDb(join(dir, 'orchestration.db'))
+    databases.push(db)
+    return db
+  }
+
+  function leaf(index: number): string {
+    const hex = index.toString(16).padStart(12, '0')
+    return `${hex.slice(0, 8)}-0000-4000-8000-${hex}`
+  }
+
+  it('resolves a reminted tab half by leaf UUID', () => {
+    const db = paneDb()
+    const run = db.createRun({
+      objective: 'reminted',
+      coordinatorHandle: CURRENT_COORDINATOR_HANDLE,
+      coordinatorPaneKey: `tab_before:${leaf(1)}`
+    })
+
+    // Break-out remints the tab half; the leaf UUID is the durable identity.
+    expect(db.getCurrentRunForPane(`tab_after:${leaf(1)}`)?.id).toBe(run.id)
+    expect(db.getCurrentRunForPane(`tab_before:${leaf(1)}`)?.id).toBe(run.id)
+    expect(db.getCurrentRunForPane(`tab_after:${leaf(2)}`)).toBeUndefined()
+  })
+
+  it('keeps unparseable pane keys on exact-match semantics', () => {
+    const db = paneDb()
+    const noColon = db.createRun({
+      objective: 'no colon',
+      coordinatorHandle: 'term_a',
+      coordinatorPaneKey: 'nocolonpanekey'
+    })
+    const twoColons = db.createRun({
+      objective: 'two colons',
+      coordinatorHandle: 'term_b',
+      coordinatorPaneKey: `win:tab:${leaf(3)}`
+    })
+    const emptyLeaf = db.createRun({
+      objective: 'empty leaf',
+      coordinatorHandle: 'term_c',
+      coordinatorPaneKey: 'tab_empty:'
+    })
+
+    expect(db.getCurrentRunForPane('nocolonpanekey')?.id).toBe(noColon.id)
+    expect(db.getCurrentRunForPane(`win:tab:${leaf(3)}`)?.id).toBe(twoColons.id)
+    expect(db.getCurrentRunForPane('tab_empty:')?.id).toBe(emptyLeaf.id)
+
+    // A different first segment on an unparseable key must NOT match, even though the
+    // indexed suffix is identical — the suffix only narrows, isEquivalentPaneKey decides.
+    expect(db.getCurrentRunForPane(`other:tab:${leaf(3)}`)).toBeUndefined()
+    expect(db.getCurrentRunForPane('other_empty:')).toBeUndefined()
+    // A parseable key must not be satisfied by an unparseable row sharing its suffix.
+    expect(db.getCurrentRunForPane(`tab:${leaf(3)}`)).toBeUndefined()
+  })
+
+  it('unbinds the equivalent pane when a reminted key binds a new Run', () => {
+    const db = paneDb()
+    const first = db.createRun({
+      objective: 'first',
+      coordinatorHandle: 'term_a',
+      coordinatorPaneKey: `tab_one:${leaf(4)}`
+    })
+    const second = db.createRun({
+      objective: 'second',
+      coordinatorHandle: 'term_a',
+      coordinatorPaneKey: `tab_two:${leaf(4)}`
+    })
+
+    expect(db.getRun(first.id)?.coordinator_pane_key).toBeNull()
+    expect(db.getCurrentRunForPane(`tab_three:${leaf(4)}`)?.id).toBe(second.id)
+  })
+
+  it.each([60, 2000])('stays correct and fast at %i bound Runs', (total) => {
+    const db = paneDb()
+    for (let index = 0; index < total; index += 1) {
+      db.createRun({
+        objective: `run ${index}`,
+        coordinatorHandle: `term_${index}`,
+        coordinatorPaneKey: `tab_${index}:${leaf(index + 100)}`
+      })
+    }
+
+    const target = `tab_reminted:${leaf(total + 99)}`
+    const started = performance.now()
+    for (let probe = 0; probe < 200; probe += 1) {
+      expect(db.getCurrentRunForPane(target)).toBeDefined()
+    }
+    const elapsed = performance.now() - started
+
+    // Generous ceiling: the pre-fix full-table scan at 2000 Runs was orders of magnitude slower.
+    expect(elapsed).toBeLessThan(4000)
+    expect(db.getCurrentRunForPane(`tab_missing:${leaf(999999)}`)).toBeUndefined()
+  })
+})
diff --git a/src/main/runtime/rpc/orchestration-legacy-coordinator-authority.ts b/src/main/runtime/rpc/orchestration-legacy-coordinator-authority.ts
index 782460c891b..1791841307b 100644
--- a/src/main/runtime/rpc/orchestration-legacy-coordinator-authority.ts
+++ b/src/main/runtime/rpc/orchestration-legacy-coordinator-authority.ts
@@ -35,29 +35,30 @@ export class LegacyCoordinatorAuthority {
       paneKey: request.orchestrationCompatibilityEvidence?.paneKey
     })
     if (!candidate) {
-      if (request.orchestrationCompatibilityEvidence) {
-        const run = db.getRun(adoption.adopted_run_id)
-        // Why: an unclaimed adopted Run has no coordinator to fence — same rule as bindingMatches below.
-        if (
-          !run?.coordinator_pane_key &&
-          !db.getLegacyCoordinatorPrincipal(adoption.adopted_run_id)
-        ) {
-          return undefined
-        }
-        const caller = this.runtime.verifyOrchestrationCompatibilityCaller(
-          request.orchestrationCompatibilityEvidence
-        )
-        if (
-          caller &&
-          run?.coordinator_handle === caller.terminalHandle &&
-          run.coordinator_pane_key &&
-          equivalentLegacyPaneKey(run.coordinator_pane_key, caller.paneKey)
-        ) {
-          return undefined
-        }
-        throw legacyCoordinatorReadOnly()
+      const evidence = request.orchestrationCompatibilityEvidence
+      if (!evidence) {
+        return undefined
       }
-      return undefined
+      const run = db.getRun(adoption.adopted_run_id)
+      const principal = db.getLegacyCoordinatorPrincipal(adoption.adopted_run_id)
+      // Why: an unclaimed adopted Run has no coordinator to fence, and a revoked principal is exactly that.
+      if (!run?.coordinator_pane_key && principal?.status !== 'committed') {
+        return undefined
+      }
+      const caller = this.runtime.verifyOrchestrationCompatibilityCaller(evidence)
+      // Why: the binding is trusted DB state, so the owner keeps its Run on hosts where attestation is unavailable.
+      if (run && (ownsRunBinding(run, caller) || ownsRunBinding(run, evidence))) {
+        return undefined
+      }
+      // Why: only a caller already known as the legacy coordinator is in this fence's jurisdiction;
+      // fencing anyone else hides the honest downstream error behind unusable takeover guidance.
+      if (
+        !evidence.terminalHandle ||
+        !db.isLegacyCoordinatorHandle(adoption.adopted_run_id, evidence.terminalHandle)
+      ) {
+        return undefined
+      }
+      throw legacyCoordinatorReadOnly()
     }
     const existing = db.getLegacyCoordinatorPrincipal(adoption.adopted_run_id)
     const proofCandidate = existing
@@ -181,6 +182,18 @@ export class LegacyCoordinatorAuthority {
   }
 }
 
+function ownsRunBinding(
+  run: { coordinator_handle: string | null; coordinator_pane_key: string | null },
+  identity: { terminalHandle?: string; paneKey?: string } | null
+): boolean {
+  return Boolean(
+    identity?.terminalHandle &&
+    run.coordinator_pane_key &&
+    run.coordinator_handle === identity.terminalHandle &&
+    equivalentLegacyPaneKey(run.coordinator_pane_key, identity.paneKey)
+  )
+}
+
 function boundRunId(db: OrchestrationDb, request: RpcRequest): string | undefined {
   const paneKey = request.orchestrationCompatibilityEvidence?.paneKey
   return paneKey ? db.getCurrentRunForPane(paneKey)?.id : undefined
diff --git a/src/main/runtime/rpc/orchestration-legacy-fence-jurisdiction.test.ts b/src/main/runtime/rpc/orchestration-legacy-fence-jurisdiction.test.ts
new file mode 100644
index 00000000000..d04c24dbbd1
--- /dev/null
+++ b/src/main/runtime/rpc/orchestration-legacy-fence-jurisdiction.test.ts
@@ -0,0 +1,188 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import type { OrchestrationCompatibilityEvidence } from '../../../shared/orchestration-compatibility-evidence'
+import {
+  cleanupLegacyCompatibilityDispatcherHarnesses,
+  COORDINATOR_HANDLE,
+  createHarness,
+  currentEvidence,
+  CURRENT_COORDINATOR_HANDLE,
+  CURRENT_COORDINATOR_PANE,
+  evidence,
+  request,
+  type LegacyCompatibilityDispatcherHarness
+} from './orchestration-legacy-compatibility-dispatcher-test-fixture'
+
+afterEach(() => {
+  cleanupLegacyCompatibilityDispatcherHarnesses()
+})
+
+function unattested(proof: OrchestrationCompatibilityEvidence): OrchestrationCompatibilityEvidence {
+  return { ...proof, launchToken: '' }
+}
+
+async function claimAdoptedRunAsLegacyCoordinator(
+  harness: LegacyCompatibilityDispatcherHarness
+): Promise<void> {
+  const response = await harness.dispatcher.dispatch(
+    request(
+      'orchestration.runUse',
+      { id: harness.adoptedRunId, from: COORDINATOR_HANDLE },
+      evidence('coordinator'),
+      'legacy-coordinator-run-use'
+    )
+  )
+  expect(response).toMatchObject({ ok: true })
+  expect(harness.db.getLegacyCoordinatorPrincipal(harness.adoptedRunId)?.status).toBe('committed')
+}
+
+async function takeoverAdoptedRun(harness: LegacyCompatibilityDispatcherHarness): Promise<void> {
+  const response = await harness.dispatcher.dispatch(
+    request(
+      'orchestration.runUse',
+      { id: harness.adoptedRunId, from: CURRENT_COORDINATOR_HANDLE, takeoverLegacy: true },
+      currentEvidence('coordinator'),
+      'current-coordinator-takeover'
+    )
+  )
+  expect(response).toMatchObject({ ok: true })
+  expect(harness.db.getLegacyCoordinatorPrincipal(harness.adoptedRunId)?.status).toBe('revoked')
+}
+
+describe('legacy coordinator fence jurisdiction', () => {
+  it('declines jurisdiction over an unbound stranger while the adopted Run is claimed', async () => {
+    const harness = createHarness()
+    await claimAdoptedRunAsLegacyCoordinator(harness)
+
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.taskCreate',
+        { spec: 'fresh assignment', callerTerminalHandle: CURRENT_COORDINATOR_HANDLE },
+        currentEvidence('coordinator'),
+        'claimed-stranger-task-create'
+      )
+    )
+
+    expect(response).toMatchObject({ ok: false, error: { code: 'run_required' } })
+    expect(harness.db.listTasks({ runId: harness.adoptedRunId })).toHaveLength(1)
+  })
+
+  it('releases the fence once the adopted Run is unclaimed and its principal is revoked', async () => {
+    const harness = createHarness()
+    await claimAdoptedRunAsLegacyCoordinator(harness)
+    await takeoverAdoptedRun(harness)
+    // The new owner moves its pane to another Run, which unbinds the adopted Run.
+    const elsewhere = harness.db.createRun({
+      objective: 'other work',
+      coordinatorHandle: CURRENT_COORDINATOR_HANDLE,
+      coordinatorPaneKey: CURRENT_COORDINATOR_PANE
+    })
+    expect(elsewhere.id).not.toBe(harness.adoptedRunId)
+    expect(harness.db.getRun(harness.adoptedRunId)?.coordinator_pane_key).toBeNull()
+
+    const fenced = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.taskCreate',
+        { spec: 'unclaimed assignment', callerTerminalHandle: COORDINATOR_HANDLE },
+        evidence('coordinator'),
+        'unclaimed-revoked-task-create'
+      )
+    )
+    expect(fenced).toMatchObject({ ok: false, error: { code: 'run_required' } })
+
+    const reclaim = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.runUse',
+        { id: harness.adoptedRunId, from: COORDINATOR_HANDLE },
+        evidence('coordinator'),
+        'unclaimed-revoked-run-use'
+      )
+    )
+    // The Run still holds live legacy work, so the honest downstream error — not a dead-end fence — answers.
+    expect(reclaim).toMatchObject({
+      ok: false,
+      error: {
+        code: 'consumer_fenced',
+        data: {
+          recoveryCommand: `orca orchestration run-use --id ${harness.adoptedRunId} --takeover-legacy`
+        }
+      }
+    })
+
+    const recovered = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.runUse',
+        { id: harness.adoptedRunId, from: COORDINATOR_HANDLE, takeoverLegacy: true },
+        evidence('coordinator'),
+        'unclaimed-revoked-run-takeover'
+      )
+    )
+    expect(recovered).toMatchObject({ ok: true, result: { run: { id: harness.adoptedRunId } } })
+  })
+
+  it('leaves a named adopted Run to the downstream consumer check instead of the fence', async () => {
+    const harness = createHarness()
+    await claimAdoptedRunAsLegacyCoordinator(harness)
+
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.taskCreate',
+        {
+          spec: 'stranger assignment',
+          run: harness.adoptedRunId,
+          callerTerminalHandle: CURRENT_COORDINATOR_HANDLE
+        },
+        currentEvidence('coordinator'),
+        'claimed-stranger-named-run-task-create'
+      )
+    )
+
+    expect(response).toMatchObject({ ok: false, error: { code: 'consumer_fenced' } })
+    expect(harness.db.listTasks({ runId: harness.adoptedRunId })).toHaveLength(1)
+  })
+
+  it('still fences the legacy coordinator after its principal is revoked by a takeover', async () => {
+    const harness = createHarness()
+    await claimAdoptedRunAsLegacyCoordinator(harness)
+    await takeoverAdoptedRun(harness)
+
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.taskCreate',
+        {
+          spec: 'stale assignment',
+          run: harness.adoptedRunId,
+          callerTerminalHandle: COORDINATOR_HANDLE
+        },
+        evidence('coordinator'),
+        'revoked-legacy-task-create'
+      )
+    )
+
+    expect(response).toMatchObject({ ok: false, error: { code: 'legacy_read_only' } })
+    expect(harness.db.listTasks({ runId: harness.adoptedRunId })).toHaveLength(1)
+  })
+
+  it('lets the post-takeover owner operate the adopted Run without attestation', async () => {
+    const harness = createHarness()
+    await claimAdoptedRunAsLegacyCoordinator(harness)
+    await takeoverAdoptedRun(harness)
+
+    const response = await harness.dispatcher.dispatch(
+      request(
+        'orchestration.taskCreate',
+        {
+          spec: 'owner assignment',
+          run: harness.adoptedRunId,
+          callerTerminalHandle: CURRENT_COORDINATOR_HANDLE
+        },
+        unattested(currentEvidence('coordinator')),
+        'owner-unattested-task-create'
+      )
+    )
+
+    expect(response).toMatchObject({
+      ok: true,
+      result: { task: { run_id: harness.adoptedRunId, spec: 'owner assignment' } }
+    })
+  })
+})

From f3f5a928f6232c0ba812d2a3b343c37af8410edf Mon Sep 17 00:00:00 2001
From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com>
Date: Fri, 31 Jul 2026 11:25:30 -0700
Subject: [PATCH 22/23] Fix duplicate terminal renderers after layout restore
 (#11726)

* Fix duplicate terminal PTY layout ownership

* Fix rootless duplicate PTY replay

* Normalize mirrored terminal PTY ownership

* Handle repeated terminal layout leaf ownership

* Preserve terminal ownership through duplicate layout repair

* Repair dangling PTY layout selection

* Preserve terminal ownership repair metadata

* Preserve rootless pending terminal focus

* Bound duplicate terminal layout pruning

* Preserve agent authority during layout repair

* Fix hydrated terminal pane authority repair
---
 .../terminal-pane/layout-serialization.ts     |   3 +-
 ...rminal-layout-duplicate-pty-replay.test.ts | 127 +++++
 .../terminal-pane/terminal-layout-leaf-ids.ts |  26 +-
 ...erminal-layout-pty-ownership-depth.test.ts |  30 ++
 .../terminal-layout-pty-ownership.test.ts     | 479 ++++++++++++++++++
 .../terminal-layout-pty-ownership.ts          | 319 ++++++++++++
 .../src/runtime/web-session-tabs-sync.test.ts |  93 +++-
 .../src/runtime/web-session-tabs-sync.ts      |  71 ++-
 .../terminal-layout-pty-ownership.test.ts     | 235 +++++++++
 src/renderer/src/store/slices/terminals.ts    |  82 ++-
 10 files changed, 1439 insertions(+), 26 deletions(-)
 create mode 100644 src/renderer/src/components/terminal-pane/terminal-layout-duplicate-pty-replay.test.ts
 create mode 100644 src/renderer/src/components/terminal-pane/terminal-layout-pty-ownership-depth.test.ts
 create mode 100644 src/renderer/src/components/terminal-pane/terminal-layout-pty-ownership.test.ts
 create mode 100644 src/renderer/src/components/terminal-pane/terminal-layout-pty-ownership.ts
 create mode 100644 src/renderer/src/store/slices/terminal-layout-pty-ownership.test.ts

diff --git a/src/renderer/src/components/terminal-pane/layout-serialization.ts b/src/renderer/src/components/terminal-pane/layout-serialization.ts
index add3280e658..6fb2df02703 100644
--- a/src/renderer/src/components/terminal-pane/layout-serialization.ts
+++ b/src/renderer/src/components/terminal-pane/layout-serialization.ts
@@ -238,12 +238,11 @@ export function replayTerminalLayout(
 ): Map<string, number> {
   const paneByLeafId = new Map<string, number>()
 
-  const inputSnapshot = snapshot
   const normalized = normalizeTerminalLayoutSnapshot(snapshot)
   snapshot = normalized.snapshot
   const initialLeafId = snapshot.root
     ? getLeftmostLeafId(snapshot.root)
-    : (resolveRootlessTerminalLayoutLeafId(inputSnapshot ?? snapshot) ?? undefined)
+    : (resolveRootlessTerminalLayoutLeafId(snapshot) ?? undefined)
   const initialPane = manager.createInitialPane({ focus: focusInitialPane, leafId: initialLeafId })
   if (!snapshot?.root) {
     paneByLeafId.set(initialPane.leafId, initialPane.id)
diff --git a/src/renderer/src/components/terminal-pane/terminal-layout-duplicate-pty-replay.test.ts b/src/renderer/src/components/terminal-pane/terminal-layout-duplicate-pty-replay.test.ts
new file mode 100644
index 00000000000..c7cf27b3b01
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/terminal-layout-duplicate-pty-replay.test.ts
@@ -0,0 +1,127 @@
+import { describe, expect, it, vi } from 'vitest'
+import { replayTerminalLayout } from './layout-serialization'
+
+const LEAF_1 = '11111111-1111-4111-8111-111111111111'
+const LEAF_2 = '22222222-2222-4222-8222-222222222222'
+const LEAF_3 = '33333333-3333-4333-8333-333333333333'
+
+describe('duplicate PTY layout replay', () => {
+  it('replays one surface when restored leaves point to the same PTY', () => {
+    const manager = {
+      createInitialPane: vi.fn((opts?: { leafId?: string }) => ({
+        id: 1,
+        leafId: opts?.leafId ?? LEAF_1
+      })),
+      splitPane: vi.fn()
+    }
+
+    const restored = replayTerminalLayout(
+      manager as unknown as Parameters<typeof replayTerminalLayout>[0],
+      {
+        root: {
+          type: 'split',
+          direction: 'vertical',
+          first: { type: 'leaf', leafId: LEAF_1 },
+          second: { type: 'leaf', leafId: LEAF_2 }
+        },
+        activeLeafId: LEAF_2,
+        expandedLeafId: null,
+        ptyIdsByLeafId: {
+          [LEAF_1]: 'pty-agent',
+          [LEAF_2]: 'pty-agent'
+        }
+      },
+      true
+    )
+
+    expect(manager.createInitialPane).toHaveBeenCalledWith({ focus: true, leafId: LEAF_2 })
+    expect(manager.splitPane).not.toHaveBeenCalled()
+    expect([...restored]).toEqual([[LEAF_2, 1]])
+  })
+
+  it('reattaches the retained PTY leaf from rootless duplicate state', () => {
+    const manager = {
+      createInitialPane: vi.fn((opts?: { leafId?: string }) => ({
+        id: 1,
+        leafId: opts?.leafId ?? LEAF_2
+      })),
+      splitPane: vi.fn()
+    }
+
+    const restored = replayTerminalLayout(
+      manager as unknown as Parameters<typeof replayTerminalLayout>[0],
+      {
+        root: null,
+        activeLeafId: null,
+        expandedLeafId: null,
+        ptyIdsByLeafId: {
+          [LEAF_1]: 'pty-agent',
+          [LEAF_2]: 'pty-agent'
+        }
+      },
+      true
+    )
+
+    expect(manager.createInitialPane).toHaveBeenCalledWith({ focus: true, leafId: LEAF_1 })
+    expect(manager.splitPane).not.toHaveBeenCalled()
+    expect([...restored]).toEqual([[LEAF_1, 1]])
+  })
+
+  it('preserves a rootless pending leaf while pruning duplicate PTY ownership', () => {
+    const manager = {
+      createInitialPane: vi.fn((opts?: { leafId?: string }) => ({
+        id: 1,
+        leafId: opts?.leafId ?? LEAF_2
+      })),
+      splitPane: vi.fn()
+    }
+
+    const restored = replayTerminalLayout(
+      manager as unknown as Parameters<typeof replayTerminalLayout>[0],
+      {
+        root: null,
+        activeLeafId: LEAF_3,
+        expandedLeafId: null,
+        ptyIdsByLeafId: {
+          [LEAF_1]: 'pty-agent',
+          [LEAF_2]: 'pty-agent'
+        }
+      },
+      true
+    )
+
+    expect(manager.createInitialPane).toHaveBeenCalledWith({ focus: true, leafId: LEAF_3 })
+    expect(manager.splitPane).not.toHaveBeenCalled()
+    expect([...restored]).toEqual([[LEAF_3, 1]])
+  })
+
+  it('reattaches one PTY when the split repeats its bound leaf id', () => {
+    const manager = {
+      createInitialPane: vi.fn((opts?: { leafId?: string }) => ({
+        id: 1,
+        leafId: opts?.leafId ?? LEAF_2
+      })),
+      splitPane: vi.fn()
+    }
+
+    const restored = replayTerminalLayout(
+      manager as unknown as Parameters<typeof replayTerminalLayout>[0],
+      {
+        root: {
+          type: 'split',
+          direction: 'vertical',
+          first: { type: 'leaf', leafId: LEAF_1 },
+          second: { type: 'leaf', leafId: LEAF_1 }
+        },
+        activeLeafId: LEAF_1,
+        expandedLeafId: null,
+        ptyIdsByLeafId: { [LEAF_1]: 'pty-agent' }
+      },
+      true
+    )
+
+    expect(manager.createInitialPane).toHaveBeenCalledWith({ focus: true, leafId: LEAF_1 })
+    expect(manager.splitPane).not.toHaveBeenCalled()
+    expect([...restored]).toEqual([[LEAF_1, 1]])
+  })
+})
diff --git a/src/renderer/src/components/terminal-pane/terminal-layout-leaf-ids.ts b/src/renderer/src/components/terminal-pane/terminal-layout-leaf-ids.ts
index 81e4efd6af5..bd780e89495 100644
--- a/src/renderer/src/components/terminal-pane/terminal-layout-leaf-ids.ts
+++ b/src/renderer/src/components/terminal-pane/terminal-layout-leaf-ids.ts
@@ -1,6 +1,7 @@
 import type { TerminalLayoutSnapshot, TerminalPaneLayoutNode } from '../../../../shared/types'
 import { isTerminalLeafId, type TerminalLeafId } from '../../../../shared/stable-pane-id'
 import { mintStablePaneId } from '@/lib/pane-manager/mint-stable-pane-id'
+import { normalizeTerminalLayoutPtyOwnership } from './terminal-layout-pty-ownership'
 
 const EMPTY_TERMINAL_LAYOUT: TerminalLayoutSnapshot = {
   root: null,
@@ -124,9 +125,10 @@ function getRemappedLeafId(
   return rewrite.nextLeafIdByInputLeafId.get(leafId) ?? null
 }
 
-export function normalizeTerminalLayoutSnapshot(
-  snapshot: TerminalLayoutSnapshot | null | undefined
-): { snapshot: TerminalLayoutSnapshot; changed: boolean } {
+function normalizeTerminalLayoutLeafIds(snapshot: TerminalLayoutSnapshot | null | undefined): {
+  snapshot: TerminalLayoutSnapshot
+  changed: boolean
+} {
   if (!snapshot?.root) {
     const nextSnapshot = snapshot ?? EMPTY_TERMINAL_LAYOUT
     const activeLeafId = resolveRootlessTerminalLayoutLeafId(nextSnapshot)
@@ -207,6 +209,24 @@ export function normalizeTerminalLayoutSnapshot(
   }
 }
 
+export function normalizeTerminalLayoutSnapshot(
+  snapshot: TerminalLayoutSnapshot | null | undefined
+): { snapshot: TerminalLayoutSnapshot; changed: boolean } {
+  const ptyOwnership = normalizeTerminalLayoutPtyOwnership(snapshot ?? EMPTY_TERMINAL_LAYOUT)
+  const leafIds = normalizeTerminalLayoutLeafIds(ptyOwnership.snapshot)
+  const activeLeafId = leafIds.snapshot.root
+    ? leafIds.snapshot.activeLeafId
+    : resolveRootlessTerminalLayoutLeafId(leafIds.snapshot)
+  return {
+    snapshot:
+      activeLeafId === leafIds.snapshot.activeLeafId
+        ? leafIds.snapshot
+        : { ...leafIds.snapshot, activeLeafId },
+    changed:
+      ptyOwnership.changed || leafIds.changed || activeLeafId !== leafIds.snapshot.activeLeafId
+  }
+}
+
 export function collectLeafIdsInOrder(node: TerminalPaneLayoutNode | null | undefined): string[] {
   if (!node) {
     return []
diff --git a/src/renderer/src/components/terminal-pane/terminal-layout-pty-ownership-depth.test.ts b/src/renderer/src/components/terminal-pane/terminal-layout-pty-ownership-depth.test.ts
new file mode 100644
index 00000000000..a7e3fa4fc5a
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/terminal-layout-pty-ownership-depth.test.ts
@@ -0,0 +1,30 @@
+import { expect, it } from 'vitest'
+import type { TerminalPaneLayoutNode } from '../../../../shared/types'
+import { normalizeTerminalLayoutPtyOwnership } from './terminal-layout-pty-ownership'
+
+it('prunes deeply nested duplicate ownership without recursive stack growth', () => {
+  const leafCount = 12_000
+  let root: TerminalPaneLayoutNode = { type: 'leaf', leafId: 'leaf-0' }
+  const ptyIdsByLeafId: Record<string, string> = { 'leaf-0': 'pty-agent' }
+  for (let index = 1; index < leafCount; index += 1) {
+    const leafId = `leaf-${index}`
+    root = {
+      type: 'split',
+      direction: 'vertical',
+      first: root,
+      second: { type: 'leaf', leafId }
+    }
+    ptyIdsByLeafId[leafId] = 'pty-agent'
+  }
+
+  const retainedLeafId = `leaf-${leafCount - 1}`
+  const normalized = normalizeTerminalLayoutPtyOwnership({
+    root,
+    activeLeafId: retainedLeafId,
+    expandedLeafId: null,
+    ptyIdsByLeafId
+  }).snapshot
+
+  expect(normalized.root).toEqual({ type: 'leaf', leafId: retainedLeafId })
+  expect(normalized.ptyIdsByLeafId).toEqual({ [retainedLeafId]: 'pty-agent' })
+})
diff --git a/src/renderer/src/components/terminal-pane/terminal-layout-pty-ownership.test.ts b/src/renderer/src/components/terminal-pane/terminal-layout-pty-ownership.test.ts
new file mode 100644
index 00000000000..92a0def1df1
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/terminal-layout-pty-ownership.test.ts
@@ -0,0 +1,479 @@
+import { describe, expect, it } from 'vitest'
+import type { TerminalLayoutSnapshot } from '../../../../shared/types'
+import { normalizeTerminalLayoutSnapshot } from './terminal-layout-leaf-ids'
+import { normalizeTerminalLayoutPtyOwnership } from './terminal-layout-pty-ownership'
+
+const LEAF_1 = '11111111-1111-4111-8111-111111111111'
+const LEAF_2 = '22222222-2222-4222-8222-222222222222'
+const LEAF_3 = '33333333-3333-4333-8333-333333333333'
+
+function collectRootLeafIds(layout: TerminalLayoutSnapshot): string[] {
+  const visit = (node: NonNullable<TerminalLayoutSnapshot['root']>): string[] =>
+    node.type === 'leaf' ? [node.leafId] : [...visit(node.first), ...visit(node.second)]
+  return layout.root ? visit(layout.root) : []
+}
+
+function duplicatePtyLayout(): TerminalLayoutSnapshot {
+  return {
+    root: {
+      type: 'split',
+      direction: 'vertical',
+      ratio: 0.4,
+      first: {
+        type: 'split',
+        direction: 'horizontal',
+        ratio: 0.25,
+        first: { type: 'leaf', leafId: LEAF_1 },
+        second: { type: 'leaf', leafId: LEAF_2 }
+      },
+      second: { type: 'leaf', leafId: LEAF_3 }
+    },
+    activeLeafId: LEAF_2,
+    expandedLeafId: LEAF_1,
+    ptyIdsByLeafId: {
+      [LEAF_1]: 'pty-agent',
+      [LEAF_2]: 'pty-agent',
+      [LEAF_3]: 'remote:env-1@@term_setup'
+    },
+    buffersByLeafId: {
+      [LEAF_1]: 'stale agent buffer',
+      [LEAF_2]: 'active agent buffer',
+      [LEAF_3]: 'setup buffer'
+    },
+    scrollbackRefsByLeafId: {
+      [LEAF_1]: 'stale-agent-scrollback',
+      [LEAF_2]: 'active-agent-scrollback',
+      [LEAF_3]: 'setup-scrollback'
+    },
+    titlesByLeafId: {
+      [LEAF_1]: 'stale agent',
+      [LEAF_2]: 'active agent',
+      [LEAF_3]: 'setup'
+    }
+  }
+}
+
+describe('terminal layout PTY ownership normalization', () => {
+  it('keeps the active leaf and prunes the stale surface plus its metadata', () => {
+    const normalized = normalizeTerminalLayoutSnapshot(duplicatePtyLayout())
+
+    expect(normalized.changed).toBe(true)
+    expect(normalized.snapshot).toEqual({
+      root: {
+        type: 'split',
+        direction: 'vertical',
+        ratio: 0.4,
+        first: { type: 'leaf', leafId: LEAF_2 },
+        second: { type: 'leaf', leafId: LEAF_3 }
+      },
+      activeLeafId: LEAF_2,
+      expandedLeafId: null,
+      ptyIdsByLeafId: {
+        [LEAF_2]: 'pty-agent',
+        [LEAF_3]: 'remote:env-1@@term_setup'
+      },
+      buffersByLeafId: {
+        [LEAF_2]: 'active agent buffer',
+        [LEAF_3]: 'setup buffer'
+      },
+      scrollbackRefsByLeafId: {
+        [LEAF_2]: 'active-agent-scrollback',
+        [LEAF_3]: 'setup-scrollback'
+      },
+      titlesByLeafId: {
+        [LEAF_2]: 'active agent',
+        [LEAF_3]: 'setup'
+      }
+    })
+  })
+
+  it('keeps the first layout leaf when focus belongs to another PTY', () => {
+    const layout = duplicatePtyLayout()
+    layout.activeLeafId = LEAF_3
+    layout.expandedLeafId = null
+
+    const normalized = normalizeTerminalLayoutSnapshot(layout)
+
+    expect(normalized.snapshot.root).toEqual({
+      type: 'split',
+      direction: 'vertical',
+      ratio: 0.4,
+      first: { type: 'leaf', leafId: LEAF_1 },
+      second: { type: 'leaf', leafId: LEAF_3 }
+    })
+    expect(normalized.snapshot.activeLeafId).toBe(LEAF_3)
+    expect(normalized.snapshot.ptyIdsByLeafId).toEqual({
+      [LEAF_1]: 'pty-agent',
+      [LEAF_3]: 'remote:env-1@@term_setup'
+    })
+  })
+
+  it('carries missing scrollback metadata onto the surviving leaf', () => {
+    const layout = duplicatePtyLayout()
+    layout.buffersByLeafId = { [LEAF_1]: 'only cached buffer' }
+    layout.scrollbackRefsByLeafId = { [LEAF_1]: 'only-scrollback-ref' }
+    layout.titlesByLeafId = { [LEAF_1]: 'only cached title' }
+
+    const normalized = normalizeTerminalLayoutSnapshot(layout).snapshot
+
+    expect(normalized.buffersByLeafId).toEqual({ [LEAF_2]: 'only cached buffer' })
+    expect(normalized.scrollbackRefsByLeafId).toEqual({ [LEAF_2]: 'only-scrollback-ref' })
+    expect(normalized.titlesByLeafId).toEqual({ [LEAF_2]: 'only cached title' })
+  })
+
+  it('does not combine a retained buffer with a stale duplicate scrollback ref', () => {
+    const layout = duplicatePtyLayout()
+    layout.buffersByLeafId = { [LEAF_2]: 'active buffer' }
+    layout.scrollbackRefsByLeafId = { [LEAF_1]: 'stale-scrollback-ref' }
+
+    const normalized = normalizeTerminalLayoutPtyOwnership(layout).snapshot
+
+    expect(normalized.buffersByLeafId).toEqual({ [LEAF_2]: 'active buffer' })
+    expect(normalized.scrollbackRefsByLeafId).toBeUndefined()
+  })
+
+  it('coalesces chained duplicate metadata in layout order', () => {
+    const layout = duplicatePtyLayout()
+    layout.activeLeafId = LEAF_3
+    layout.ptyIdsByLeafId = {
+      [LEAF_1]: 'pty-agent',
+      [LEAF_2]: 'pty-agent',
+      [LEAF_3]: 'pty-agent'
+    }
+    layout.buffersByLeafId = {
+      [LEAF_1]: 'first cached buffer',
+      [LEAF_2]: 'second cached buffer'
+    }
+    layout.scrollbackRefsByLeafId = undefined
+
+    const normalized = normalizeTerminalLayoutSnapshot(layout).snapshot
+
+    expect(normalized.root).toEqual({ type: 'leaf', leafId: LEAF_3 })
+    expect(normalized.buffersByLeafId).toEqual({ [LEAF_3]: 'first cached buffer' })
+  })
+
+  it('deduplicates rootless remount state without guessing among distinct PTYs', () => {
+    const normalized = normalizeTerminalLayoutSnapshot({
+      root: null,
+      activeLeafId: LEAF_2,
+      expandedLeafId: null,
+      ptyIdsByLeafId: {
+        [LEAF_1]: 'pty-agent',
+        [LEAF_2]: 'pty-agent',
+        [LEAF_3]: 'pty-setup'
+      }
+    })
+
+    expect(normalized.snapshot).toEqual({
+      root: null,
+      activeLeafId: LEAF_2,
+      expandedLeafId: null,
+      ptyIdsByLeafId: {
+        [LEAF_2]: 'pty-agent',
+        [LEAF_3]: 'pty-setup'
+      }
+    })
+  })
+
+  it('keeps rooted ownership when stale focus names a dangling duplicate leaf', () => {
+    const normalized = normalizeTerminalLayoutPtyOwnership({
+      root: { type: 'leaf', leafId: LEAF_1 },
+      activeLeafId: LEAF_2,
+      expandedLeafId: null,
+      ptyIdsByLeafId: {
+        [LEAF_1]: 'pty-agent',
+        [LEAF_2]: 'pty-agent'
+      }
+    })
+
+    expect(normalized.snapshot).toEqual({
+      root: { type: 'leaf', leafId: LEAF_1 },
+      activeLeafId: LEAF_1,
+      expandedLeafId: null,
+      ptyIdsByLeafId: { [LEAF_1]: 'pty-agent' }
+    })
+  })
+
+  it('repairs rootless duplicate ownership in one idempotent pass', () => {
+    const normalized = normalizeTerminalLayoutSnapshot({
+      root: null,
+      activeLeafId: null,
+      expandedLeafId: null,
+      ptyIdsByLeafId: {
+        [LEAF_1]: 'pty-agent',
+        [LEAF_2]: 'pty-agent'
+      }
+    })
+
+    expect(normalized.snapshot).toEqual({
+      root: null,
+      activeLeafId: LEAF_1,
+      expandedLeafId: null,
+      ptyIdsByLeafId: { [LEAF_1]: 'pty-agent' }
+    })
+    expect(normalizeTerminalLayoutSnapshot(normalized.snapshot)).toEqual({
+      snapshot: normalized.snapshot,
+      changed: false
+    })
+  })
+
+  it('preserves rootless pending focus while repairing duplicate ownership', () => {
+    const normalized = normalizeTerminalLayoutSnapshot({
+      root: null,
+      activeLeafId: LEAF_3,
+      expandedLeafId: LEAF_3,
+      ptyIdsByLeafId: {
+        [LEAF_1]: 'pty-agent',
+        [LEAF_2]: 'pty-agent'
+      }
+    })
+
+    expect(normalized.snapshot).toEqual({
+      root: null,
+      activeLeafId: LEAF_3,
+      expandedLeafId: null,
+      ptyIdsByLeafId: { [LEAF_1]: 'pty-agent' }
+    })
+  })
+
+  it('repairs dangling rooted selection during direct ownership normalization', () => {
+    const normalized = normalizeTerminalLayoutPtyOwnership({
+      root: {
+        type: 'split',
+        direction: 'vertical',
+        first: { type: 'leaf', leafId: LEAF_1 },
+        second: { type: 'leaf', leafId: LEAF_2 }
+      },
+      activeLeafId: LEAF_3,
+      expandedLeafId: LEAF_3,
+      ptyIdsByLeafId: {
+        [LEAF_1]: 'pty-agent',
+        [LEAF_2]: 'pty-agent'
+      }
+    })
+
+    expect(normalized.snapshot).toEqual({
+      root: { type: 'leaf', leafId: LEAF_1 },
+      activeLeafId: LEAF_1,
+      expandedLeafId: null,
+      ptyIdsByLeafId: { [LEAF_1]: 'pty-agent' }
+    })
+  })
+
+  it('keeps a valid active unbound leaf while repairing duplicate sibling ownership', () => {
+    const normalized = normalizeTerminalLayoutPtyOwnership({
+      root: {
+        type: 'split',
+        direction: 'vertical',
+        first: {
+          type: 'split',
+          direction: 'horizontal',
+          first: { type: 'leaf', leafId: LEAF_1 },
+          second: { type: 'leaf', leafId: LEAF_2 }
+        },
+        second: { type: 'leaf', leafId: LEAF_3 }
+      },
+      activeLeafId: LEAF_3,
+      expandedLeafId: LEAF_3,
+      ptyIdsByLeafId: {
+        [LEAF_1]: 'pty-agent',
+        [LEAF_2]: 'pty-agent'
+      }
+    })
+
+    expect(normalized.snapshot).toEqual({
+      root: {
+        type: 'split',
+        direction: 'vertical',
+        first: { type: 'leaf', leafId: LEAF_1 },
+        second: { type: 'leaf', leafId: LEAF_3 }
+      },
+      activeLeafId: LEAF_3,
+      expandedLeafId: LEAF_3,
+      ptyIdsByLeafId: { [LEAF_1]: 'pty-agent' }
+    })
+  })
+
+  it('collapses repeated live leaf ids without looping during direct normalization', () => {
+    const normalized = normalizeTerminalLayoutPtyOwnership({
+      root: {
+        type: 'split',
+        direction: 'vertical',
+        first: { type: 'leaf', leafId: LEAF_1 },
+        second: { type: 'leaf', leafId: LEAF_1 }
+      },
+      activeLeafId: LEAF_1,
+      expandedLeafId: LEAF_1,
+      ptyIdsByLeafId: { [LEAF_1]: 'pty-agent' },
+      buffersByLeafId: { [LEAF_1]: 'cached buffer' }
+    })
+
+    expect(normalized.snapshot).toEqual({
+      root: { type: 'leaf', leafId: LEAF_1 },
+      activeLeafId: LEAF_1,
+      expandedLeafId: LEAF_1,
+      ptyIdsByLeafId: { [LEAF_1]: 'pty-agent' },
+      buffersByLeafId: { [LEAF_1]: 'cached buffer' }
+    })
+    expect(normalizeTerminalLayoutPtyOwnership(normalized.snapshot)).toEqual({
+      snapshot: normalized.snapshot,
+      changed: false
+    })
+  })
+
+  it('keeps active metadata when its retained leaf id also repeats', () => {
+    const normalized = normalizeTerminalLayoutPtyOwnership({
+      root: {
+        type: 'split',
+        direction: 'horizontal',
+        first: { type: 'leaf', leafId: LEAF_1 },
+        second: {
+          type: 'split',
+          direction: 'vertical',
+          first: { type: 'leaf', leafId: LEAF_2 },
+          second: { type: 'leaf', leafId: LEAF_2 }
+        }
+      },
+      activeLeafId: LEAF_2,
+      expandedLeafId: LEAF_2,
+      ptyIdsByLeafId: {
+        [LEAF_1]: 'pty-agent',
+        [LEAF_2]: 'pty-agent'
+      },
+      buffersByLeafId: {
+        [LEAF_1]: 'stale buffer',
+        [LEAF_2]: 'active buffer'
+      },
+      titlesByLeafId: {
+        [LEAF_1]: 'stale title',
+        [LEAF_2]: 'active title'
+      }
+    }).snapshot
+
+    expect(normalized).toEqual({
+      root: { type: 'leaf', leafId: LEAF_2 },
+      activeLeafId: LEAF_2,
+      expandedLeafId: LEAF_2,
+      ptyIdsByLeafId: { [LEAF_2]: 'pty-agent' },
+      buffersByLeafId: { [LEAF_2]: 'active buffer' },
+      titlesByLeafId: { [LEAF_2]: 'active title' }
+    })
+  })
+
+  it('preserves PTY ownership while collapsing repeated live leaf ids', () => {
+    const normalized = normalizeTerminalLayoutSnapshot({
+      root: {
+        type: 'split',
+        direction: 'vertical',
+        first: { type: 'leaf', leafId: LEAF_1 },
+        second: { type: 'leaf', leafId: LEAF_1 }
+      },
+      activeLeafId: LEAF_1,
+      expandedLeafId: LEAF_1,
+      ptyIdsByLeafId: { [LEAF_1]: 'pty-agent' },
+      buffersByLeafId: { [LEAF_1]: 'cached buffer' }
+    })
+
+    expect(normalized.snapshot).toEqual({
+      root: { type: 'leaf', leafId: LEAF_1 },
+      activeLeafId: LEAF_1,
+      expandedLeafId: LEAF_1,
+      ptyIdsByLeafId: { [LEAF_1]: 'pty-agent' },
+      buffersByLeafId: { [LEAF_1]: 'cached buffer' }
+    })
+    expect(normalizeTerminalLayoutSnapshot(normalized.snapshot)).toEqual({
+      snapshot: normalized.snapshot,
+      changed: false
+    })
+  })
+
+  it('retains one repeated PTY leaf alongside distinct sibling ownership', () => {
+    const normalized = normalizeTerminalLayoutSnapshot({
+      root: {
+        type: 'split',
+        direction: 'vertical',
+        first: {
+          type: 'split',
+          direction: 'horizontal',
+          first: { type: 'leaf', leafId: LEAF_1 },
+          second: { type: 'leaf', leafId: LEAF_1 }
+        },
+        second: { type: 'leaf', leafId: LEAF_2 }
+      },
+      activeLeafId: LEAF_1,
+      expandedLeafId: LEAF_1,
+      ptyIdsByLeafId: {
+        [LEAF_1]: 'pty-agent',
+        [LEAF_2]: 'pty-shell'
+      }
+    }).snapshot
+
+    expect(normalized).toEqual({
+      root: {
+        type: 'split',
+        direction: 'vertical',
+        first: { type: 'leaf', leafId: LEAF_1 },
+        second: { type: 'leaf', leafId: LEAF_2 }
+      },
+      activeLeafId: LEAF_1,
+      expandedLeafId: LEAF_1,
+      ptyIdsByLeafId: {
+        [LEAF_1]: 'pty-agent',
+        [LEAF_2]: 'pty-shell'
+      }
+    })
+  })
+
+  it('preserves valid split layouts by identity', () => {
+    const layout = duplicatePtyLayout()
+    layout.ptyIdsByLeafId = {
+      [LEAF_1]: 'pty-1',
+      [LEAF_2]: 'pty-2',
+      [LEAF_3]: 'remote:env-1@@term_setup'
+    }
+
+    const normalized = normalizeTerminalLayoutSnapshot(layout)
+
+    expect(normalized).toEqual({ snapshot: layout, changed: false })
+    expect(normalized.snapshot).toBe(layout)
+  })
+
+  it('is idempotent and preserves one owner across PTY and focus permutations', () => {
+    const ptyOptions = [undefined, 'pty-a', 'remote:env-1@@term_b'] as const
+    for (const firstPtyId of ptyOptions) {
+      for (const secondPtyId of ptyOptions) {
+        for (const thirdPtyId of ptyOptions) {
+          for (const activeLeafId of [LEAF_1, LEAF_2, LEAF_3]) {
+            const ptyIdsByLeafId = Object.fromEntries(
+              [
+                [LEAF_1, firstPtyId],
+                [LEAF_2, secondPtyId],
+                [LEAF_3, thirdPtyId]
+              ].filter((entry): entry is [string, string] => entry[1] !== undefined)
+            )
+            const layout = duplicatePtyLayout()
+            layout.activeLeafId = activeLeafId
+            layout.expandedLeafId = activeLeafId
+            layout.ptyIdsByLeafId = ptyIdsByLeafId
+            const before = structuredClone(layout)
+
+            const normalized = normalizeTerminalLayoutSnapshot(layout).snapshot
+            const normalizedPtyIds = Object.values(normalized.ptyIdsByLeafId ?? {})
+            const rootLeafIds = new Set(collectRootLeafIds(normalized))
+
+            expect(new Set(normalizedPtyIds).size).toBe(normalizedPtyIds.length)
+            expect(
+              Object.keys(normalized.ptyIdsByLeafId ?? {}).every((id) => rootLeafIds.has(id))
+            ).toBe(true)
+            expect(normalized.activeLeafId && rootLeafIds.has(normalized.activeLeafId)).toBe(true)
+            expect(normalizeTerminalLayoutSnapshot(normalized)).toEqual({
+              snapshot: normalized,
+              changed: false
+            })
+            expect(layout).toEqual(before)
+          }
+        }
+      }
+    }
+  })
+})
diff --git a/src/renderer/src/components/terminal-pane/terminal-layout-pty-ownership.ts b/src/renderer/src/components/terminal-pane/terminal-layout-pty-ownership.ts
new file mode 100644
index 00000000000..f0742328240
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/terminal-layout-pty-ownership.ts
@@ -0,0 +1,319 @@
+import type { TerminalLayoutSnapshot, TerminalPaneLayoutNode } from '../../../../shared/types'
+
+type TerminalLayoutPtyOwnershipNormalization = {
+  snapshot: TerminalLayoutSnapshot
+  changed: boolean
+}
+
+type DuplicatePtyLeafReplacements = {
+  orderedLeafIds: string[]
+  retainedLeafIdByRemovedLeafId: Map<string, string>
+}
+
+function collectLeafIds(node: TerminalPaneLayoutNode | null | undefined): string[] {
+  if (!node) {
+    return []
+  }
+  const leafIds: string[] = []
+  const pending = [node]
+  while (pending.length > 0) {
+    const current = pending.pop()!
+    if (current.type === 'leaf') {
+      leafIds.push(current.leafId)
+      continue
+    }
+    pending.push(current.second, current.first)
+  }
+  return leafIds
+}
+
+function pruneLeaves(
+  node: TerminalPaneLayoutNode,
+  retainedLeafIdByRemovedLeafId: ReadonlyMap<string, string>,
+  retainedSelfLeafIds: Set<string>
+): TerminalPaneLayoutNode | null {
+  const pending: { node: TerminalPaneLayoutNode; visited: boolean }[] = [{ node, visited: false }]
+  const pruned: (TerminalPaneLayoutNode | null)[] = []
+  while (pending.length > 0) {
+    const current = pending.pop()!
+    if (current.node.type === 'leaf') {
+      const retainedLeafId = retainedLeafIdByRemovedLeafId.get(current.node.leafId)
+      if (!retainedLeafId) {
+        pruned.push(current.node)
+      } else if (
+        retainedLeafId === current.node.leafId &&
+        !retainedSelfLeafIds.has(current.node.leafId)
+      ) {
+        retainedSelfLeafIds.add(current.node.leafId)
+        pruned.push(current.node)
+      } else {
+        pruned.push(null)
+      }
+      continue
+    }
+    if (!current.visited) {
+      pending.push({ node: current.node, visited: true })
+      pending.push({ node: current.node.second, visited: false })
+      pending.push({ node: current.node.first, visited: false })
+      continue
+    }
+    const second = pruned.pop() ?? null
+    const first = pruned.pop() ?? null
+    if (first && second) {
+      pruned.push(
+        first === current.node.first && second === current.node.second
+          ? current.node
+          : { ...current.node, first, second }
+      )
+    } else {
+      pruned.push(first ?? second)
+    }
+  }
+  return pruned[0] ?? null
+}
+
+function resolveRetainedLeafId(
+  leafId: string,
+  retainedLeafIdByRemovedLeafId: ReadonlyMap<string, string>
+): string {
+  let retainedLeafId = leafId
+  while (retainedLeafIdByRemovedLeafId.has(retainedLeafId)) {
+    const nextLeafId = retainedLeafIdByRemovedLeafId.get(retainedLeafId)
+    if (!nextLeafId || nextLeafId === retainedLeafId) {
+      return retainedLeafId
+    }
+    retainedLeafId = nextLeafId
+  }
+  return retainedLeafId
+}
+
+function coalesceLeafRecord(
+  source: Record<string, string> | undefined,
+  retainedLeafIdByRemovedLeafId: ReadonlyMap<string, string>
+): Record<string, string> | undefined {
+  if (!source) {
+    return undefined
+  }
+  const retained = Object.fromEntries(
+    Object.entries(source).filter(([leafId]) => {
+      const retainedLeafId = retainedLeafIdByRemovedLeafId.get(leafId)
+      return retainedLeafId === undefined || retainedLeafId === leafId
+    })
+  )
+  for (const [removedLeafId, value] of Object.entries(source)) {
+    if (!retainedLeafIdByRemovedLeafId.has(removedLeafId)) {
+      continue
+    }
+    const retainedLeafId = resolveRetainedLeafId(removedLeafId, retainedLeafIdByRemovedLeafId)
+    if (!Object.prototype.hasOwnProperty.call(retained, retainedLeafId)) {
+      retained[retainedLeafId] = value
+    }
+  }
+  return Object.keys(retained).length > 0 ? retained : undefined
+}
+
+function hasLeafRecordValue(source: Record<string, string> | undefined, leafId: string): boolean {
+  return Boolean(source && Object.prototype.hasOwnProperty.call(source, leafId))
+}
+
+function coalesceScrollbackRecords(
+  buffersByLeafId: Record<string, string> | undefined,
+  scrollbackRefsByLeafId: Record<string, string> | undefined,
+  retainedLeafIdByRemovedLeafId: ReadonlyMap<string, string>,
+  orderedLeafIds: readonly string[]
+): {
+  buffersByLeafId: Record<string, string> | undefined
+  scrollbackRefsByLeafId: Record<string, string> | undefined
+} {
+  const affectedRetainedLeafIds = new Set<string>()
+  for (const removedLeafId of retainedLeafIdByRemovedLeafId.keys()) {
+    affectedRetainedLeafIds.add(resolveRetainedLeafId(removedLeafId, retainedLeafIdByRemovedLeafId))
+  }
+
+  const sourceLeafIdByRetainedLeafId = new Map<string, string>()
+  for (const retainedLeafId of affectedRetainedLeafIds) {
+    if (
+      hasLeafRecordValue(buffersByLeafId, retainedLeafId) ||
+      hasLeafRecordValue(scrollbackRefsByLeafId, retainedLeafId)
+    ) {
+      sourceLeafIdByRetainedLeafId.set(retainedLeafId, retainedLeafId)
+    }
+  }
+  for (const leafId of orderedLeafIds) {
+    const retainedLeafId = resolveRetainedLeafId(leafId, retainedLeafIdByRemovedLeafId)
+    if (
+      !affectedRetainedLeafIds.has(retainedLeafId) ||
+      sourceLeafIdByRetainedLeafId.has(retainedLeafId)
+    ) {
+      continue
+    }
+    if (
+      hasLeafRecordValue(buffersByLeafId, leafId) ||
+      hasLeafRecordValue(scrollbackRefsByLeafId, leafId)
+    ) {
+      sourceLeafIdByRetainedLeafId.set(retainedLeafId, leafId)
+    }
+  }
+
+  const coalesce = (
+    source: Record<string, string> | undefined
+  ): Record<string, string> | undefined => {
+    if (!source) {
+      return undefined
+    }
+    const retained = Object.fromEntries(
+      Object.entries(source).filter(([leafId]) => {
+        const retainedLeafId = resolveRetainedLeafId(leafId, retainedLeafIdByRemovedLeafId)
+        return !affectedRetainedLeafIds.has(retainedLeafId)
+      })
+    )
+    for (const [retainedLeafId, sourceLeafId] of sourceLeafIdByRetainedLeafId) {
+      if (hasLeafRecordValue(source, sourceLeafId)) {
+        retained[retainedLeafId] = source[sourceLeafId]!
+      }
+    }
+    return Object.keys(retained).length > 0 ? retained : undefined
+  }
+
+  return {
+    buffersByLeafId: coalesce(buffersByLeafId),
+    scrollbackRefsByLeafId: coalesce(scrollbackRefsByLeafId)
+  }
+}
+
+function findDuplicatePtyLeafReplacements(
+  snapshot: TerminalLayoutSnapshot
+): DuplicatePtyLeafReplacements {
+  const ptyIdsByLeafId = snapshot.ptyIdsByLeafId ?? {}
+  const rootLeafIds = collectLeafIds(snapshot.root)
+  const rootLeafIdSet = new Set(rootLeafIds)
+  const activeLeafId =
+    !snapshot.root || (snapshot.activeLeafId && rootLeafIdSet.has(snapshot.activeLeafId))
+      ? snapshot.activeLeafId
+      : null
+  const orderedLeafIds = [
+    ...rootLeafIds,
+    ...Object.keys(ptyIdsByLeafId).filter((leafId) => !rootLeafIdSet.has(leafId))
+  ]
+  const retainedLeafIdByPtyId = new Map<string, string>()
+  const retainedLeafIdByRemovedLeafId = new Map<string, string>()
+
+  for (const leafId of orderedLeafIds) {
+    const ptyId = ptyIdsByLeafId[leafId]
+    if (!ptyId) {
+      continue
+    }
+    const retainedLeafId = retainedLeafIdByPtyId.get(ptyId)
+    if (!retainedLeafId) {
+      retainedLeafIdByPtyId.set(ptyId, leafId)
+      continue
+    }
+    if (leafId === activeLeafId) {
+      retainedLeafIdByRemovedLeafId.set(retainedLeafId, leafId)
+      retainedLeafIdByPtyId.set(ptyId, leafId)
+      continue
+    }
+    retainedLeafIdByRemovedLeafId.set(leafId, retainedLeafId)
+  }
+
+  return { orderedLeafIds, retainedLeafIdByRemovedLeafId }
+}
+
+function resolveOwnedActiveLeafId(
+  rootLeafIds: readonly string[],
+  activeLeafId: string | null,
+  ptyIdsByLeafId: Record<string, string> | undefined
+): string | null {
+  const hasBinding = (leafId: string): boolean =>
+    Boolean(ptyIdsByLeafId && Object.prototype.hasOwnProperty.call(ptyIdsByLeafId, leafId))
+  if (rootLeafIds.length === 0) {
+    const boundLeafIds = Object.keys(ptyIdsByLeafId ?? {})
+    if (activeLeafId) {
+      return activeLeafId
+    }
+    return boundLeafIds.length === 1 ? boundLeafIds[0] : null
+  }
+
+  if (activeLeafId && rootLeafIds.includes(activeLeafId)) {
+    return activeLeafId
+  }
+  const hasBoundRootLeaf = rootLeafIds.some(hasBinding)
+  return hasBoundRootLeaf ? (rootLeafIds.find(hasBinding) ?? null) : (rootLeafIds[0] ?? null)
+}
+
+export function normalizeTerminalLayoutPtyOwnership(
+  snapshot: TerminalLayoutSnapshot
+): TerminalLayoutPtyOwnershipNormalization {
+  const { orderedLeafIds, retainedLeafIdByRemovedLeafId } =
+    findDuplicatePtyLeafReplacements(snapshot)
+  if (retainedLeafIdByRemovedLeafId.size === 0) {
+    return { snapshot, changed: false }
+  }
+
+  // Why: one live PTY has one renderer surface; retaining both leaves races input, resize, and teardown.
+  const removedLeafIds = new Set<string>()
+  for (const [removedLeafId, retainedLeafId] of retainedLeafIdByRemovedLeafId) {
+    if (removedLeafId !== retainedLeafId) {
+      removedLeafIds.add(removedLeafId)
+    }
+  }
+  const root = snapshot.root
+    ? pruneLeaves(snapshot.root, retainedLeafIdByRemovedLeafId, new Set())
+    : null
+  const mappedActiveLeafId = snapshot.activeLeafId
+    ? resolveRetainedLeafId(snapshot.activeLeafId, retainedLeafIdByRemovedLeafId)
+    : snapshot.activeLeafId
+  const ptyIdsByLeafId = coalesceLeafRecord(snapshot.ptyIdsByLeafId, retainedLeafIdByRemovedLeafId)
+  const rootLeafIds = collectLeafIds(root)
+  const activeLeafId = resolveOwnedActiveLeafId(rootLeafIds, mappedActiveLeafId, ptyIdsByLeafId)
+  const { buffersByLeafId, scrollbackRefsByLeafId } = coalesceScrollbackRecords(
+    snapshot.buffersByLeafId,
+    snapshot.scrollbackRefsByLeafId,
+    retainedLeafIdByRemovedLeafId,
+    orderedLeafIds
+  )
+  const titlesByLeafId = coalesceLeafRecord(snapshot.titlesByLeafId, retainedLeafIdByRemovedLeafId)
+  const {
+    ptyIdsByLeafId: _oldPtyIdsByLeafId,
+    buffersByLeafId: _oldBuffersByLeafId,
+    scrollbackRefsByLeafId: _oldScrollbackRefsByLeafId,
+    titlesByLeafId: _oldTitlesByLeafId,
+    ...snapshotWithoutLeafRecords
+  } = snapshot
+
+  return {
+    snapshot: {
+      ...snapshotWithoutLeafRecords,
+      root,
+      activeLeafId,
+      expandedLeafId:
+        snapshot.expandedLeafId &&
+        !removedLeafIds.has(snapshot.expandedLeafId) &&
+        rootLeafIds.includes(snapshot.expandedLeafId)
+          ? snapshot.expandedLeafId
+          : null,
+      ...(ptyIdsByLeafId ? { ptyIdsByLeafId } : {}),
+      ...(buffersByLeafId ? { buffersByLeafId } : {}),
+      ...(scrollbackRefsByLeafId ? { scrollbackRefsByLeafId } : {}),
+      ...(titlesByLeafId ? { titlesByLeafId } : {})
+    },
+    changed: true
+  }
+}
+
+export function resolveTerminalLayoutPtyOwnershipTransfers(
+  source: TerminalLayoutSnapshot,
+  normalized: TerminalLayoutSnapshot
+): { removedLeafId: string; retainedLeafId: string; ptyId: string }[] {
+  const retainedLeafIdByPtyId = new Map(
+    Object.entries(normalized.ptyIdsByLeafId ?? {}).map(([leafId, ptyId]) => [ptyId, leafId])
+  )
+  const transfers: { removedLeafId: string; retainedLeafId: string; ptyId: string }[] = []
+  for (const [removedLeafId, ptyId] of Object.entries(source.ptyIdsByLeafId ?? {})) {
+    const retainedLeafId = retainedLeafIdByPtyId.get(ptyId)
+    if (retainedLeafId && retainedLeafId !== removedLeafId) {
+      transfers.push({ removedLeafId, retainedLeafId, ptyId })
+    }
+  }
+  return transfers
+}
diff --git a/src/renderer/src/runtime/web-session-tabs-sync.test.ts b/src/renderer/src/runtime/web-session-tabs-sync.test.ts
index fcdfbddecb3..e406d8644f0 100644
--- a/src/renderer/src/runtime/web-session-tabs-sync.test.ts
+++ b/src/renderer/src/runtime/web-session-tabs-sync.test.ts
@@ -55,6 +55,7 @@ const ENV = 'web-env-1'
 const NOW = 1_700_000_000_000
 const LEAF_ID = '11111111-1111-4111-8111-111111111111'
 const SECOND_LEAF_ID = '22222222-2222-4222-8222-222222222222'
+const THIRD_LEAF_ID = '33333333-3333-4333-8333-333333333333'
 const HOST_SURFACE_ID = `host-tab-1::${LEAF_ID}`
 
 function makeState(overrides: Partial<WebSessionTabsSyncState> = {}): WebSessionTabsSyncState {
@@ -2338,6 +2339,79 @@ describe('applyWebSessionTabsSnapshot', () => {
     expect(patch.activeTabIdByWorktree?.[WT]).toBe(mirroredId)
   })
 
+  it('deduplicates mirrored leaves that claim the same remote PTY', () => {
+    const parentLayout = {
+      root: {
+        type: 'split' as const,
+        direction: 'horizontal' as const,
+        first: { type: 'leaf' as const, leafId: LEAF_ID },
+        second: { type: 'leaf' as const, leafId: SECOND_LEAF_ID }
+      },
+      activeLeafId: SECOND_LEAF_ID,
+      expandedLeafId: null
+    }
+    const patch = applyWebSessionTabsSnapshot(
+      makeState(),
+      makeSnapshot([
+        {
+          type: 'terminal',
+          id: HOST_SURFACE_ID,
+          title: 'stale mirror',
+          parentTabId: 'host-tab-1',
+          leafId: LEAF_ID,
+          parentLayout,
+          isActive: false,
+          status: 'ready',
+          terminal: 'terminal-1',
+          agentStatus: {
+            state: 'working',
+            prompt: 'stale duplicate',
+            updatedAt: NOW - 100,
+            stateStartedAt: NOW - 1_000,
+            agentType: 'pi',
+            paneKey: makePaneKey('host-tab-1', LEAF_ID),
+            terminalTitle: 'Pi ready',
+            stateHistory: []
+          }
+        },
+        {
+          type: 'terminal',
+          id: `host-tab-1::${SECOND_LEAF_ID}`,
+          title: 'Pi ready',
+          parentTabId: 'host-tab-1',
+          leafId: SECOND_LEAF_ID,
+          parentLayout,
+          isActive: true,
+          status: 'ready',
+          terminal: 'terminal-1',
+          launchAgent: 'omp'
+        }
+      ]),
+      ENV,
+      NOW
+    ) as Partial<WebSessionTabsSyncState>
+
+    const mirroredId = patch.tabsByWorktree?.[WT]?.[0]?.id
+    expect(patch.ptyIdsByTabId?.[mirroredId!]).toEqual(['remote:web-env-1@@terminal-1'])
+    expect(patch.terminalLayoutsByTabId?.[mirroredId!]).toEqual({
+      root: { type: 'leaf', leafId: SECOND_LEAF_ID },
+      activeLeafId: SECOND_LEAF_ID,
+      expandedLeafId: null,
+      ptyIdsByLeafId: {
+        [SECOND_LEAF_ID]: 'remote:web-env-1@@terminal-1'
+      }
+    })
+    expect(Object.keys(patch.agentStatusByPaneKey ?? {})).toEqual([
+      makePaneKey(mirroredId!, SECOND_LEAF_ID)
+    ])
+    expect(patch.agentStatusByPaneKey?.[makePaneKey(mirroredId!, SECOND_LEAF_ID)]).toMatchObject({
+      prompt: 'stale duplicate',
+      paneKey: makePaneKey(mirroredId!, SECOND_LEAF_ID),
+      agentType: 'omp',
+      terminalTitle: 'OMP ready'
+    })
+  })
+
   it('does not let repeated remote terminal status snapshots steal local tab focus', () => {
     const agentTabId = toWebTerminalSurfaceTabId('host-tab-1')
     const shellTabId = toWebTerminalSurfaceTabId('host-tab-2')
@@ -3746,9 +3820,19 @@ describe('applyWebSessionTabsSnapshot', () => {
         {
           type: 'terminal',
           id: `host-tab-1::${SECOND_LEAF_ID}`,
-          title: 'pending shell',
+          title: 'duplicate ready shell',
           parentTabId: 'host-tab-1',
           leafId: SECOND_LEAF_ID,
+          isActive: false,
+          status: 'ready',
+          terminal: 'terminal-1'
+        },
+        {
+          type: 'terminal',
+          id: `host-tab-1::${THIRD_LEAF_ID}`,
+          title: 'pending shell',
+          parentTabId: 'host-tab-1',
+          leafId: THIRD_LEAF_ID,
           isActive: true,
           status: 'pending-handle',
           terminal: null
@@ -3770,7 +3854,12 @@ describe('applyWebSessionTabsSnapshot', () => {
     ])
     expect(patch.ptyIdsByTabId?.[mirroredId!]).toEqual(['remote:web-env-1@@terminal-1'])
     expect(patch.terminalLayoutsByTabId?.[mirroredId!]).toMatchObject({
-      activeLeafId: SECOND_LEAF_ID,
+      root: {
+        type: 'split',
+        first: { type: 'leaf', leafId: LEAF_ID },
+        second: { type: 'leaf', leafId: THIRD_LEAF_ID }
+      },
+      activeLeafId: THIRD_LEAF_ID,
       ptyIdsByLeafId: {
         [LEAF_ID]: 'remote:web-env-1@@terminal-1'
       }
diff --git a/src/renderer/src/runtime/web-session-tabs-sync.ts b/src/renderer/src/runtime/web-session-tabs-sync.ts
index ca5f56a2ae0..cafe434aa94 100644
--- a/src/renderer/src/runtime/web-session-tabs-sync.ts
+++ b/src/renderer/src/runtime/web-session-tabs-sync.ts
@@ -32,6 +32,7 @@ import type { OpenFile } from '../store/slices/editor'
 import { isTerminalLeafId, makePaneKey, parsePaneKey } from '../../../shared/stable-pane-id'
 import { getRemoteRuntimePtyEnvironmentId, toRemoteRuntimePtyId } from './runtime-terminal-stream'
 import { sanitizeTerminalLayoutPaneTitlesForLabels } from '@/lib/terminal-pane-title-sanitization'
+import { normalizeTerminalLayoutPtyOwnership } from '@/components/terminal-pane/terminal-layout-pty-ownership'
 import {
   getExplicitRuntimeEnvironmentIdForWorktree,
   getRuntimeSessionMirrorEnvironmentIds
@@ -116,6 +117,7 @@ type MirroredTerminalTab = {
   hostTabId: string
   ptyIds: string[]
   layout: TerminalLayoutSnapshot
+  retainedSurfaceByPrunedLeafId?: ReadonlyMap<string, TerminalSurface>
 }
 
 type MirroredBrowserTab = {
@@ -586,9 +588,28 @@ function buildMirroredTerminalTabs(
         .filter((surface): surface is ReadyTerminalSurface => surface.status === 'ready')
         .map((surface) => [surface.leafId, toRemoteRuntimePtyId(surface.terminal, environmentId)])
     )
-    const ptyIds = surfaces
-      .map((surface) => ptyIdsByLeafId[surface.leafId]!)
-      .filter((ptyId): ptyId is string => typeof ptyId === 'string' && ptyId.length > 0)
+    const layout = normalizeTerminalLayoutPtyOwnership(
+      chooseRemoteTerminalLayout(surfaces, ptyIdsByLeafId, existingLayout, requestedActiveLeafId)
+    ).snapshot
+    const layoutPtyEntries = Object.entries(layout.ptyIdsByLeafId ?? {})
+    const ptyIds = layoutPtyEntries.map(([, ptyId]) => ptyId)
+    let retainedSurfaceByPrunedLeafId: Map<string, TerminalSurface> | undefined
+    if (layoutPtyEntries.length < Object.keys(ptyIdsByLeafId).length) {
+      const retainedLeafIdByPtyId = new Map(
+        layoutPtyEntries.map(([leafId, ptyId]) => [ptyId, leafId])
+      )
+      const surfaceByLeafId = new Map(surfaces.map((surface) => [surface.leafId, surface]))
+      retainedSurfaceByPrunedLeafId = new Map()
+      for (const [leafId, ptyId] of Object.entries(ptyIdsByLeafId)) {
+        const retainedLeafId = retainedLeafIdByPtyId.get(ptyId)
+        if (retainedLeafId && retainedLeafId !== leafId) {
+          const retainedSurface = surfaceByLeafId.get(retainedLeafId)
+          if (retainedSurface) {
+            retainedSurfaceByPrunedLeafId.set(leafId, retainedSurface)
+          }
+        }
+      }
+    }
     const launchAgent =
       activeSurface.launchAgent ?? surfaces.find((surface) => surface.launchAgent)?.launchAgent
     const ownerAgent = resolvePaneAgentOwner({
@@ -643,34 +664,33 @@ function buildMirroredTerminalTabs(
       },
       hostTabId: parentTabId,
       ptyIds,
-      layout: chooseRemoteTerminalLayout(
-        surfaces,
-        ptyIdsByLeafId,
-        existingLayout,
-        requestedActiveLeafId
-      )
+      layout,
+      ...(retainedSurfaceByPrunedLeafId ? { retainedSurfaceByPrunedLeafId } : {})
     }
   })
 }
 
-function toMirroredPaneKey(surface: TerminalSurface): string | null {
-  if (!isTerminalLeafId(surface.leafId)) {
+function toMirroredPaneKey(surface: TerminalSurface, leafId = surface.leafId): string | null {
+  if (!isTerminalLeafId(leafId)) {
     return null
   }
-  return makePaneKey(toWebTerminalSurfaceTabId(surface.parentTabId), surface.leafId)
+  return makePaneKey(toWebTerminalSurfaceTabId(surface.parentTabId), leafId)
 }
 
 /** Normalises and mirrors agent status updates from the host payload, preserving ownership metadata. */
-function remapHostAgentStatus(surface: TerminalSurface): AgentStatusEntry | null {
+function remapHostAgentStatus(
+  surface: TerminalSurface,
+  retainedSurface?: TerminalSurface
+): AgentStatusEntry | null {
   if (!surface.agentStatus) {
     return null
   }
-  const paneKey = toMirroredPaneKey(surface)
+  const paneKey = toMirroredPaneKey(surface, retainedSurface?.leafId)
   if (!paneKey) {
     return null
   }
   const ownerAgent = resolvePaneAgentOwner({
-    launchAgent: surface.launchAgent,
+    launchAgent: retainedSurface?.launchAgent ?? surface.launchAgent,
     hookAgent: surface.agentStatus.agentType
   })
   return {
@@ -690,6 +710,7 @@ function buildMirroredAgentStatusPatch(
   state: WebSessionTabsSyncState,
   currentTerminalTabs: readonly TerminalTab[],
   terminalSurfaceTabs: readonly TerminalSurface[],
+  mirroredTerminalTabs: readonly MirroredTerminalTab[],
   now: number
 ): Pick<WebSessionTabsSyncState, 'agentStatusByPaneKey' | 'agentStatusEpoch' | 'sortEpoch'> | null {
   const mirroredTabIds = new Set<string>()
@@ -706,13 +727,28 @@ function buildMirroredAgentStatusPatch(
     return null
   }
 
+  let retainedSurfaceByHostTabAndPrunedLeafId:
+    | Map<string, ReadonlyMap<string, TerminalSurface>>
+    | undefined
+  for (const entry of mirroredTerminalTabs) {
+    if (entry.retainedSurfaceByPrunedLeafId) {
+      retainedSurfaceByHostTabAndPrunedLeafId ??= new Map()
+      retainedSurfaceByHostTabAndPrunedLeafId.set(
+        entry.hostTabId,
+        entry.retainedSurfaceByPrunedLeafId
+      )
+    }
+  }
   const nextByPaneKey = new Map<string, AgentStatusEntry>()
   for (const surface of terminalSurfaceTabs) {
-    const entry = remapHostAgentStatus(surface)
+    const retainedSurface = retainedSurfaceByHostTabAndPrunedLeafId
+      ?.get(surface.parentTabId)
+      ?.get(surface.leafId)
+    const entry = remapHostAgentStatus(surface, retainedSurface)
     if (!entry) {
       continue
     }
-    const existing = state.agentStatusByPaneKey[entry.paneKey]
+    const existing = nextByPaneKey.get(entry.paneKey) ?? state.agentStatusByPaneKey[entry.paneKey]
     // Why: keep fresher OSC state while taking remapped ownership metadata from the authoritative host snapshot.
     const hostIdentityPredatesCurrentTurn =
       existing !== undefined &&
@@ -2523,6 +2559,7 @@ export function applyWebSessionTabsSnapshot(
     state,
     currentTerminalTabs,
     terminalSurfaceTabs,
+    mirroredTerminalTabs,
     now
   )
 
diff --git a/src/renderer/src/store/slices/terminal-layout-pty-ownership.test.ts b/src/renderer/src/store/slices/terminal-layout-pty-ownership.test.ts
new file mode 100644
index 00000000000..41948d42a5d
--- /dev/null
+++ b/src/renderer/src/store/slices/terminal-layout-pty-ownership.test.ts
@@ -0,0 +1,235 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+import { makePaneKey } from '../../../../shared/stable-pane-id'
+import { getDefaultWorkspaceSession } from '../../../../shared/constants'
+import {
+  resetAgentPaneAuthorityAliasesForTests,
+  resolveAgentPaneAuthorityKey
+} from './agent-pane-authority'
+import { createTestStore, makeTab, makeWorktree, seedStore } from './store-test-helpers'
+
+const LEAF_1 = '11111111-1111-4111-8111-111111111111'
+const LEAF_2 = '22222222-2222-4222-8222-222222222222'
+
+describe('setTabLayout PTY ownership', () => {
+  beforeEach(() => {
+    resetAgentPaneAuthorityAliasesForTests()
+  })
+
+  it('normalizes duplicate PTY surfaces at the renderer state boundary', () => {
+    const store = createTestStore()
+
+    store.getState().setTabLayout('tab-1', {
+      root: {
+        type: 'split',
+        direction: 'vertical',
+        first: { type: 'leaf', leafId: LEAF_1 },
+        second: { type: 'leaf', leafId: LEAF_2 }
+      },
+      activeLeafId: LEAF_2,
+      expandedLeafId: null,
+      ptyIdsByLeafId: {
+        [LEAF_1]: 'pty-agent',
+        [LEAF_2]: 'pty-agent'
+      }
+    })
+
+    expect(store.getState().terminalLayoutsByTabId['tab-1']).toEqual({
+      root: { type: 'leaf', leafId: LEAF_2 },
+      activeLeafId: LEAF_2,
+      expandedLeafId: null,
+      ptyIdsByLeafId: { [LEAF_2]: 'pty-agent' }
+    })
+  })
+
+  it('preserves valid live layouts and legacy leaf ids by identity', () => {
+    const store = createTestStore()
+    const layout = {
+      root: {
+        type: 'split' as const,
+        direction: 'horizontal' as const,
+        first: { type: 'leaf' as const, leafId: 'pane:1' },
+        second: { type: 'leaf' as const, leafId: 'pane:2' }
+      },
+      activeLeafId: 'pane:2',
+      expandedLeafId: 'pane:1',
+      ptyIdsByLeafId: {
+        'pane:1': 'pty-local',
+        'pane:2': 'remote:env-1@@term_remote'
+      }
+    }
+
+    store.getState().setTabLayout('tab-1', layout)
+
+    expect(store.getState().terminalLayoutsByTabId['tab-1']).toBe(layout)
+  })
+
+  it('moves live and future pane authority onto the retained PTY leaf', () => {
+    const store = createTestStore()
+    const removedPaneKey = makePaneKey('tab-1', LEAF_1)
+    const retainedPaneKey = makePaneKey('tab-1', LEAF_2)
+    store.getState().setAgentStatus(removedPaneKey, {
+      state: 'working',
+      prompt: 'before repair',
+      agentType: 'codex'
+    })
+
+    store.getState().setTabLayout('tab-1', {
+      root: {
+        type: 'split',
+        direction: 'vertical',
+        first: { type: 'leaf', leafId: LEAF_1 },
+        second: { type: 'leaf', leafId: LEAF_2 }
+      },
+      activeLeafId: LEAF_2,
+      expandedLeafId: null,
+      ptyIdsByLeafId: {
+        [LEAF_1]: 'pty-agent',
+        [LEAF_2]: 'pty-agent'
+      }
+    })
+
+    expect(store.getState().agentStatusByPaneKey[removedPaneKey]).toBeUndefined()
+    expect(store.getState().agentStatusByPaneKey[retainedPaneKey]?.prompt).toBe('before repair')
+    expect(resolveAgentPaneAuthorityKey(removedPaneKey)).toBe(retainedPaneKey)
+
+    store.getState().setAgentStatus(removedPaneKey, {
+      state: 'working',
+      prompt: 'after repair',
+      agentType: 'codex'
+    })
+    expect(store.getState().agentStatusByPaneKey[retainedPaneKey]?.prompt).toBe('after repair')
+  })
+
+  it('moves hydrated pane authority onto the retained PTY leaf', () => {
+    const store = createTestStore()
+    const worktreeId = 'repo1::/wt-1'
+    const removedPaneKey = makePaneKey('tab-1', LEAF_1)
+    const retainedPaneKey = makePaneKey('tab-1', LEAF_2)
+    seedStore(store, {
+      worktreesByRepo: {
+        repo1: [makeWorktree({ id: worktreeId, repoId: 'repo1', path: '/wt-1' })]
+      }
+    })
+    store.getState().setAgentStatus(removedPaneKey, {
+      state: 'working',
+      prompt: 'before hydration',
+      agentType: 'codex'
+    })
+
+    store.getState().hydrateWorkspaceSession({
+      ...getDefaultWorkspaceSession(),
+      activeRepoId: 'repo1',
+      activeWorktreeId: worktreeId,
+      activeTabId: 'tab-1',
+      tabsByWorktree: {
+        [worktreeId]: [makeTab({ id: 'tab-1', worktreeId, ptyId: 'pty-agent' })]
+      },
+      terminalLayoutsByTabId: {
+        'tab-1': {
+          root: {
+            type: 'split',
+            direction: 'vertical',
+            first: { type: 'leaf', leafId: LEAF_1 },
+            second: { type: 'leaf', leafId: LEAF_2 }
+          },
+          activeLeafId: LEAF_2,
+          expandedLeafId: null,
+          ptyIdsByLeafId: {
+            [LEAF_1]: 'pty-agent',
+            [LEAF_2]: 'pty-agent'
+          }
+        }
+      }
+    })
+
+    expect(store.getState().agentStatusByPaneKey[removedPaneKey]).toBeUndefined()
+    expect(store.getState().agentStatusByPaneKey[retainedPaneKey]?.prompt).toBe('before hydration')
+    expect(resolveAgentPaneAuthorityKey(removedPaneKey)).toBe(retainedPaneKey)
+  })
+
+  it('does not steal authority from a pane that was already detached to another tab', () => {
+    const store = createTestStore()
+    const removedPaneKey = makePaneKey('source-tab', LEAF_1)
+    const retainedPaneKey = makePaneKey('source-tab', LEAF_2)
+    const detachedPaneKey = makePaneKey('target-tab', LEAF_1)
+    store.getState().setTabLayout('target-tab', {
+      root: { type: 'leaf', leafId: LEAF_1 },
+      activeLeafId: LEAF_1,
+      expandedLeafId: null,
+      ptyIdsByLeafId: { [LEAF_1]: 'pty-detached' }
+    })
+    store.getState().transferAgentPaneAuthority({
+      fromPaneKey: removedPaneKey,
+      toPaneKey: detachedPaneKey,
+      ptyId: 'pty-detached'
+    })
+
+    store.getState().setTabLayout('source-tab', {
+      root: {
+        type: 'split',
+        direction: 'vertical',
+        first: { type: 'leaf', leafId: LEAF_1 },
+        second: { type: 'leaf', leafId: LEAF_2 }
+      },
+      activeLeafId: LEAF_2,
+      expandedLeafId: null,
+      ptyIdsByLeafId: {
+        [LEAF_1]: 'pty-detached',
+        [LEAF_2]: 'pty-detached'
+      }
+    })
+
+    expect(resolveAgentPaneAuthorityKey(removedPaneKey)).toBe(detachedPaneKey)
+    expect(resolveAgentPaneAuthorityKey(detachedPaneKey)).toBe(detachedPaneKey)
+    expect(resolveAgentPaneAuthorityKey(retainedPaneKey)).toBe(retainedPaneKey)
+  })
+
+  it('repairs duplicate legacy leaf ownership without throwing', () => {
+    const store = createTestStore()
+
+    expect(() =>
+      store.getState().setTabLayout('tab-1', {
+        root: {
+          type: 'split',
+          direction: 'horizontal',
+          first: { type: 'leaf', leafId: 'pane:1' },
+          second: { type: 'leaf', leafId: 'pane:2' }
+        },
+        activeLeafId: 'pane:2',
+        expandedLeafId: null,
+        ptyIdsByLeafId: {
+          'pane:1': 'pty-agent',
+          'pane:2': 'pty-agent'
+        }
+      })
+    ).not.toThrow()
+    expect(store.getState().terminalLayoutsByTabId['tab-1']).toEqual({
+      root: { type: 'leaf', leafId: 'pane:2' },
+      activeLeafId: 'pane:2',
+      expandedLeafId: null,
+      ptyIdsByLeafId: { 'pane:2': 'pty-agent' }
+    })
+  })
+
+  it('scopes ownership to a tab so detach handoffs can share a PTY across tabs', () => {
+    const store = createTestStore()
+    const sourceLayout = {
+      root: { type: 'leaf' as const, leafId: LEAF_1 },
+      activeLeafId: LEAF_1,
+      expandedLeafId: null,
+      ptyIdsByLeafId: { [LEAF_1]: 'pty-detached' }
+    }
+    const targetLayout = {
+      root: { type: 'leaf' as const, leafId: LEAF_2 },
+      activeLeafId: LEAF_2,
+      expandedLeafId: null,
+      ptyIdsByLeafId: { [LEAF_2]: 'pty-detached' }
+    }
+
+    store.getState().setTabLayout('source-tab', sourceLayout)
+    store.getState().setTabLayout('target-tab', targetLayout)
+
+    expect(store.getState().terminalLayoutsByTabId['source-tab']).toBe(sourceLayout)
+    expect(store.getState().terminalLayoutsByTabId['target-tab']).toBe(targetLayout)
+  })
+})
diff --git a/src/renderer/src/store/slices/terminals.ts b/src/renderer/src/store/slices/terminals.ts
index 2ff1dbc3c83..210c2f35537 100644
--- a/src/renderer/src/store/slices/terminals.ts
+++ b/src/renderer/src/store/slices/terminals.ts
@@ -31,6 +31,7 @@ import {
 import { deriveGeneratedTabTitle } from '../../../../shared/agent-tab-title'
 import { isDecorativeAgentTitleFrameChange } from '../../../../shared/agent-decorative-title-signature'
 import {
+  isTerminalLeafId,
   makePaneKey,
   parseLegacyNumericPaneKey,
   parsePaneKey
@@ -87,6 +88,10 @@ import {
   normalizeTerminalLayoutSnapshot,
   resolvePtyBoundActiveLeafId
 } from '@/components/terminal-pane/terminal-layout-leaf-ids'
+import {
+  normalizeTerminalLayoutPtyOwnership,
+  resolveTerminalLayoutPtyOwnershipTransfers
+} from '@/components/terminal-pane/terminal-layout-pty-ownership'
 import { shutdownBufferCaptures } from '@/components/terminal-pane/shutdown-buffer-captures'
 import { callRuntimeRpc } from '@/runtime/runtime-rpc-client'
 import { parseRemoteRuntimePtyId, toRemoteRuntimePtyId } from '@/runtime/runtime-terminal-stream'
@@ -121,6 +126,7 @@ import { resolveTerminalWorktreeRoute } from '@/lib/terminal-worktree-route'
 import { resolveWorktreeOperationRouteResult } from '@/lib/worktree-operation-route'
 import { getLocalProjectExecutionRuntimeContext } from '@/lib/local-preflight-context'
 import type { NativeChatLaunchDraft, NativeChatLaunchPrompt } from '@/lib/native-chat-launch-prompt'
+import { resolveAgentPaneAuthorityKey } from './agent-pane-authority'
 import {
   addAdditionalValidWorkspaceKeys,
   type WorkspaceSessionHydrationOptions
@@ -869,6 +875,48 @@ function replaceHydratedRecordKeys<T>(
   }
 }
 
+type TerminalLayoutPtyOwnershipTransfer = ReturnType<
+  typeof resolveTerminalLayoutPtyOwnershipTransfers
+>[number]
+
+function transferNormalizedTerminalLayoutPtyOwnership(
+  state: Pick<AppState, 'terminalLayoutsByTabId' | 'transferAgentPaneAuthority'>,
+  tabId: string,
+  transfers: readonly TerminalLayoutPtyOwnershipTransfer[]
+): void {
+  if (transfers.length === 0) {
+    return
+  }
+  const ptyIdsOwnedByOtherTabs = new Set<string>()
+  for (const [candidateTabId, layout] of Object.entries(state.terminalLayoutsByTabId)) {
+    if (candidateTabId === tabId) {
+      continue
+    }
+    for (const ptyId of Object.values(layout.ptyIdsByLeafId ?? {})) {
+      ptyIdsOwnedByOtherTabs.add(ptyId)
+    }
+  }
+  for (const { removedLeafId, retainedLeafId, ptyId } of transfers) {
+    if (
+      !isTerminalLeafId(removedLeafId) ||
+      !isTerminalLeafId(retainedLeafId) ||
+      ptyIdsOwnedByOtherTabs.has(ptyId)
+    ) {
+      continue
+    }
+    const fromPaneKey = makePaneKey(tabId, removedLeafId)
+    const currentOwner = parsePaneKey(resolveAgentPaneAuthorityKey(fromPaneKey))
+    if (currentOwner && currentOwner.tabId !== tabId) {
+      continue
+    }
+    state.transferAgentPaneAuthority({
+      fromPaneKey,
+      toPaneKey: makePaneKey(tabId, retainedLeafId),
+      ptyId
+    })
+  }
+}
+
 function targetScopedWorkspaceHydrationPatch(
   state: AppState,
   hydrated: WorkspaceHydrationPatch,
@@ -3514,15 +3562,24 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
   },
 
   setTabLayout: (tabId, layout) => {
+    let ownershipTransfers: ReturnType<typeof resolveTerminalLayoutPtyOwnershipTransfers> = []
     set((s) => {
       const next = { ...s.terminalLayoutsByTabId }
       if (layout) {
-        next[tabId] = layout
+        const normalized = normalizeTerminalLayoutPtyOwnership(layout)
+        next[tabId] = normalized.snapshot
+        if (normalized.changed) {
+          ownershipTransfers = resolveTerminalLayoutPtyOwnershipTransfers(
+            layout,
+            normalized.snapshot
+          )
+        }
       } else {
         delete next[tabId]
       }
       return { terminalLayoutsByTabId: next }
     })
+    transferNormalizedTerminalLayoutPtyOwnership(get(), tabId, ownershipTransfers)
   },
 
   syncPaneDetachPtyOwnership: ({
@@ -3722,6 +3779,14 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
   },
 
   hydrateWorkspaceSession: (session, options) => {
+    const ownershipTransferTabIds = options?.replaceWorkspaceKeys
+      ? new Set(
+          options.replaceWorkspaceKeys.flatMap((workspaceKey) =>
+            (session.tabsByWorktree[workspaceKey] ?? []).map((tab) => tab.id)
+          )
+        )
+      : null
+    const ownershipTransfersByTabId = new Map<string, TerminalLayoutPtyOwnershipTransfer[]>()
     set((s) => {
       const runtimeSessionPlaceholders = buildRuntimeSessionPlaceholders({
         repos: s.repos,
@@ -3977,7 +4042,17 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
             .filter(([tabId]) => validTabIds.has(tabId))
             .map(([tabId, layout]) => {
               // Why: old sessions can contain renderer-local pane:1-style leaf ids; normalize before runtime/mobile surfaces read them.
-              const normalized = normalizeTerminalLayoutSnapshot(layout).snapshot
+              const normalization = normalizeTerminalLayoutSnapshot(layout)
+              const normalized = normalization.snapshot
+              if (
+                normalization.changed &&
+                (!ownershipTransferTabIds || ownershipTransferTabIds.has(tabId))
+              ) {
+                ownershipTransfersByTabId.set(
+                  tabId,
+                  resolveTerminalLayoutPtyOwnershipTransfers(layout, normalized)
+                )
+              }
               const tab = tabById.get(tabId)
               const sanitized = tab ? sanitizeTerminalLayoutPaneTitles(normalized, tab) : normalized
               const activeLeafId = sanitized.root
@@ -3995,6 +4070,9 @@ export const createTerminalSlice: StateCreator<AppState, [], [], TerminalSlice>
         ? targetScopedWorkspaceHydrationPatch(s, hydrated, session, options)
         : hydrated
     })
+    for (const [tabId, transfers] of ownershipTransfersByTabId) {
+      transferNormalizedTerminalLayoutPtyOwnership(get(), tabId, transfers)
+    }
   },
 
   reconnectPersistedTerminals: async (signal, options) => {

From b0c5bb558622f11c47e692064751c9181324678a Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Fri, 31 Jul 2026 18:28:35 +0000
Subject: [PATCH 23/23] release: v1.4.163-rc.3

---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index 1a05084eabc..466aec66383 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "orca",
-  "version": "1.4.163-rc.1",
+  "version": "1.4.163-rc.3",
   "description": "Next-gen IDE for parallel agentic development",
   "homepage": "https://github.com/stablyai/orca",
   "author": "stablyai",